Cowrie Research

actual-balance-and-scaled-liquidity-ledger-coherence-discipline

15 min read

Actual-Balance and Scaled-Liquidity Ledger Coherence Discipline

  • Name: actual-balance and scaled-liquidity ledger coherence discipline
  • Category: lending-reserve accounting reference / reserve-ledger coherence note / rebasing-liquidity design checklist / off-path balance-recognition companion
  • Summary: Healthy rebasing lending systems do not let real tokens sitting in the reserve wrapper, recognized supplier-backed liquidity, flash-loanable balance, utilization input, supplier-index denominator, and collateral-visible backing drift into separate partially-true ledgers. In Aave-family systems, the dangerous split often appears when raw underlying can reach the aToken contract outside supply(), while fee socialization and supplier claims still divide by scaled liquidity or reserve-cache state. The result is not merely unexpected balance showed up; it is that one subsystem starts lending, charging premiums on, or advertising collateral against a balance object that the claim-accounting side has not adopted on the same terms. The sharp review habit is to keep three promotions separate: raw custody balance exists, recognized reserve liquidity exists, and only later economically active reserve truth exists for flash loans, withdrawals, utilization, and collateral consumers. This note exists to preserve the positive-design lesson behind ZeroLend PT-LBTC, dTRINITY cbBTC, and related rebasing-reserve incidents: reserve truth must stay one coherent object across raw balance, recognized liquidity, fee routing, and downstream solvency.

Why this note exists

  • unexpected-balance-quarantine-and-explicit-recognition-discipline already preserves the first healthy boundary: tokens showed up is not yet recognized reserves.
  • reserve-backed-claim-truth-security-object already preserves the broader object: receipt, issuance, liability, and redemption must stay bound.
  • But Aave-style and similar rebasing reserves need one sharper lending-specific note: even after teams understand those two ideas in principle, they still miss the concrete danger where raw underlying balance, reserve cache, scaled supply, flash-loan accounting, and collateral presentation are allowed to consult different ledgers.
  • ZeroLend PT-LBTC is the clean balance-split exemplar: direct transfer enlarged the aToken’s real ERC-20 balance, flash loans could use that balance, but supplier-index updates still divided by dust-sized bookkept liquidity.
  • dTRINITY dLEND cbBTC is the fresh-market replay: public reconstruction indicates direct transfer widened the same raw-balance / scaled-liquidity gap while the reserve was still thin enough for fee socialization to remain attacker-authored.
  • The recurring healthy-side question is therefore sharper than should unexpected balances be quarantined? It is: which exact ledger is each reserve subsystem allowed to trust, and what enforces that all economically forceful subsystems are still consulting one coherent reserve object?
  • The practical failure pattern to keep visible is that teams often add a recognition step, then still let flash-loan activation, withdrawal semantics, or collateral publication inherit that newly recognized value too early. Recognized reserve liquidity exists is still a weaker statement than every economically forceful path may consume it now.

The six ledgers a healthy rebasing reserve should not split

  1. Raw token custody balance

    • The literal underlying.balanceOf(aToken) or equivalent custody-side token inventory.
    • Useful for custody visibility, but not automatically the same thing as supplier-owned liquidity.

  2. Recognized reserve liquidity

    • The amount the protocol has explicitly adopted as reserve-owned and supplier- / treasury-attributable backing.
    • This is the liquidity ledger that reserve accounting, reserve rate logic, and supplier claims are supposed to reconcile against.

  3. Supplier denominator state

    • The scaled-liquidity or equivalent denominator over which fees, interest, or index growth are socialized.
    • If this ledger can stay tiny while raw custody balance becomes large, fee routing itself becomes an exploit surface.

  4. Flash-loanable and spendable balance

    • The inventory the protocol is willing to lend, route, or otherwise make economically active in the same transaction.
    • This should not exceed recognized reserve liquidity merely because the token contract can see more raw inventory.

  5. Withdrawal / redemption backing

    • The state against which user exits are paid.
    • If withdrawals consult a richer ledger than supplier minting or fee denominator state, the reserve is already speaking in contradictory balance-sheet dialects.

  6. Collateral-visible reserve truth

    • The state downstream collateral engines, health-factor checks, liquidations, and sibling markets are willing to honor as real supplier value.
    • Even a locally coherent reserve may still need delay, caps, or quarantine before this ledger becomes system-wide borrowing truth.

