Shares and exchange rates

A vault share is a slice of the jar. Its value is simple division: everything the vault is worth, divided by all the shares that exist.

Deposits. The first depositor sets the starting count. After that, each deposit gets shares in proportion to what is already there. Put in 1% of the jar's value and you get about 1% of the shares. The share count always rounds down to a whole number.

Growth and loss. If a connected protocol earns money, the jar is worth more and the share count stays the same. Each share redeems for more. If the protocol loses money, each share redeems for less.

Paper losses. Sometimes a loan looks bad before it has failed. The vault records that as an unrealized loss. It is a warning on the books, not a final number.

A paper loss creates a problem. People who leave early could dodge it and push the whole loss onto those who stay. So withdrawals are priced with the paper loss already subtracted. Everyone who leaves carries a fair part of it.

Available is not total. Money out on loan still counts toward the vault's value. It is not in the jar, though. A withdrawal can only pay out what is in the jar at that moment. If too much is lent out, a withdrawal fails until money comes back.

Withdrawals are first come, first served. There is no queue on the ledger.

Shares are MPTs issued by the vault's pseudo-account. The Vault entry does not store a share count. The OutstandingAmount on the share MPTokenIssuance is the total.

MPTs are whole numbers, so the vault uses a Scale to turn fractional assets into whole shares:

After the first deposit, with Γ_assets as AssetsTotal, Γ_shares as outstanding shares and l as LossUnrealized:

• Deposit: Δ_shares = (Δ_assets × Γ_shares) / Γ_assets, rounded down.
• Redeem shares: Δ_assets = (Δ_shares × (Γ_assets − l)) / Γ_shares.
• Withdraw an asset amount: Δ_shares = (Δ_assets × Γ_shares) / (Γ_assets − l), rounded down. The payout is then computed from those shares.

VaultWithdraw takes an Amount in either unit. An asset amount burns the shares needed to pay it. A share amount pays whatever those shares are worth. An optional Destination sends the assets to another account.

Rounding rules, updated by the fixCleanup3_4_0 amendment:

• The payout never exceeds the requested amount. Leftover dust stays in the vault.
• A deposit or withdrawal that rounds to nothing fails with tecPRECISION_LOSS.
• A final withdrawal that redeems every outstanding share succeeds even if it pays zero.

Other limits:

• tecINSUFFICIENT_FUNDS: the sender lacks shares, or AssetsAvailable cannot cover the request.
• tecLIMIT_EXCEEDED: a deposit would push AssetsTotal past AssetsMaximum.
• WithdrawalPolicy has one value today, vaultStrategyFirstComeFirstServe (0x0001).

Vault deposits and withdrawals do not charge the asset's transfer fee.

Related: A shared jar for one asset, Multi-Purpose Tokens.