> For the complete documentation index, see [llms.txt](https://docs.buoy.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buoy.finance/protocol-deep-dive/request-lifecycle.md). # Request Lifecycle Deposits and withdrawals are **requests**: submitted by the user in one transaction, settled by the protocol in another, at a freshly computed NAV. This page walks through both state machines in full. ## Deposit lifecycle ``` ┌────────────┐ fulfilled at NAV ┌───────────┐ user tx ──────────► │ PENDING ├─────────────────────► │ FULFILLED │ (USDC escrowed) └─────┬──────┘ shares minted └───────────┘ │ │ after timeout, user cancels ▼ ┌───────────┐ │ CANCELLED │ (USDC returned) └───────────┘ ``` 1. **Request.** The user's transaction transfers USDC into the vault, records the request (amount, recipient, minimum shares), and pays the fixed HYPE fee. On a vault with [deposit limits](/for-vault-leaders/deposit-limits.md) the request is first checked against them — the whitelist exactly, the leader share and TVL cap as a projection on the vault's cached value — and a request that cannot pass reverts outright: no fee paid, nothing queued. 2. **Fulfillment.** The settlement service computes the vault's NAV ([with consistency guarantees](/protocol-deep-dive/nav-and-share-price.md)) and settles: the high-water-mark fee is crystallized if the share price set a new high, shares are minted to the recipient at the net share price, and the new USDC is bridged to the vault's HyperCore account to be traded. If the resulting shares would fall below the user's minimum, the settlement reverts instead. The deposit limits are re-checked here against the live NAV; a deposit that no longer fits is skipped with the reason on-chain and stays Pending — the service re-checks it whenever the vault's state changes, and the user can cancel it after the timeout. 3. **Cancellation.** If the request is still pending after the timeout (30 minutes), the user may cancel and reclaim the full USDC amount. The HYPE fee is not refunded. Deposits are operationally simple — the vault is *receiving* money — which is why they settle in a minute or two. ## Withdrawal lifecycle ``` ┌─────────┐ locked at NAV ┌────────┐ vault has cash ┌───────────┐ user tx ───────► │ PENDING ├───────────────► │ LOCKED ├────────────────► │ FULFILLED │ (shares escrowed)└────┬────┘ shares burned, └───┬────┘ USDC paid └───────────┘ │ owed USDC fixed │ │ cancel after timeout │ cancel after timeout ▼ ▼ ┌───────────┐ ┌───────────┐ │ CANCELLED │ │ CANCELLED │ │ (shares │ │ (shares │ │ returned)│ │ re-minted)│ └───────────┘ └───────────┘ ``` 1. **Request.** The user's shares are escrowed; the request records the share amount and the minimum USDC out. 2. **Lock.** At the next consistent NAV, the vault **fixes the payout**: shares are burned and the owed USDC amount is recorded as an on-chain obligation. From here the user's money is a fixed dollar claim — later trading doesn't change it (the obligation is also subtracted from NAV so remaining holders aren't diluted). If the current NAV would put the payout below the user's minimum, the lock waits instead of executing. 3. **Settlement.** The vault can pay only when its EVM-side USDC covers all obligations. If it's short, the settlement service raises cash in escalating order: bridge free spot USDC → free perp margin → sell spot holdings → partially close perp positions → close HIP-3 positions and pull idle HIP-3 margin. 4. **Fulfillment.** Once covered, the owed USDC is transferred to the user. ### The two hard cases * **Raising the cash realized a loss.** If, after exhausting every source it can safely convert, the proceeds genuinely fall short of the locked amount — a NAV drop, closing costs, slippage — the obligation may be **reduced** to reflect the realized loss, but never below the user's quoted minimum out. This is the withdrawal bearing its fair share of a real loss, not a penalty. * **The vault can't raise enough cash at all.** If everything the service can safely convert still doesn't cover even the user's minimum (capital locked in exposure it can't unwind), the withdrawal **waits** and the Leader is expected to free capital — see [Liquidity & Withdrawals](/for-vault-leaders/liquidity-and-withdrawals.md). The obligation remains on-chain; settlement retries continuously. ### Cancellation After the timeout (30 minutes), the user can cancel at either stage: * **Pending** → escrowed shares are returned untouched. * **Locked** → the obligation is released and the user's **original Buoys are re-minted** — they're restored to their prior share position and can retry. ## Design properties worth noting * **Every request settles at a NAV computed after the request existed** — no user can trade against the vault with stale information, and no settlement can execute against a stale valuation (the nonce guard). * **Requests are independent.** There's no queue coupling: one user's enormous withdrawal doesn't reprice or block another's deposit beyond the shared liquidity it consumes. * **Users can hold multiple open requests** per vault, of either kind, simultaneously. * **Nothing can be stranded.** Every state has an exit: fulfillment, or a user-initiated cancel after the timeout. * **Limits gate entry only.** A vault's deposit limits are consulted on the deposit path and nowhere on the withdrawal path — the policy that holds them can refuse a deposit but cannot touch, delay or block an exit. ## Batched settlement Requests for the same vault are settled together where possible: one transaction, one NAV snapshot, many requests. The vault's interaction nonce is checked once at entry, so every request in the batch prices against the same verified state. Individual items that can't settle — a request already cancelled, one whose slippage floor the current NAV can't meet, a malformed entry — are **skipped and reported on-chain** (`DepositSkipped` / `WithdrawalSkipped`, with the reason) instead of reverting the whole batch. One user's unsatisfiable floor therefore can't block everyone else's settlement, and the skipped request simply stays open for the next attempt. If you're indexing Buoy, this is the practical consequence: a request that produced a `*Requested` event but no `*Fulfilled` event isn't necessarily failing — look for a `*Skipped` event to see why it's still waiting. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.buoy.finance/protocol-deep-dive/request-lifecycle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.