Three reserve promotions reviewers should not collapse

  1. Raw custody balance exists

    • Tokens are physically sitting at the reserve wrapper or under the reserve’s operational control.
    • This is only an observation about custody, not yet a claim about supplier ownership, lendable liquidity, or solvency.

  2. Recognized reserve liquidity exists

    • The protocol has explicitly adopted some portion of that custody balance into the reserve ledger that suppliers, treasury accounting, and reserve-rate logic are allowed to treat as real backing.
    • This is already a stronger statement than tokens showed up, but it is still not the same thing as all economically forceful paths may now use those tokens.

  3. Economically active reserve truth exists

    • Flash loans, withdrawals, utilization, supplier-index growth, and downstream collateral engines are now allowed to consume that recognized liquidity as money-good state.
    • This last promotion is where many thin-market lending failures still hide: teams correctly add a recognition step, then still forget that recognized locally is not automatically safe to activate everywhere right now.

The design target is to make each promotion explicit, narrow, and testable. A reserve should be able to answer three separate questions in code and in docs: what tokens are here?, which of those tokens now back suppliers?, and which of those supplier-backed tokens may already influence flash-loan capacity or cross-market solvency?

What sound design looks like

1. One reserve object graduates through named stages

  • A healthy rebasing reserve can name its lifecycle cleanly: raw custody balance exists, recognized reserve liquidity exists, supplier claims may track it, flash loans may use it, and sibling markets may trust it as collateral are distinct stages.
  • The design target is not to collapse those stages into one boolean called reserve live.
  • The especially important lending-side reminder is that recognized reserve liquidity exists is still not the same thing as every economically forceful reserve path may already consume it. Flash-loan capacity and collateral-visible truth are late promotions, not ambient consequences of local recognition.

2. Raw custody balance is not self-interpreting

  • Direct transfers, over-repayments, rescue top-ups, bridge settlements, stray token sends, or operator prefunds do not get to define supplier-owned liquidity merely because they changed the custody balance.
  • A healthy reserve treats raw custody balance as an observation until one narrow recognition path adopts it into the recognized-liquidity ledger.
  • This is the sharper reserve-local companion to unexpected-balance-quarantine-and-explicit-recognition-discipline.

3. Fee socialization reads the same ledger that suppliers actually own

  • Flash-loan premiums, borrow interest, and reserve-income events should distribute over a denominator derived from the same recognized-liquidity object that backs suppliers.
  • If premiums are computed using raw flash-loanable balance while liquidityIndex growth divides by a thinner or differently maintained ledger, the protocol is already printing supplier value against fiction.

4. Flash-loanable balance never outruns recognized reserve truth

  • A reserve should not be willing to lend, route, or otherwise activate tokens that the accounting system has not yet adopted as reserve liquidity on the same terms.
  • Even after local recognition, a healthy design may still keep those tokens out of flash-loan capacity or other economically forceful paths until denominator health, reserve coherence, and reserve lifecycle checks all pass.
  • This is the promotion boundary that teams most often skip: recognized reserve liquidity exists still does not imply economically active reserve truth exists for flash loans, utilization, or same-block fee generation.
  • If raw tokens at the aToken can be flash-loaned before the reserve recognizes what they mean, or if newly recognized tokens can be flash-loaned before the reserve has re-earned mature-state trust, then fee events and utilization updates are already being authored by a different ledger than supplier claims.

5. Withdrawal math, supplier accounting, and collateral presentation reconcile against one story

  • User balanceOf, reserve totalLiquidity, liquidityIndex, withdrawable underlying, and collateral-visible value should all be derivable from one coherent reserve state machine.
  • A design is equally unhealthy if one can say those tokens are recognized reserve liquidity now, those tokens are already flash-loanable or collateral-visible now, and we have not yet proved denominator health or reserve-coherence parity under that larger state all at once.
  • In other words: reserve recognition, reserve activation, and cross-market trust should be able to fail independently and safely.

