Skip to main content

Deposits and Withdrawals

Deposit Flow​

Deposits go through a two-step process: escrow funding, then keeper processing.

Step 1: Register and Fund Escrow​

The depositor registers a deposit address for the vault (one-time), which creates:

  • A DepositorPosition PDA (tracks shares and points)
  • A DepositAuthority PDA (controls the escrow account)
  • A USDC escrow token account (controlled by the deposit authority)

The depositor then transfers USDC to their escrow account using a standard SPL token transfer.

Step 2: Keeper Processes Deposit​

The keeper calls process_deposit_vault, which:

  1. Validates the vault and reserve are not paused
  2. Requires same-slot oracle valuation (skip for first deposit)
  3. Transfers USDC from escrow to the reserve treasury
  4. Deducts keeper incentive (sent to keeper's token account)
  5. Calculates oracle-priced USD value of the net deposit
  6. Mints vault shares proportional to NAV: shares = net_deposit * total_shares / total_value_usd
  7. Mints reserve shares: reserve_shares = net_deposit * reserve.total_shares / reserve.total_assets
  8. Accrues loyalty points on the depositor's existing position
  9. Updates all accounting (vault, reserve, position, performance)

First Deposit Protection​

When total_shares == 0, the first deposit sets the baseline: 1 USDC = 1 share (scaled to mint decimals). The oracle valuation check is skipped for bootstrap deposits.

Withdrawal Flow​

Withdrawals burn vault shares and return proportional assets from all active reserves.

  1. Depositor specifies how many shares to burn
  2. Program requires same-slot oracle valuation
  3. Shares are burned from the depositor's share token account
  4. For each active allocation with a mapped reserve:
    • Calculate proportional reserve shares to burn
    • Calculate native tokens owed from the reserve
    • Transfer tokens from reserve treasury to depositor's token account
    • Update reserve and position accounting
  5. Update vault accounting (total_shares, total_value_usd, cumulative_withdraw_usd)

The withdrawal is pro-rata across all reserves — if a vault has 60% USDC and 40% SOL, the depositor receives both USDC and SOL proportional to their share.

Rounding Safety​

All share-to-asset conversions use BigFraction math and round against the user (floor on withdrawals) to protect vault solvency. This is a standard defense against rounding exploits.