Merge pull request #121 from quicknode/claude/rename-borrow-accumulation-factor

lending: name the interest index for what it is

Author: mikemaccana

finance/lending/anchor/README.md

@@ -56,7 +56,7 @@ closing the classic empty-pool inflation attack. The first deposit mints 1:1.
 
 ### Interest: a kinked curve and a cumulative index
 
-Each `refresh_reserve` advances `cumulative_borrow_rate_index` by
+Each `refresh_reserve` advances `borrow_accumulation_factor` by
 `(1 + rate_per_slot * elapsed_slots)`. `rate_per_slot` comes from a kinked
 utilization curve: linear from `min_borrow_rate_bps` to `optimal_borrow_rate_bps`
 up to `optimal_utilization_bps`, then steeper to `max_borrow_rate_bps` at full
@@ -185,7 +185,7 @@ Suppliers deposit a token with `deposit_reserve_liquidity` and receive share tok
 
 ### How does interest accrue without looping over every account?
 
-Through a cumulative interest index: `refresh_reserve` advances a per-reserve index along a utilization-based rate curve, and each obligation stores the index value from its last interaction. The gap between the two is the interest owed, so no per-account accrual loop is needed. This is the same technique the most-used Solana lending protocols share.
+Through a cumulative accumulation factor: `refresh_reserve` advances a per-reserve factor along a utilization-based rate curve, and each obligation stores the index value from its last interaction. The gap between the two is the interest owed, so no per-account accrual loop is needed. This is the same technique the most-used Solana lending protocols share.
 
 ### How are prices fed into the protocol?
 

finance/lending/anchor/programs/lending/src/instructions/admin/initialize_reserve.rs

