Skip to content

Vault Shares Math

Jump to bottom
wphan edited this page Feb 19, 2025 · 5 revisions

Vaults utilize shares to keep track of each user's pro-rata share of a vault's assets. sharess are unitless and are created/destroyed as users deposit, withdraw, pay (receive in the manager's case) fees.

Definitions

Term Definition
Vault Equity The current value of all vault assets in the vault's deposit asset (i.e. USDC)
Total Shares A variable stored on the Vault account, the total shares created in this vault
User Shares A variable stored on the Vault account, the total shares owned by VaultDepositors.
Vault Depositor Shares A variable stored on each VaultDepositor account, the number of shares owned by this depositor.
Protocol Shares A variable stored on the Protocol account, the total shares owned by the Protocol
Manager Shares Implied by total_shares - user_shares - protocol_shares
Share Price Implied by vault_equity / total_shares in vault's deposit asset

Calculations

For the calculations below, the following units are used:

  • shares: unitless
  • amount: in the vault deposit token (i.e. USDC)

On Deposit

Number of shares created for the VaultDepositor when they deposit amount into the vault:

shares = amount * total_shares / vault_equity

On Withdrawal Request

Users must make a withdrawal request first, then wait the vault's redeem_period before they can complete their withdrawal.

At request time, we calculate withdraw_shares for the VaultDepositor in order to withdraw withdraw_amount from the vault:

withdraw_shares = withdraw_amount * total_shares / vault_equity

On Cancel Withdrawal

After redeem_period has elapsed, the user can complete their withdrawal. The amount they ultimately receive is min(amount_0, amount_1) where amount_0 is the value of their withdrawal at request time, and amount_1 is the value of their withdrawal at the time when they finally perform the withdrawal. This means the user is exposed to losses experienced during the withdrawal window, and don't enjoy any of the profits made during the withdrawal window (these are instead distributed to other users in the vault)

If the user cancels their withdrawal request while the vault was in profit, we burn some of their shares in order to forfeit any pnl they would have earned during the withdrawal window.

To calculate the shares_lost burned at cancel time (withdraw_amount and withdraw_shares are from Request time):

current_value_in_shares = withdraw_amount * (total_shares - withdraw_shares) / (vault_equity - withdraw_amount)
shares_lost = withdraw_shares - current_value_in_shares

On Withdrawal

The user simply receives the min(amount_0, amount_1), and the shares calculated during the withdraw request are subtracted from total_shares and user_shares, effectively sharing any pnl earned by the withdrawing user with remaining depositors.

Example Scenario

Below are some examples of the shares carried out by the vault based on user interactions. The examples build on each other (i.e. user2 deposits after user1)

  1. user1 deposits 100_000 USDC 
total depositors = 1
vault equity = 100_000 USDC
total shares = 100_000_000_000
share price = 1 USDC
user1 shares = 100_000_000_000
  1. user2 deposits 200_000 USDC 
total depositors = 2
vault equity = 300_000 USDC
total shares = 300_000_000_000
share price = 1 USDC
user2 shares = 200_000_000_000
  1. vault is up 10% and user1 requests to withdraw 100% of their deposit
total depositors = 2
vault equity = 330_000 USDC
total shares = 300_000_000_000
share price = 1.1 USDC
user1 withdraw_shares = 100_000_000_000
user1 withdraw_amount = 110_000
  1. vault goes up 10% more, user1 cancels their request
total depositors = 2
vault equity = 363_000 USDC
total shares = 286_956_521_739
share price = 1.265 USDC

user1 shares = 86_956_521_739
user1 equity = 363_000 * 86_956_521_739 / 286_956_521_739 = 109,999.999999885 (roughly the amount at withdraw request time)

user2 shares = 200_000_000_000
user2 equity = 363_000 * 200_000_000_000 / 286_956_521_739 = 253,000.000000115

Total change in share price since inception is 26.5%, which matches user2's equity change, user1 forfeited their pnl during the withdrawal window.

  1. vault loses 10%
total depositors = 2
vault equity = 326_700 USDC
total shares = 286_956_521_739
share price = 1.1385 USDC

user1 shares = 86_956_521_739
user1 equity = 326_700 * 86_956_521_739 / 286_956_521_739 = 98,999.9999998965

user2 shares = 200_000_000_000
user2 equity = 326_700 * 200_000_000_000 / 286_956_521_739 = 227,700.0000001035
  1. user1 requests to withdraw all shares
total depositors = 2
vault equity = 326_700 USDC
total shares = 300_000_000_000
share price = 1.089 USDC
user1 withdraw_shares = 86_956_521_739
user1 withdraw_amount = 98_999.999999
  1. vault loses 50% by the time they complete withdraw user1 withdraw request. State of vault after user withdraws
total depositors = 1
vault equity = 113_850 USDC
total shares = 200_000_000_000
share price = 1.089 USDC

user1 shares after = 0
user1 amount withdrawn = 49_499.999999

user2 shares = 200_000_000_000
user2 equity = 113_850 * 200_000_000_000 / 200_000_000_000 = 113_850
Clone this wiki locally