Vault Depositors

A vault is a delegated trading pool: depositors provide capital, and a manager trades it under fixed withdrawal rules. This section covers the depositor side of that relationship, which is what you build against when you are writing a vault front end, an allocator dashboard, or a wallet integration. For the manager side, see Vault Managers.

Everything here runs through VaultClient from @velocity-exchange/vaults-sdk, the TypeScript client for the vaults program (vAuLTsyrvSfZRuRB3XgvkPwNGgYSs9YRYymVebLKoxR).

The VaultDepositor account

Every depositor holds one VaultDepositor account per vault. It is a PDA of the vault and the depositor’s authority, so its address is derivable without a lookup:


import { getVaultDepositorAddressSync, VAULT_PROGRAM_ID } from '@velocity-exchange/vaults-sdk';
 
const vaultDepositor = getVaultDepositorAddressSync(
  VAULT_PROGRAM_ID,
  vault,
  authority
);

The account tracks the depositor’s share balance, its share base (used for rebases), lifetime deposits and withdrawals, the cost basis profit share is measured against, and one pending withdraw request. It does not hold tokens. Tokens sit in the vault’s own Velocity user account, pooled with every other depositor’s.

initializeVaultDepositor(vault, authority?, payer?) creates the account. In a permissioned vault only the manager may create depositor accounts, and any other payer fails with PermissionedVault. In an open vault anyone can create one, and deposit creates it for you when you pass initVaultDepositor.

Deposits mint shares; withdrawals burn them. A depositor never owns a fixed token amount, only a fraction of the pool:


share price = vault equity / total shares

Vault equity is valued in the vault’s deposit asset (its spotMarketIndex), and for Trusted vaults it includes the manager’s outstanding borrow. The SDK exposes both sides:


// Price of one share, as a BigNum in the deposit asset.
const sharePrice = await vaultClient.calcVaultSharePrice({ vault });
 
// What this depositor could withdraw right now, net of profit share.
const equity = await vaultClient.calculateWithdrawableVaultDepositorEquity({
  vaultDepositor,
  vault,
});

calculateWithdrawableVaultDepositorEquity returns the value in the vault’s spot market (usually USDC or USDT). calculateWithdrawableVaultDepositorEquityInDepositAsset returns it in the deposit asset’s own units, which differ when the deposit asset is not the quote asset. Both subtract the profit share the manager would take, so they answer “what do I get” rather than “what is my gross claim”.

Share balances can be rebased. If vault equity falls far enough relative to the share count, the program divides every share balance by a common divisor and increments the vault’s shares_base. Your share count changes; your fraction of the vault does not. Depositor accounts resync on their next action, or on demand via the manager’s applyRebase.

Lifecycle

The depositor lifecycle is deposit, then request withdraw, then wait the redeem period, then withdraw. There is no direct withdrawal. A pending request blocks deposits, share transfers, tokenization, and further requests on the same account, so it is a state your integration has to render.

Deposit and withdraw Tokenized shares

What to check before depositing

Read these off the vault account and surface them, because the program will reject a deposit that violates any of them:

Field	Why it matters
`redeemPeriod`	Seconds you must wait between requesting and completing a withdrawal.
`maxTokens`	Capacity cap. A deposit that would push vault equity above it fails with `VaultIsAtCapacity`. `0` means uncapped.
`minDepositAmount`	Minimum deposit size. Below it, `InvalidVaultDeposit`. `0` means no minimum.
`permissioned`	If true, only the manager can create your depositor account.
`managementFee`, `profitShare`, `hurdleRate`	The fee policy, in percentage precision (1e6 = 100%).
`feeUpdateStatus`	Non-zero means a fee change is queued behind a timelock.
`vaultClass`	Trusted vaults let the manager move assets out of the vault.

Fees can rise. update_vault only lowers fees, but a manager can queue a raise with manager_update_fees behind a timelock of at least max(7 days, 2 x redeem period). Check feeUpdateStatus and read the pending policy with getFeeUpdate so depositors can exit before a higher fee installs. See Changing vault fees.

Vaults are not trustless. The manager trades pooled capital and depositors have no on-chain recourse against bad trading. In a Trusted-class vault the manager can also move assets out of the vault entirely, tracked only as a borrowed value. See Trusted vaults.

Vault Managers, the manager side and the fee rules
Manager operations, profit share, rebases, and the queued fee update
Velocity SDK, the core trading and positions SDK

Vault Depositors

The VaultDepositor account

Share accounting

Lifecycle

What to check before depositing

Related resources