@@ -18,8 +18,8 @@ pub fn handle_initialize_reserve(context: Context<InitializeReserve>, config: Re
     reserve.liquidity_decimals = context.accounts.liquidity_mint.decimals;
     reserve.available_liquidity = 0;
     reserve.share_mint_supply = 0;
-    reserve.borrowed_amount_scaled = 0;
-    reserve.cumulative_borrow_rate_index = FIXED_POINT_SCALE;
+    reserve.borrowed_principal = 0;
+    reserve.borrow_accumulation_factor = FIXED_POINT_SCALE;
     reserve.last_update_slot = Clock::get()?.slot;
     reserve.accumulated_protocol_fees = 0;
     reserve.config = config;

finance/lending/anchor/programs/lending/src/instructions/borrow_obligation_liquidity.rs

@@ -45,13 +45,13 @@ pub fn handle_borrow_obligation_liquidity(
     let scaled_added = mul_div_ceil(
         liquidity_amount as u128,
         FIXED_POINT_SCALE,
-        context.accounts.reserve.cumulative_borrow_rate_index,
+        context.accounts.reserve.borrow_accumulation_factor,
     )?;
 
     {
         let reserve = &mut context.accounts.reserve;
-        reserve.borrowed_amount_scaled = reserve
-            .borrowed_amount_scaled
+        reserve.borrowed_principal = reserve
+            .borrowed_principal
             .checked_add(scaled_added)
             .ok_or(LendingError::MathOverflow)?;
         reserve.available_liquidity = reserve
@@ -63,8 +63,8 @@ pub fn handle_borrow_obligation_liquidity(
     {
         let obligation = &mut context.accounts.obligation;
         let index = obligation.upsert_borrow(reserve_key)?;
-        obligation.borrows[index].borrowed_scaled = obligation.borrows[index]
-            .borrowed_scaled
+        obligation.borrows[index].borrowed_principal = obligation.borrows[index]
+            .borrowed_principal
             .checked_add(scaled_added)
             .ok_or(LendingError::MathOverflow)?;
         obligation.stale = true;

finance/lending/anchor/programs/lending/src/instructions/liquidate_obligation.rs

@@ -49,12 +49,12 @@ pub fn handle_liquidate_obligation(
 
     let borrow_index = obligation.find_borrow(repay_reserve.key())?;
     let collateral_index = obligation.find_collateral(collateral_reserve.key())?;
-    let borrowed_scaled = obligation.borrows[borrow_index].borrowed_scaled;
+    let borrowed_principal = obligation.borrows[borrow_index].borrowed_principal;
     let deposited_shares = obligation.deposits[collateral_index].deposited_shares;
 
     // How much debt this liquidation repays, capped by the close factor.
-    let interest_index = repay_reserve.cumulative_borrow_rate_index;
-    let debt_now = mul_div_ceil(borrowed_scaled, interest_index, FIXED_POINT_SCALE)?;
+    let accumulation_factor = repay_reserve.borrow_accumulation_factor;
+    let debt_now = mul_div_ceil(borrowed_principal, accumulation_factor, FIXED_POINT_SCALE)?;
     let debt_now = u64::try_from(debt_now).map_err(|_| LendingError::MathOverflow)?;
     let max_repay = mul_div_floor(
         debt_now as u128,
@@ -100,13 +100,13 @@ pub fn handle_liquidate_obligation(
     );
 
     let scaled_removed =
-        mul_div_floor(repay as u128, FIXED_POINT_SCALE, interest_index)?.min(borrowed_scaled);
+        mul_div_floor(repay as u128, FIXED_POINT_SCALE, accumulation_factor)?.min(borrowed_principal);
 
     // Effects: repay side.
     {
         let repay_reserve = &mut context.accounts.repay_reserve;
-        repay_reserve.borrowed_amount_scaled = repay_reserve
-            .borrowed_amount_scaled
+        repay_reserve.borrowed_principal = repay_reserve
+            .borrowed_principal
             .checked_sub(scaled_removed)
             .ok_or(LendingError::MathOverflow)?;
         repay_reserve.available_liquidity = repay_reserve
@@ -118,10 +118,10 @@ pub fn handle_liquidate_obligation(
     // Effects: obligation debt and collateral.
     let (lending_market, owner, obligation_bump) = {
         let obligation = &mut context.accounts.obligation;
-        obligation.borrows[borrow_index].borrowed_scaled = borrowed_scaled
+        obligation.borrows[borrow_index].borrowed_principal = borrowed_principal
             .checked_sub(scaled_removed)
             .ok_or(LendingError::MathOverflow)?;
-        if obligation.borrows[borrow_index].borrowed_scaled == 0 {
+        if obligation.borrows[borrow_index].borrowed_principal == 0 {
             obligation.borrows.remove(borrow_index);
         }
         obligation.deposits[collateral_index].deposited_shares = deposited_shares

finance/lending/anchor/programs/lending/src/instructions/refresh_obligation.rs

@@ -64,8 +64,8 @@ pub fn handle_refresh_obligation(context: Context<RefreshObligation>) -> Result<
             read_pair(accounts, &mut cursor, borrow.reserve, lending_market, slot)?;
 
         let debt = mul_div_ceil(
-            borrow.borrowed_scaled,
-            reserve.cumulative_borrow_rate_index,
+            borrow.borrowed_principal,
+            reserve.borrow_accumulation_factor,
             crate::constants::FIXED_POINT_SCALE,
         )?;
         let debt = u64::try_from(debt).map_err(|_| LendingError::MathOverflow)?;

finance/lending/anchor/programs/lending/src/instructions/repay_obligation_liquidity.rs

@@ -20,23 +20,23 @@ pub fn handle_repay_obligation_liquidity(
     let reserve_key = context.accounts.reserve.key();
     context.accounts.reserve.require_refreshed()?;
 
-    let index = context.accounts.reserve.cumulative_borrow_rate_index;
+    let index = context.accounts.reserve.borrow_accumulation_factor;
     let decimals = context.accounts.reserve.liquidity_decimals;
 
     let borrow_index = context.accounts.obligation.find_borrow(reserve_key)?;
-    let borrowed_scaled = context.accounts.obligation.borrows[borrow_index].borrowed_scaled;
+    let borrowed_principal = context.accounts.obligation.borrows[borrow_index].borrowed_principal;
 
-    let debt_now = mul_div_ceil(borrowed_scaled, index, FIXED_POINT_SCALE)?;
+    let debt_now = mul_div_ceil(borrowed_principal, index, FIXED_POINT_SCALE)?;
     let debt_now = u64::try_from(debt_now).map_err(|_| LendingError::MathOverflow)?;
     let repay = liquidity_amount.min(debt_now);
     require!(repay > 0, LendingError::ZeroAmount);
 
-    let scaled_removed = mul_div_floor(repay as u128, FIXED_POINT_SCALE, index)?.min(borrowed_scaled);
+    let scaled_removed = mul_div_floor(repay as u128, FIXED_POINT_SCALE, index)?.min(borrowed_principal);
 
     {
         let reserve = &mut context.accounts.reserve;
-        reserve.borrowed_amount_scaled = reserve
-            .borrowed_amount_scaled
+        reserve.borrowed_principal = reserve
+            .borrowed_principal
             .checked_sub(scaled_removed)
             .ok_or(LendingError::MathOverflow)?;
         reserve.available_liquidity = reserve
@@ -47,10 +47,10 @@ pub fn handle_repay_obligation_liquidity(
 
     {
         let obligation = &mut context.accounts.obligation;
-        obligation.borrows[borrow_index].borrowed_scaled = borrowed_scaled
+        obligation.borrows[borrow_index].borrowed_principal = borrowed_principal
             .checked_sub(scaled_removed)
             .ok_or(LendingError::MathOverflow)?;
-        if obligation.borrows[borrow_index].borrowed_scaled == 0 {
+        if obligation.borrows[borrow_index].borrowed_principal == 0 {
             obligation.borrows.remove(borrow_index);
         }
         obligation.stale = true;

finance/lending/anchor/programs/lending/src/state/obligation.rs

@@ -54,8 +54,8 @@ pub struct ObligationLiquidity {
     pub reserve: Pubkey,
     /// Borrowed principal, scaled by the reserve's index at borrow time so the
     /// live debt grows automatically as that index advances:
-    /// `debt = borrowed_scaled * reserve.cumulative_borrow_rate_index / FIXED_POINT_SCALE`.
-    pub borrowed_scaled: u128,
+    /// `debt = borrowed_principal * reserve.borrow_accumulation_factor / FIXED_POINT_SCALE`.
+    pub borrowed_principal: u128,
     pub market_value: u128,
 }
 
@@ -102,7 +102,7 @@ impl Obligation {
         );
         self.borrows.push(ObligationLiquidity {
             reserve,
-            borrowed_scaled: 0,
+            borrowed_principal: 0,
             market_value: 0,
         });
         Ok(self.borrows.len() - 1)

finance/lending/anchor/programs/lending/src/state/reserve.rs

@@ -55,13 +55,13 @@ pub struct Reserve {
     /// out more than it holds.
     pub share_mint_supply: u64,
 
-    /// Total borrowed principal, scaled so that the live debt is
-    /// `borrowed_amount_scaled * cumulative_borrow_rate_index / FIXED_POINT_SCALE`.
-    pub borrowed_amount_scaled: u128,
+    /// Total borrowed principal. The live debt is
+    /// `borrowed_principal * borrow_accumulation_factor / FIXED_POINT_SCALE`.
+    pub borrowed_principal: u128,
 
-    /// Monotonically increasing interest index, FIXED_POINT_SCALE-scaled.
+    /// Monotonically increasing accumulation factor, FIXED_POINT_SCALE-scaled.
     /// Starts at FIXED_POINT_SCALE (1.0) and only ever multiplies by factors >= 1.
-    pub cumulative_borrow_rate_index: u128,
+    pub borrow_accumulation_factor: u128,
 
     pub last_update_slot: u64,
 
@@ -138,8 +138,8 @@ impl Reserve {
     /// Live total debt owed to the pool, rounded up (protocol-favourable).
     pub fn current_borrowed_amount(&self) -> Result<u64> {
         let amount = mul_div_ceil(
-            self.borrowed_amount_scaled,
-            self.cumulative_borrow_rate_index,
+            self.borrowed_principal,
+            self.borrow_accumulation_factor,
             FIXED_POINT_SCALE,
         )?;
         u64::try_from(amount).map_err(|_| LendingError::MathOverflow.into())
@@ -209,15 +209,15 @@ impl Reserve {
         mul_div_floor(apr_bps, FIXED_POINT_SCALE, per_year_denominator)
     }
 
-    /// Advance the interest index for the slots elapsed since the last refresh.
-    /// `new_index = old_index * (1 + rate_per_slot * elapsed_slots)`, a single
+    /// Advance the accumulation factor for the slots elapsed since the last refresh.
+    /// `new_factor = old_factor * (1 + rate_per_slot * elapsed_slots)`, a single
     /// multiply per refresh that compounds across refreshes (Solend's approach).
     pub fn accrue_interest(&mut self, current_slot: u64) -> Result<()> {
         let elapsed = current_slot
             .checked_sub(self.last_update_slot)
             .ok_or(LendingError::MathOverflow)?;
 
-        if elapsed > 0 && self.borrowed_amount_scaled > 0 {
+        if elapsed > 0 && self.borrowed_principal > 0 {
             let borrowed_before = self.current_borrowed_amount()?;
             let rate_per_slot = self.current_borrow_rate_per_slot()?;
             let accrued = rate_per_slot
@@ -226,13 +226,13 @@ impl Reserve {
             let growth_factor = FIXED_POINT_SCALE
                 .checked_add(accrued)
                 .ok_or(LendingError::MathOverflow)?;
-            self.cumulative_borrow_rate_index = mul_div_floor(
-                self.cumulative_borrow_rate_index,
+            self.borrow_accumulation_factor = mul_div_floor(
+                self.borrow_accumulation_factor,
                 growth_factor,
                 FIXED_POINT_SCALE,
             )?;
 
-            // Borrowers owe the full interest (the index grew for all of it); the
+            // Borrowers owe the full interest (the factor grew for all of it); the
             // protocol keeps `reserve_factor_bps` of the newly accrued interest,
             // and the remainder lifts the supplier exchange rate. Flooring the fee
             // rounds the owner's cut down, in the suppliers' favour.

finance/lending/anchor/programs/lending/tests/test_borrow_repay.rs

@@ -105,15 +105,15 @@ fn repay_reduces_debt_and_over_repay_clamps() {
     let (mut env, collateral, borrow, borrower, obligation) = setup();
     env.try_borrow(&borrower, obligation, &[&collateral], &[], &borrow, 500_000_000)
         .unwrap();
-    assert_eq!(env.reserve(&borrow).borrowed_amount_scaled > 0, true);
+    assert_eq!(env.reserve(&borrow).borrowed_principal > 0, true);
 
     env.repay(&borrower, obligation, &borrow, 200_000_000);
     let obligation_state = env.obligation(obligation);
     assert_eq!(obligation_state.borrows.len(), 1);
 
     // Over-repay: ask to repay far more than owed; it clamps to the remaining debt.
     env.repay(&borrower, obligation, &borrow, 1_000_000_000);
-    assert_eq!(env.reserve(&borrow).borrowed_amount_scaled, 0);
+    assert_eq!(env.reserve(&borrow).borrowed_principal, 0);
     assert!(env.obligation(obligation).borrows.is_empty());
 }
 

finance/lending/anchor/programs/lending/tests/test_interest.rs

@@ -5,7 +5,7 @@ use lending::constants::FIXED_POINT_SCALE;
 use solana_signer::Signer;
 
 /// Borrowing at non-zero utilization, then letting slots pass, must grow the
-/// reserve's interest index, the borrower's debt, and the share exchange rate.
+/// reserve's accumulation factor, the borrower's debt, and the share exchange rate.
 #[test]
 fn interest_accrues_on_borrows_over_time() {
     let mut env = Env::new();
@@ -29,18 +29,18 @@ fn interest_accrues_on_borrows_over_time() {
     env.try_borrow(&borrower, obligation, &[&collateral], &[], &borrow, 500_000_000)
         .unwrap();
 
-    assert_eq!(env.reserve(&borrow).cumulative_borrow_rate_index, FIXED_POINT_SCALE);
+    assert_eq!(env.reserve(&borrow).borrow_accumulation_factor, FIXED_POINT_SCALE);
 
     // Let ~0.1 year pass (2.5 slots/s => ~7.884M slots), re-publish prices, refresh.
     env.warp_slots(7_884_000);
     env.set_price(collateral.mint, dollars(1));
     env.set_price(borrow.mint, dollars(1));
     env.refresh_reserve_only(&borrower, &borrow);
 
-    let index_after = env.reserve(&borrow).cumulative_borrow_rate_index;
+    let index_after = env.reserve(&borrow).borrow_accumulation_factor;
     assert!(
         index_after > FIXED_POINT_SCALE,
-        "interest index must grow once time passes with outstanding borrows"
+        "accumulation factor must grow once time passes with outstanding borrows"
     );
 
     // The borrower now owes more than the principal.