diff --git a/WRITING-PLAN.md b/WRITING-PLAN.md index 7ee008c7..811b71b9 100644 --- a/WRITING-PLAN.md +++ b/WRITING-PLAN.md @@ -71,7 +71,7 @@ What is specific to the book: the conventions are fixed during the single visual Steps currently missing their per-step diagram, to be drawn in the visual pass: -- Lending and Borrowing: Maria's opening deposit into each reserve, and her three share accounts in the account map; Carol's short; Bob's repayment and collateral withdrawal. +- Lending and Borrowing: Carol's short; Bob's repayment and collateral withdrawal. - Perpetual Futures: Alice's `close_position` payout. - The Prop AMM: Maria's `deposit_inventory` and `withdraw_inventory`. - The Vault Strategy: Bob's deposit at the new share price. diff --git a/building-financial-products-in-solana/figures/lending-account-map.svg b/building-financial-products-in-solana/figures/lending-account-map.svg deleted file mode 100644 index da36d939..00000000 --- a/building-financial-products-in-solana/figures/lending-account-map.svg +++ /dev/null @@ -1,257 +0,0 @@ - - Every account the market holds - - - - Solana Devnet - - - - - USDC mint - - - - - - NVDAx mint - - - - - - SPCXx mint - - - - - - Alice - - 1 SOL - - - - ALICE'S ADDRESS + - TOKEN PROGRAM + - USDC MINT - - - Alice's USDC - - 0 USDC - - - - ALICE'S ADDRESS + - TOKEN PROGRAM + - USDC SHARE MINT - - - USDC shares - - 1,000 shares - - - - ALICE'S ADDRESS + - TOKEN PROGRAM + - SPCXX SHARE MINT - - - SPCXx shares - - 4 shares - - - - - - Bob - - 1 SOL - - - - BOB'S ADDRESS + - TOKEN PROGRAM + - NVDAX MINT - - - Bob's NVDAx - - 0 NVDAx - - - - BOB'S ADDRESS + - TOKEN PROGRAM + - NVDAX SHARE MINT - - - NVDAx shares - - 0 · all pledged - - - - BOB'S ADDRESS + - TOKEN PROGRAM + - USDC MINT - - - Bob's USDC - - 750 USDC - - - - "OBLIGATION" + - MARKET + - BOB'S ADDRESS - - - obligation - - deposited_value: $1,000 - borrowed_value: $750 - - - - "OBLIGATION_SHARE_ - VAULT" + RESERVE + - OBLIGATION - - - collateral vault - - 5 NVDAx shares - authority: the obligation - - - - - - Carol - - 1 SOL - - - - CAROL'S ADDRESS + - TOKEN PROGRAM + - USDC MINT - - - Carol's USDC - - 0 USDC - - - - CAROL'S ADDRESS + - TOKEN PROGRAM + - USDC SHARE MINT - - - USDC shares - - 0 · all pledged - - - - CAROL'S ADDRESS + - TOKEN PROGRAM + - SPCXX MINT - - - Carol's SPCXx - - 3 SPCXx - - - - "OBLIGATION" + - MARKET + - CAROL'S ADDRESS - - - obligation - - deposited_value: $1,000 - borrowed_value: $750 - - - - "OBLIGATION_SHARE_ - VAULT" + RESERVE + - OBLIGATION - - - collateral vault - - 1,000 USDC shares - authority: the obligation - - - - - - Dave - - 1 SOL - - - - DAVE'S ADDRESS + - TOKEN PROGRAM + - SPCXX MINT - - - Dave's SPCXx - - - - - - - Maria - - 1 SOL - - - - - - lending program - - init_lending_market() - init_reserve() - update_reserve_config() - set_price() - refresh_reserve() - refresh_obligation() - deposit_reserve_liquidity() - redeem_reserve_collateral() - init_obligation() - deposit_obligation_collateral() - withdraw_obligation_collateral() - borrow_obligation_liquidity() - repay_obligation_liquidity() - liquidate_obligation() - collect_protocol_fees() - - - - "LENDING_MARKET" - + MARKET ID - - - lending market - - market_id: 0 - owner: Maria - quote_currency_mint: USDC - - - diff --git a/building-financial-products-in-solana/figures/lending-borrow-ltv.svg b/building-financial-products-in-solana/figures/lending-borrow-ltv.svg index 66b5024e..edb7aab0 100644 --- a/building-financial-products-in-solana/figures/lending-borrow-ltv.svg +++ b/building-financial-products-in-solana/figures/lending-borrow-ltv.svg @@ -1,4 +1,4 @@ - + Bob borrows against collateral @@ -262,4 +262,7 @@ Borrow 750 USDC against the pledged shares + not drawn: Maria's USDC, NVDAx and SPCXx accounts and her three share accounts, which this step does not touch + balances and supplies leave out Maria's opening deposit into each reserve, + 1,001 minor units in and one minor unit of shares out diff --git a/building-financial-products-in-solana/figures/lending-deposit-shares.svg b/building-financial-products-in-solana/figures/lending-deposit-shares.svg index 45d2fd53..714f823e 100644 --- a/building-financial-products-in-solana/figures/lending-deposit-shares.svg +++ b/building-financial-products-in-solana/figures/lending-deposit-shares.svg @@ -254,5 +254,8 @@ minted to Alice + not drawn: Maria's USDC, NVDAx and SPCXx accounts and her three share accounts, + which this step does not touch; balances and supplies leave out Maria's opening deposit + into each reserve, 1,001 minor units in and one minor unit of shares out diff --git a/building-financial-products-in-solana/figures/lending-liquidation-second-call.svg b/building-financial-products-in-solana/figures/lending-liquidation-second-call.svg index a84f323d..0e57a6ce 100644 --- a/building-financial-products-in-solana/figures/lending-liquidation-second-call.svg +++ b/building-financial-products-in-solana/figures/lending-liquidation-second-call.svg @@ -1,4 +1,4 @@ - + Dave liquidates Carol a second time @@ -316,4 +316,7 @@ Seize 236.25 USDC shares, 5% bonus 4 Debt and collateral both fall + not drawn: Maria's USDC, NVDAx and SPCXx accounts and her three share accounts, which this step does not touch + balances and supplies leave out Maria's opening deposit into each reserve, + 1,001 minor units in and one minor unit of shares out diff --git a/building-financial-products-in-solana/figures/lending-liquidation.svg b/building-financial-products-in-solana/figures/lending-liquidation.svg index 545754f9..080ea133 100644 --- a/building-financial-products-in-solana/figures/lending-liquidation.svg +++ b/building-financial-products-in-solana/figures/lending-liquidation.svg @@ -1,4 +1,4 @@ - + Dave liquidates Carol @@ -316,4 +316,7 @@ Seize 472.50 USDC shares, 5% bonus 4 Debt and collateral both fall + not drawn: Maria's USDC, NVDAx and SPCXx accounts and her three share accounts, which this step does not touch + balances and supplies leave out Maria's opening deposit into each reserve, + 1,001 minor units in and one minor unit of shares out diff --git a/building-financial-products-in-solana/figures/lending-open-reserves.svg b/building-financial-products-in-solana/figures/lending-open-reserves.svg new file mode 100644 index 00000000..41a9256f --- /dev/null +++ b/building-financial-products-in-solana/figures/lending-open-reserves.svg @@ -0,0 +1,296 @@ + + Maria opens each reserve with a deposit + + + + + Solana Devnet + + + + + + USDC mint + + + + + + + NVDAx mint + + + + + + + SPCXx mint + + + + + + + Alice + + + + + + + Bob + + + + + + + Carol + + + + + + + Dave + + + + + + Maria + + 1 SOL + + + + + + lending program + + init_lending_market() + init_reserve() + update_reserve_config() + set_price() + refresh_reserve() + refresh_obligation() + deposit_reserve_liquidity() + redeem_reserve_collateral() + init_obligation() + deposit_obligation_collateral() + withdraw_obligation_collateral() + borrow_obligation_liquidity() + repay_obligation_liquidity() + liquidate_obligation() + collect_protocol_fees() + + + + MARIA'S ADDRESS + + TOKEN PROGRAM + + USDC MINT + + + Maria's USDC + + 0 USDC + + + + MARIA'S ADDRESS + + TOKEN PROGRAM + + USDC SHARE MINT + + + USDC shares + + 1 minor unit + + + + "RESERVE" + MARKET + + USDC MINT ADDRESS + + + USDC reserve + + available_liquidity: 1,001 minor units + borrowed_principal: 0 + borrow_accumulation_factor: 1.0 + accumulated_protocol_fees: 0 + + + + "LIQUIDITY_VAULT" + + RESERVE + + + USDC liquidity vault + + 1,001 minor units + authority: the reserve + + + + "SHARE_MINT" + RESERVE + + + USDC share mint + + supply: 1 minor unit + authority: the reserve + + + + MARIA'S ADDRESS + + TOKEN PROGRAM + + NVDAX MINT + + + Maria's NVDAx + + 0 NVDAx + + + + MARIA'S ADDRESS + + TOKEN PROGRAM + + NVDAX SHARE MINT + + + NVDAx shares + + 1 minor unit + + + + "RESERVE" + MARKET + + NVDAX MINT ADDRESS + + + NVDAx reserve + + available_liquidity: 1,001 minor units + borrowed_principal: 0 + borrow_accumulation_factor: 1.0 + accumulated_protocol_fees: 0 + + + + "LIQUIDITY_VAULT" + + RESERVE + + + NVDAx liquidity vault + + 1,001 minor units + authority: the reserve + + + + "SHARE_MINT" + RESERVE + + + NVDAx share mint + + supply: 1 minor unit + authority: the reserve + + + + MARIA'S ADDRESS + + TOKEN PROGRAM + + SPCXX MINT + + + Maria's SPCXx + + 0 SPCXx + + + + MARIA'S ADDRESS + + TOKEN PROGRAM + + SPCXX SHARE MINT + + + SPCXx shares + + 1 minor unit + + + + "RESERVE" + MARKET + + SPCXX MINT ADDRESS + + + SPCXx reserve + + available_liquidity: 1,001 minor units + borrowed_principal: 0 + borrow_accumulation_factor: 1.0 + accumulated_protocol_fees: 0 + + + + "LIQUIDITY_VAULT" + + RESERVE + + + SPCXx liquidity vault + + 1,001 minor units + authority: the reserve + + + + "SHARE_MINT" + RESERVE + + + SPCXx share mint + + supply: 1 minor unit + authority: the reserve + + + + 1 + + + 2 + + + 3 + + + 4 + + + 5 + + + 6 + + 1 + Pay in USDC + 1,001 minor units + 2 + Get USDC shares + 1 minor unit + 3 + Pay in NVDAx + 1,001 minor units + 4 + Get NVDAx shares + 1 minor unit + 5 + Pay in SPCXx + 1,001 minor units + 6 + Get SPCXx shares + 1 minor unit + A reserve's first deposit mints one minor unit of shares per minor unit deposited, less 1,000 that are withheld. + The withheld shares are never minted and belong to nobody, and every later share price counts them. + not drawn: the price feeds, the lending market, and Alice's, Bob's, Carol's and Dave's token accounts, which this step does not touch + + diff --git a/building-financial-products-in-solana/figures/lending-reserves.svg b/building-financial-products-in-solana/figures/lending-reserves.svg deleted file mode 100644 index 2a6fa66b..00000000 --- a/building-financial-products-in-solana/figures/lending-reserves.svg +++ /dev/null @@ -1,141 +0,0 @@ - - - One reserve per token, and what each one owns - - - - "RESERVE" + MARKET + - USDC MINT ADDRESS - - - USDC reserve - - available_liquidity: 1,250 - borrowed_principal: 750 - borrow_accumulation_factor: 1.0 - accumulated_protocol_fees: 0 - - - - "PRICE_FEED" + MARKET + - USDC MINT ADDRESS - - - USDC price feed - - price_mantissa: 1 - exponent: 0 - - - - "LIQUIDITY_VAULT" - + RESERVE - - - USDC liquidity vault - - 1,250 USDC - authority: the reserve - - - - "SHARE_MINT" + RESERVE - - - USDC share mint - - supply: 2,000 - authority: the reserve - - - - "RESERVE" + MARKET + - NVDAX MINT ADDRESS - - - NVDAx reserve - - available_liquidity: 5 - borrowed_principal: 0 - borrow_accumulation_factor: 1.0 - accumulated_protocol_fees: 0 - - - - "PRICE_FEED" + MARKET + - NVDAX MINT ADDRESS - - - NVDAx price feed - - price_mantissa: 200 - exponent: 0 - - - - "LIQUIDITY_VAULT" - + RESERVE - - - NVDAx liquidity vault - - 5 NVDAx - authority: the reserve - - - - "SHARE_MINT" + RESERVE - - - NVDAx share mint - - supply: 5 - authority: the reserve - - - - "RESERVE" + MARKET + - SPCXX MINT ADDRESS - - - SPCXx reserve - - available_liquidity: 1 - borrowed_principal: 3 - borrow_accumulation_factor: 1.0 - accumulated_protocol_fees: 0 - - - - "PRICE_FEED" + MARKET + - SPCXX MINT ADDRESS - - - SPCXx price feed - - price_mantissa: 250 - exponent: 0 - - - - "LIQUIDITY_VAULT" - + RESERVE - - - SPCXx liquidity vault - - 1 SPCXx - authority: the reserve - - - - "SHARE_MINT" + RESERVE - - - SPCXx share mint - - supply: 4 - authority: the reserve - - - diff --git a/building-financial-products-in-solana/lending.md b/building-financial-products-in-solana/lending.md index 50b8a707..96e74cd3 100644 --- a/building-financial-products-in-solana/lending.md +++ b/building-financial-products-in-solana/lending.md @@ -35,7 +35,11 @@ Each reserve carries a `ReserveConfig`, all in basis points, and its validation ## Supplying: Tokens In, Shares Out -Alice has her standard 1,000 USDC, plus four SPCXx (SpaceX stock, $250 each), sitting idle, and she wants yield. She runs `deposit_reserve_liquidity()` with her 1,000 USDC. Maria has already made the first deposit into each reserve, 1,001 minor units. A reserve's first deposit mints one share per minor unit, less 1,000 shares that are withheld and never minted, the program's `MINIMUM_SHARES`. So Maria holds one share, and the 1,000 withheld shares belong to nobody. Every later deposit mints by the going rate: shares = amount × (share supply + 1,000) ÷ total liquidity, floored, where total liquidity is available plus borrowed (with accrued interest) minus the house's accumulated fees. The withheld 1,000 count in every conversion between shares and liquidity, and the failure-modes section says why. The USDC reserve holds 1,001 minor units against 1,001 shares, so Alice receives 1,000 USDC shares; she does the same with her four SPCXx. The share price is how yield arrives: interest grows the pool while the share supply is unchanged, so each share redeems for more than it did. The program keeps no per-lender interest records. +Before anyone supplies, Maria makes the first deposit into each reserve herself, running `deposit_reserve_liquidity()` three times with 1,001 minor units of USDC, NVDAx and SPCXx. A reserve's share token has as many decimals as its asset, and the first deposit mints one minor unit of shares per minor unit deposited, less 1,000 that are withheld and never minted: the program's `MINIMUM_SHARES`. So Maria holds one minor unit of each reserve's shares, and the 1,000 withheld units belong to nobody. + +![](figures/lending-open-reserves.svg) + +Alice has her standard 1,000 USDC, plus four SPCXx (SpaceX stock, $250 each), sitting idle, and she wants yield. She runs `deposit_reserve_liquidity()` with her 1,000 USDC. Every deposit after a reserve's first mints by the going rate: shares = amount × (share supply + 1,000) ÷ total liquidity, floored, where total liquidity is available plus borrowed (with accrued interest) minus the house's accumulated fees. The withheld 1,000 count in every conversion between shares and liquidity, and the failure-modes section says why. The USDC reserve holds 1,001 minor units against 1,001 minor units of shares, one to one, so Alice receives 1,000 USDC shares; she does the same with her four SPCXx. The share price is how yield arrives: interest grows the pool while the share supply is unchanged, so each share redeems for more than it did. The program keeps no per-lender interest records. ![Interest grows the pool while the share supply is unchanged, so the same shares redeem for more USDC later.](figures/lending-deposit-shares.svg) @@ -141,7 +145,7 @@ Every number in this program flows through `mul_div_floor()` or `mul_div_ceil()` - **Skipping the refresh** would let positions be judged on old values; `ReserveStale`, `ObligationStale`, and `borrow_without_obligation_refresh_is_rejected` close the path. - **Cross-market smuggling**: an obligation in one market pledging reserves from another is refused (`MarketMismatch`, `cross_market_reserve_is_rejected`). - **Dangerous configurations are rejected at write time**: LTV above threshold, zero close factor, misordered rate curves (`rejects_ltv_above_liquidation_threshold`, `rejects_misordered_interest_rate_curve`). -- **Share inflation through the reserve's own borrowing.** Donating tokens to the vault moves nothing, because `available_liquidity`, not the vault balance, is the source of truth. But total liquidity also counts interest owed on borrows, and a supplier may borrow from the reserve they supply. The attacker is the only supplier of an empty reserve, holding one share, and borrows one minor unit from it against collateral in another reserve. Debt rounds up, so a second of interest makes that debt two minor units, and the one share is worth two without anything being minted. From there, deposits and redemptions push the share price higher, because both round in the pool's favor and the attacker owns the whole pool. Once one share is worth about 690 USDC, a 1,000 USDC deposit mints one share, and the attacker's share redeems half the pool. `inflating_shares_through_own_borrow_does_not_pay` runs this on the default rate curve, and the attacker repays the loan and leaves no bad debt. Without the withheld shares the attacker turns 4,000 USDC into 4,155.20. With them, the attacker's share is one of 1,001, and nearly everything the rounding leaves behind goes to shares nobody can redeem. The attacker ends 1,065 minor units down, and the victim gets back the whole deposit. A reserve whose suppliers have all left keeps the 1,000 minor units behind the withheld shares, and the next deposit is priced against them instead of starting the reserve over (`sole_supplier_leaves_the_minimum_behind`). +- **Share inflation through the reserve's own borrowing.** Donating tokens to the vault moves nothing, because `available_liquidity`, not the vault balance, is the source of truth. But total liquidity also counts interest owed on borrows, and a supplier may borrow from the reserve they supply. The attacker is the only supplier of an empty reserve, holding a single minor unit of its shares, and borrows one minor unit from it against collateral in another reserve. Debt rounds up, so a second of interest makes that debt two minor units, and the attacker's unit of shares is worth two without anything being minted. From there, deposits and redemptions push the share price higher, because both round in the pool's favor and the attacker owns the whole pool. Once that unit is worth about 690 USDC, a 1,000 USDC deposit mints one unit of shares, and the attacker's unit redeems half the pool. `inflating_shares_through_own_borrow_does_not_pay` runs this on the default rate curve, and the attacker repays the loan and leaves no bad debt. Without the withheld shares the attacker turns 4,000 USDC into 4,155.20. With them, the attacker's unit is one of 1,001, and nearly everything the rounding leaves behind goes to shares nobody can redeem. The attacker ends 1,065 minor units down, and the victim gets back the whole deposit. A reserve whose suppliers have all left keeps the 1,000 minor units behind the withheld shares, and the next deposit is priced against them instead of starting the reserve over (`sole_supplier_leaves_the_minimum_behind`). - **Self-liquidation** is allowed, deliberately: it is only possible while unhealthy and is economically pointless, matching how Save and Kamino Lend behave. Not every strange-looking path needs a check; this one is harmless because it never pays. ## Testing Considerations