6. Downstream borrowing still treats locally new value with suspicion

  • Even if a reserve has adopted new liquidity locally, sibling borrowing and liquidation paths may still need delay, caps, or isolation before the new state becomes full collateral truth.
  • This remains the downstream job of collateral-admission-lag-and-borrow-side-quarantine.

Useful positive design shapes

1. Explicit reserve-recognition lane before economic activation

  • Keep raw custody balance and recognized reserve liquidity separate.
  • Require direct transfers, over-repayments, rescue funds, and settlement leftovers to pass through one recognition lane before they can affect flash-loan capacity, utilization, supplier index, or collateral value.

2. Flash-loan capacity pinned to recognized liquidity, not ambient balance

  • A simple healthy rule is that flash-loanable inventory cannot exceed the recognized-liquidity ledger.
  • If the protocol needs a broader custody balance for operational reasons, that broader balance should remain economically inert until recognized.

3. Supplier-index updates guarded by denominator health

  • liquidityIndex or equivalent supplier scaler should fail closed when scaled liquidity is dust-sized or when recognized-liquidity / raw-balance parity is broken.
  • Treasury routing, suspense accounting, or outright no-op fee socialization are safer than pretending a thin denominator can safely absorb the next premium.

4. Reserve-coherence assertions as first-class invariants

  • Healthy systems monitor and test relationships like:
    • flash-loanable balance <= recognized reserve liquidity
    • recognized reserve liquidity <= raw custody balance unless an explicit debt / obligation lane explains the gap
    • supplier-side aggregate value does not materially outrun economically justified reserve backing
    • collateral-visible reserve value is impossible when reserve coherence checks are failing

5. Economic re-entry through quarantine, not ambient drift

Design questions worth asking first

  • What exact ledger defines flash-loanable balance in this reserve?
  • What exact ledger defines recognized reserve liquidity?
  • What exact denominator does supplier-index growth divide by?
  • Which reserve paths are allowed to treat recognized liquidity as economically active immediately, and which must still wait for lifecycle / denominator-health checks?
  • Can any path increase one of those ledgers without increasing the others?
  • If raw underlying reaches the reserve wrapper outside the official supply path, which subsystems react immediately and which stay inert?
  • After local recognition, what exact guard still prevents same-block flash-loan activation or collateral publication if reserve coherence or scaled-liquidity health remains suspect?
  • Which exact reserve path first upgrades recognized reserve liquidity exists into economically active reserve truth exists, and what denominator-health or lifecycle checks must pass before that upgrade is allowed?
  • Does collateral-visible value read the same reserve object that flash-loan fees, withdrawals, and supplier balances read?
  • What automated condition pushes the reserve back into quarantine if balance-sheet coherence breaks or scaled liquidity collapses toward dust?

Red flags

  • Flash loans can safely use whatever the token contract currently holds.
  • Direct transfers are harmless because they only help solvency.
  • The accounting ledger will catch up on the next supply / withdraw / sync.
  • Supplier index only reads totalLiquidity, so raw balance differences do not matter while another money-moving path already reads raw balance.
  • Collateral math uses normalized income, so reserve-balance details are a separate concern.
  • This reserve is tiny, so balance-sheet divergence cannot matter.
  • If extra tokens arrive, the next premium distribution simply benefits suppliers.

