fix(lending_pool): base share accounting on tracked managed assets, not raw balance

Share value for both minting and redemption was derived from the raw
TokenClient::balance of the pool. That let the price swing while loan
principal was out (a receivable) and let anyone inflate it by transferring
tokens directly to the pool address (donation / inflation attack), while
redeem_shares subtracted the full yield-inclusive payout from TotalDeposits,
causing principal drift.

Introduce TotalManagedAssets (principal + realized yield, net of withdrawals)
as the single source of truth for the share<->asset exchange rate, moved only
by deposit, redeem, and an admin-gated record_yield. The raw balance is now a
liquidity gate only (InsufficientLiquidity on under-funded redemptions).
redeem_shares reduces TotalDeposits by the principal portion only. Adds
record_yield (emitting YieldDistributed), bumps version 3->4, documents the
model, and adds tests for outstanding loans, direct transfers, the inflation
attack, and principal reconciliation.

Closes #2

Author: xeladev4

lending_pool/src/events.rs

@@ -24,7 +24,6 @@ pub fn emergency_withdraw(
     env.events().publish(topics, (amount, shares_burned));
 }
 
-#[allow(dead_code)]
 pub fn yield_distributed(env: &Env, token: Address, amount: i128) {
     let topics = (Symbol::new(env, "YieldDistributed"), token);
     env.events().publish(topics, amount);

lending_pool/src/lib.rs

@@ -27,8 +27,27 @@ pub enum PoolError {
 ///
 /// v2 replaces the accumulator-style keys (Deposit, RewardDebt, ClaimableYield,
 /// AccYieldPerDeposit, UnclaimedYieldPool) with a share-based (LP-token) model.
-/// Yield is now implicit in the exchange rate between shares and underlying
-/// assets — no separate accumulation or claim step is required.
+/// Yield is implicit in the exchange rate between shares and underlying assets —
+/// no separate accumulation or claim step is required.
+///
+/// ## Accounting source of truth (v3, issue #2)
+///
+/// Share value is derived **exclusively** from `TotalManagedAssets`, an
+/// internally-tracked figure equal to deposited principal plus realized yield,
+/// net of withdrawals. It is deliberately *not* derived from the contract's raw
+/// `TokenClient::balance`, because the raw balance:
+///   * drops while principal is out on loan (the principal is still a pool asset,
+///     just a receivable — share value must not swing with utilisation), and
+///   * can be inflated by anyone transferring tokens directly to the pool
+///     address (a donation / inflation attack that would otherwise let an
+///     attacker arbitrarily move existing holders' redeemable value).
+///
+/// The raw balance is used only as a *liquidity* gate: a redemption that cannot
+/// currently be serviced from on-hand tokens fails with `InsufficientLiquidity`
+/// rather than mis-pricing shares. Realized yield (e.g. loan interest repaid
+/// into the pool) is folded into `TotalManagedAssets` exclusively through the
+/// admin-gated `record_yield` entry point, so unsolicited transfers never change
+/// the exchange rate.
 ///
 /// All per-token keys carry the token address so one contract instance can
 /// serve multiple token liquidity pools.
@@ -47,8 +66,15 @@ pub enum DataKey {
     /// (provider, token) → ledger sequence of the most recent deposit
     DepositTimestamp(Address, Address),
     /// token → total principal deposited (net of withdrawals); used for
-    /// utilisation stats and the MaxPoolSize cap
+    /// utilisation stats and the MaxPoolSize cap. Tracks principal only — it is
+    /// never moved by yield, so it cannot drift above what was actually
+    /// deposited.
     TotalDeposits(Address),
+    /// token → total underlying assets backing LP shares (principal + realized
+    /// yield, net of withdrawals). Single source of truth for the share↔asset
+    /// exchange rate. Unaffected by direct token transfers or by principal
+    /// temporarily out on loan. See the module-level accounting note.
+    TotalManagedAssets(Address),
     /// token → number of active depositors
     DepositorCount(Address),
     ProposedAdmin,
@@ -77,7 +103,7 @@ impl LendingPool {
     const INSTANCE_TTL_BUMP: u32 = 518400;
     const PERSISTENT_TTL_THRESHOLD: u32 = 17280;
     const PERSISTENT_TTL_BUMP: u32 = 518400;
-    const CURRENT_VERSION: u32 = 3;
+    const CURRENT_VERSION: u32 = 4;
     const DEFAULT_WITHDRAWAL_COOLDOWN: u32 = 1_440;
     const SHARE_PRICE_SCALE: i128 = 1_000_000;
     const MAX_WITHDRAWAL_COOLDOWN_LEDGERS: u32 = 17_280 * 30;
@@ -128,6 +154,24 @@ impl LendingPool {
             .unwrap_or(0)
     }
 
+    /// Total underlying assets backing LP shares (principal + realized yield,
+    /// net of withdrawals). The single source of truth for the share↔asset
+    /// exchange rate — see the module-level accounting note.
+    fn total_managed_assets(env: &Env, token: &Address) -> i128 {
+        Self::bump_instance_ttl(env);
+        env.storage()
+            .instance()
+            .get(&DataKey::TotalManagedAssets(token.clone()))
+            .unwrap_or(0)
+    }
+
+    fn set_total_managed_assets(env: &Env, token: &Address, value: i128) {
+        env.storage()
+            .instance()
+            .set(&DataKey::TotalManagedAssets(token.clone()), &value);
+        Self::bump_instance_ttl(env);
+    }
+
     fn read_shares(env: &Env, provider: &Address, token: &Address) -> i128 {
         let key = DataKey::Shares(provider.clone(), token.clone());
         let shares: i128 = env.storage().persistent().get(&key).unwrap_or(0);
@@ -272,13 +316,32 @@ impl LendingPool {
         }
 
         let cur_total_shares = Self::total_shares(env, token);
-        let total_assets = Self::read_pool_balance(env, token);
+        // Redemption value is derived from internally-tracked managed assets, not
+        // the raw token balance, so it cannot be manipulated by direct transfers
+        // and does not swing while principal is out on loan (issue #2).
+        let total_assets = Self::total_managed_assets(env, token);
         let assets_to_return = Self::calc_assets_to_redeem(shares, total_assets, cur_total_shares)?;
 
         if assets_to_return <= 0 {
             return Err(PoolError::InvalidAmount);
         }
 
+        // Liquidity gate: the redemption must be serviceable from tokens the pool
+        // physically holds. If principal is currently out on loan the share value
+        // is unchanged, but the redemption is deferred rather than mis-priced.
+        let liquid_balance = Self::read_pool_balance(env, token);
+        if liquid_balance < assets_to_return {
+            return Err(PoolError::InsufficientLiquidity);
+        }
+
+        // Principal portion being redeemed, used to keep TotalDeposits tracking
+        // principal only (it must not absorb the yield portion of the payout).
+        let cur_total_deposits = Self::total_deposits(env, token);
+        let principal_redeemed = shares
+            .checked_mul(cur_total_deposits)
+            .and_then(|v| v.checked_div(cur_total_shares))
+            .expect("principal redeem overflow");
+
         TokenClient::new(env, token).transfer(
             &env.current_contract_address(),
             provider,
@@ -309,7 +372,15 @@ impl LendingPool {
             .instance()
             .set(&DataKey::TotalShares(token.clone()), &new_total_shares);
 
-        let new_total_deposits = Self::total_deposits(env, token).saturating_sub(assets_to_return);
+        // Managed assets shrink by the full payout (principal + yield portion).
+        let new_managed_assets = total_assets
+            .checked_sub(assets_to_return)
+            .expect("managed assets underflow");
+        Self::set_total_managed_assets(env, token, new_managed_assets);
+
+        // TotalDeposits shrinks by the principal portion only, so it never drifts
+        // away from actual net principal (issue #2, acceptance criterion 4).
+        let new_total_deposits = cur_total_deposits.saturating_sub(principal_redeemed);
         env.storage()
             .instance()
             .set(&DataKey::TotalDeposits(token.clone()), &new_total_deposits);
@@ -426,6 +497,14 @@ impl LendingPool {
         Self::total_shares(&env, &token)
     }
 
+    /// Total underlying assets backing LP shares (principal + realized yield),
+    /// i.e. the value the outstanding shares collectively redeem to. This is the
+    /// accounting figure that drives the share price — distinct from
+    /// `pool_balance` (raw on-hand tokens) and `get_total_deposits` (principal).
+    pub fn get_total_managed_assets(env: Env, token: Address) -> i128 {
+        Self::total_managed_assets(&env, &token)
+    }
+
     pub fn get_withdrawal_cooldown(env: Env) -> u32 {
         Self::withdrawal_cooldown(&env)
     }
@@ -464,9 +543,11 @@ impl LendingPool {
             }
         }
 
-        // Snapshot pool state *before* the transfer so the share price
-        // reflects the pre-deposit pool composition.
-        let total_assets_before = Self::read_pool_balance(&env, &token);
+        // Snapshot pool state *before* the transfer so the share price reflects
+        // the pre-deposit pool composition. Uses internally-tracked managed
+        // assets (not the raw balance) so a direct transfer made just before the
+        // deposit cannot dilute or inflate the minted shares (issue #2).
+        let total_assets_before = Self::total_managed_assets(&env, &token);
         let cur_total_shares = Self::total_shares(&env, &token);
 
         // Issue #1: first depositor must commit at least MINIMUM_INITIAL_DEPOSIT
@@ -524,6 +605,12 @@ impl LendingPool {
             .instance()
             .set(&DataKey::TotalDeposits(token.clone()), &new_total_deposits);
 
+        // Deposited principal joins the managed-asset base 1:1.
+        let new_managed_assets = total_assets_before
+            .checked_add(amount)
+            .expect("managed assets overflow");
+        Self::set_total_managed_assets(&env, &token, new_managed_assets);
+
         Self::bump_instance_ttl(&env);
         deposit(
             &env,
@@ -551,7 +638,7 @@ impl LendingPool {
         }
         let asset_value = Self::calc_assets_to_redeem(
             shares,
-            Self::read_pool_balance(&env, &token),
+            Self::total_managed_assets(&env, &token),
             cur_total_shares,
         )
         .unwrap_or(0);
@@ -570,7 +657,7 @@ impl LendingPool {
         }
         Self::calc_assets_to_redeem(
             shares,
-            Self::read_pool_balance(&env, &token),
+            Self::total_managed_assets(&env, &token),
             cur_total_shares,
         )
         .unwrap_or(0)
@@ -583,13 +670,16 @@ impl LendingPool {
 
     /// Current LP share price scaled by `SHARE_PRICE_SCALE`.
     /// `1_000_000` means 1.0 underlying asset per share.
+    ///
+    /// Derived from internally-tracked managed assets, so it is stable while
+    /// principal is out on loan and immune to direct-transfer manipulation.
     pub fn get_share_price(env: Env, token: Address) -> i128 {
         let total_shares = Self::total_shares(&env, &token);
         if total_shares <= 0 {
             return Self::SHARE_PRICE_SCALE;
         }
 
-        Self::read_pool_balance(&env, &token)
+        Self::total_managed_assets(&env, &token)
             .checked_mul(Self::SHARE_PRICE_SCALE)
             .and_then(|v| v.checked_div(total_shares))
             .expect("share price overflow")
@@ -644,6 +734,42 @@ impl LendingPool {
         Ok(())
     }
 
+    /// Record `amount` of realized yield (e.g. loan interest repaid into the
+    /// pool), raising every outstanding share's value pro-rata.
+    ///
+    /// This is the *only* way assets enter share value besides deposits. Because
+    /// a contract cannot distinguish a legitimate interest repayment from an
+    /// unsolicited donation by looking at its balance, yield is recognised
+    /// through this deliberate, admin-gated call rather than by reading the raw
+    /// balance. That is precisely what stops a direct transfer from arbitrarily
+    /// changing existing holders' redeemable value (issue #2).
+    ///
+    /// Yield is not principal, so it does not move `TotalDeposits` or count
+    /// against the `MaxPoolSize` cap. The caller is responsible for ensuring the
+    /// corresponding tokens are actually present in the pool; otherwise later
+    /// redemptions will hit the `InsufficientLiquidity` gate.
+    pub fn record_yield(env: Env, token: Address, amount: i128) -> Result<(), PoolError> {
+        Self::admin(&env).require_auth();
+        Self::assert_not_paused(&env)?;
+
+        if amount <= 0 {
+            return Err(PoolError::InvalidAmount);
+        }
+
+        // Yield is only meaningful once shares exist to distribute it to.
+        if Self::total_shares(&env, &token) <= 0 {
+            return Err(PoolError::InvalidAmount);
+        }
+
+        let new_managed_assets = Self::total_managed_assets(&env, &token)
+            .checked_add(amount)
+            .expect("managed assets overflow");
+        Self::set_total_managed_assets(&env, &token, new_managed_assets);
+
+        yield_distributed(&env, token, amount);
+        Ok(())
+    }
+
     // ── Queries ───────────────────────────────────────────────────────────
 
     pub fn get_pool_stats(env: Env, token: Address) -> PoolStats {