Failure-prevention checklist

  • Define one authoritative recognized-liquidity ledger for each reserve and document which functions are allowed to mutate it.
  • Keep raw underlying.balanceOf(wrapper) economically inert until explicit recognition adopts the balance into reserve accounting.
  • Make flash-loan capacity, utilization, reserve-income routing, and supplier-index updates consume the same recognized reserve object or fail closed when they diverge.
  • Reconcile raw custody balance, recognized reserve liquidity, scaled supply, reserve cache, and collateral-visible supplier value after every direct transfer, over-repayment, rescue top-up, flash-loan settlement, or migration event.
  • Keep the three promotions mechanically separate in code and monitoring: raw custody balance exists, recognized reserve liquidity exists, and economically active reserve truth exists should not collapse into one ambient tokens are here state transition.
  • Refuse supplier-index socialization when the denominator is dust-sized or when raw-balance / recognized-liquidity parity checks fail.
  • Keep fresh, dormant, or low-supply reserves out of cross-market collateral duty until reserve-ledger coherence and denominator health are stable.
  • Add invariant tests where direct transfers enlarge raw balance before flash loans, fee accrual, withdrawals, or collateral reads execute. Those tests should prove the reserve either ignores, quarantines, or explicitly recognizes the balance before any economically forceful path can use it.
  • Separate reserve-local recognition from system-wide trust. Even once new liquidity is recognized, apply collateral caps, isolation, or same-block distrust until the reserve has earned broader solvency authority.
  • Alert on production-improbable states: flash-loanable balance materially above recognized liquidity, liquidityIndex jumps without corresponding borrower-side economics, one meaningful supplier, or collateral value that only exists because raw balance and scaled-liquidity ledgers disagree.
  • Treat reserve recapitalization and low-supply recovery as explicit ceremonies, not as ordinary balance drift that mature-state accounting may silently absorb.

Audit prompts

  • Which exact variable says these tokens may now be flash-loaned and which exact variable says these tokens now back suppliers? Are they ever different?
  • If a user directly transfers underlying to the reserve wrapper today, what immediate changes occur in flash-loan capacity, utilization, liquidityIndex, withdrawals, and collateral value?
  • What invariant proves flash-loan premiums cannot be socialized over a denominator that excluded the very balance used to generate those premiums?
  • Does balanceOf(user), aggregate supplier value, and recognized reserve backing still reconcile if raw custody balance changes outside the official supply path?
  • Can the reserve become economically live for sibling markets while its raw-balance / scaled-liquidity parity checks are still false or unmonitored?
  • What happens if raw balance rises while scaled liquidity remains dust-sized? Do fees route to treasury, suspense, or still to suppliers?
  • Is there any path where withdrawals or flash loans consult raw balance first and only later notice that reserve accounting had not recognized the same inventory?
  • Which circuit breaker fires if flash-loanable balance materially exceeds recognized liquidity, or if collateral-visible supplier value materially outruns justified reserve backing?
  • If the reserve is freshly listed, dormant, or repaired, what exact onchain fact graduates it from locally reachable to systemically trustworthy?
  • How would operators explain, in one sentence, why the next unexpected token transfer into this reserve cannot become supplier yield, flash-loan fuel, and borrowable collateral all at once?

Lessons that should already be standard

  • Raw custody balance is not a reserve by itself. It is only one observation about the reserve.
  • Flash-loan capacity is solvency authority. If it trusts a broader ledger than supplier accounting does, the fee path can print collateral.
  • A rebasing reserve is unsafe once one subsystem says real enough to lend while another still says not part of the supplier denominator.
  • Direct transfers into lending wrappers are not harmless noise. They are balance-sheet events that must either be ignored, quarantined, or explicitly recognized.
  • liquidityIndex safety depends on denominator health, not only on correct arithmetic.
  • Collateral engines should distrust reserves whose local ledgers are still disagreeing, even if normalized-income math looks superficially valid.
  • Thin reserves make coherence failures economically explosive because a small ledger disagreement can dominate the denominator that prices all future supplier value.
  • Reserve accounting, flash-loan design, and collateral admission are one security object in rebasing markets, not three separate modules.
  • recognized reserve liquidity is not the end of the review. The last dangerous question is still whether that recognized liquidity already deserves flash-loan activation, withdrawal authority at mature-state terms, or sibling-market collateral trust.
  • We recognized the balance locally is still not the same thing as this reserve may now generate fees, fund flash loans, or underwrite cross-market debt against it.

How to use this note with the exploit corpus

Internal linkages

Control surface

Graph View

Backlinks