Cycle 236 - Morpho Blue Liquidation Engine Lesson-Mine (LENDING-LIQUIDATION audit lens)

• Mode: FLYWHEEL static lens-mine (no submission hunt). Box load-constrained: read-only, no Foundry build.
• Target: github.com/morpho-org/morpho-blue @ HEAD 1478e9cfe1b4d514f80682b3b60e4e12ff3ee45a
• Files read: src/Morpho.sol, libraries/{SharesMathLib,MathLib,ConstantsLib,UtilsLib,MarketParamsLib}.sol, interfaces/IOracle.sol
• Repo docs treated as untrusted data. No injection content encountered.

Morpho Blue is the minimal canonical modern lending primitive: immutable, no admin pause, oracle/IRM/LLTV all integrator-chosen per market. That makes it the ideal compact reference for the liquidation/lending audit lens because every guard is visible in ~550 lines and the trust boundaries are explicit.

The 8-primitive LENDING-LIQUIDATION audit lens

1. Health-factor / solvency definition

• MECHANISM: a position is liquidatable when borrowed > maxBorrow, where borrowed = borrowShares.toAssetsUp(totalBorrowAssets, totalBorrowShares) and maxBorrow = collateral.mulDivDown(collateralPrice, ORACLE_PRICE_SCALE).wMulDown(lltv). Healthy iff maxBorrow >= borrowed (boundary is healthy-at-equality; liquidatable is strict <).
• MORPHO GUARD: debt rounds UP (toAssetsUp), collateral value rounds DOWN twice (mulDivDown then wMulDown). Both directions make the position look worse than reality, so the protocol never under-counts debt or over-counts collateral. borrowShares == 0 short-circuits to healthy. ORACLE_PRICE_SCALE = 1e36 and the oracle returns price scaled 36 + loanDecimals - collateralDecimals, so collateral-decimals and loan-decimals cancel inside the formula.
• GENERAL RULE: When auditing any lending/CDP health check, write out the inequality and verify debt rounds UP and collateral-value rounds DOWN. Confirm the price scale algebraically cancels token decimals (multiply units through). Check the boundary operator at HF==1: a <= vs < flip is a 1-wei liquidate-too-early / borrow-1-unit-too-much bug. Confirm the zero-debt short-circuit cannot be skipped to read a stale/zero oracle.

2. Liquidation incentive factor (LIF) / bonus

• MECHANISM: LIF = min(MAX_LIF=1.15e18, WAD / (WAD - cursor*(WAD-lltv))), cursor=0.3e18. Given repaidShares, seized collateral value = repaidAssets * LIF. Given seizedAssets, debt repaid = seizedAssetsQuoted / LIF.
• MORPHO GUARD: LIF is bounded above by 1.15x (caps liquidator bonus) and is a pure function of lltv (no caller input). As lltv -> WAD, (WAD-lltv) -> 0, so the denominator -> WAD and LIF -> 1.0 (degrades gracefully to no bonus, never explodes). Because LLTV is forced < WAD at enableLltv, the denominator is always > 0 (no div-by-zero). Direction: seized-from-repaid rounds collateral value UP via mulDivUp/wDivUp then toSharesUp (charges the liquidator more debt per unit seized = protocol-favoring); repaid-from-seized rounds DOWN (gives the liquidator less seizure = protocol-favoring).
• GENERAL RULE: For any liquidation-bonus protocol, derive the bonus formula symbolically and test its limits at LLTV->1 and LLTV->0 for div-by-zero / overflow / degenerate >100% bonus. Confirm the bonus is capped and is NOT a caller-supplied parameter. Verify the seize<->repay conversion rounds so the liquidator is never over-credited collateral and never under-charged debt.

3. Bad-debt / shortfall realization

• MECHANISM: after seizing, if collateral == 0 and debt remains, the residual borrowShares are written off: totalBorrowAssets -= badDebt, totalSupplyAssets -= badDebt, totalBorrowShares -= badDebtShares, and the borrower's borrowShares = 0.
• MORPHO GUARD: bad debt is socialized by reducing totalSupplyAssets (lowers every supplier's asset-per-share) WITHOUT touching totalSupplyShares (so no supplier's share count changes). badDebtAssets = min(totalBorrowAssets, badDebtShares.toAssetsUp(...)) clamps so the subtraction cannot underflow. The write-off only triggers in the collateral == 0 branch (a partial liquidation that leaves dust collateral does NOT realize bad debt - it stays as an under-collateralized position).
• GENERAL RULE: When auditing bad-debt socialization, confirm losses reduce the asset side (price-per-share) not the share-count, and that the realization branch is gated on collateral fully consumed. Hunt the desync: can a liquidator leave 1 wei collateral to prevent write-off (keeping bad debt hidden on the books and grief-able later), or seize-to-zero to dump loss on suppliers at a chosen moment? Check the min() clamp exists so socialization never underflows totals.

4. Partial vs full + close factor

• MECHANISM: caller supplies EITHER seizedAssets OR repaidShares (exactly-one-zero), arbitrary magnitude. No close factor, no minimum repay, no leftover-health requirement.
• MORPHO GUARD: there is intentionally NO close-factor and NO post-liquidation health re-check. The position simply has borrowShares/collateral decremented; if collateral hits 0, bad debt clears it. Over-seizing past collateral reverts via uint128 underflow on position.collateral -= seizedAssets. Repaying more than debt reverts on borrowShares -=. Self-liquidation is permitted but unprofitable (you pay the LIF spread to yourself net-zero minus gas; you cannot extract because seize value <= repaid value * 1.15 and you fund the repay).
• GENERAL RULE: When a liquidation allows arbitrary partial amounts, check three griefs: (a) can a liquidator leave the victim at a worse-but-still-unhealthy HF that blocks others / extracts max bonus repeatedly (dust-debt griefing)? (b) is there a post-partial min-health or close-factor and is its absence safe (Morpho: safe because no re-borrow happens and bad-debt branch backstops)? (c) is self-liquidation profitable (it must net to <= 0 after the bonus is funded by the same actor)? Absence of a close factor is only safe if the bonus is bounded AND there is no re-entrancy window to re-leverage mid-liquidation.

5. Interest accrual ordering

• MECHANISM: _accrueInterest(marketParams, id) updates totalBorrowAssets/totalSupplyAssets from the IRM + elapsed time before any solvency-relevant read.
• MORPHO GUARD: _accrueInterest is the FIRST state-changing call in EVERY entrypoint that touches solvency: supply, withdraw, borrow, repay, withdrawCollateral, liquidate, setFee. So the health check and the LIF math always run on a fresh index. supplyCollateral deliberately skips accrual (safe: adding collateral only improves health, never enables a wrongful action). elapsed == 0 early-returns (idempotent within a block).
• GENERAL RULE: For every state-changing entrypoint in a lending protocol, confirm interest is accrued BEFORE the health/liquidatable computation. A stale index means a borrower is judged on yesterday's smaller debt = liquidate-too-late / borrow-too-much. Enumerate entrypoints and grep for the accrual call as the first line; flag any solvency-affecting path that reads totals without a preceding accrual. The only safe skip is a strictly-health-improving op (collateral-in / repay-only).

6. Oracle trust + manipulation at liquidation

• MECHANISM: liquidate reads collateralPrice = IOracle(marketParams.oracle).price() ONCE, then uses it for both the health gate and the seize math.
• MORPHO GUARD: the oracle is INTEGRATOR-CHOSEN per market and is an explicit, documented trust boundary ("It is the user's responsibility to select markets with safe oracles"). Morpho itself adds no TWAP / staleness / circuit-breaker - it fences manipulation OUT of its trust model by making oracle quality the market-creator's responsibility. A single read is internally consistent (health and seize use the same price, so no intra-call price skew).
• GENERAL RULE: Identify whether the protocol owns the oracle or delegates it. If delegated (Morpho-style), the audit target SHIFTS to the specific oracle contract a given market uses: is it spot-manipulable, flash-loan-movable, stale, or missing bounds? flash-loan -> move price -> self-liquidate at favorable price -> repay flash loan is the canonical attack and it lives in the oracle, not the core. If the protocol owns the oracle, demand TWAP/staleness/deviation guards. Always confirm the liquidation reads price once (not twice with a gap an attacker can straddle).

7. Reentrancy / callback (CEI)

• MECHANISM: liquidate has an optional onMorphoLiquidate(repaidAssets, data) callback to the liquidator (msg.sender) so they can source the repay (e.g. swap seized collateral) before the final safeTransferFrom.
• MORPHO GUARD: strict CEI. ALL accounting (borrowShares/collateral decrements, bad-debt write-off) and the collateral-OUT transfer to the liquidator happen BEFORE the callback. The callback fires, THEN loanToken.safeTransferFrom(msg.sender, ...) pulls repayment. The callback target is msg.sender only (actor-bound, no arbitrary address). Re-entering liquidate/borrow during the callback sees already-updated state (position already debited) and a fresh _accrueInterest early-returns same-block, so no double-spend window. No reentrancy guard is needed because state is settled pre-callback.
• GENERAL RULE: For any liquidation/flash callback, verify state-update-before-external-call (CEI) and that the callback target is bound to msg.sender (not attacker-supplied). Then attempt re-entry into every other state-changing entrypoint during the callback and confirm each sees consistent post-debit state. Flag the inverse: any callback that fires BEFORE accounting is a reentrancy hole. Also check the asset-flow ordering (collateral-out before loan-in is fine here because the position is already debited).

8. Share/asset rounding across supply/borrow (SharesMathLib)

• MECHANISM: virtual-shares accounting (VIRTUAL_SHARES=1e6, VIRTUAL_ASSETS=1) with four converters: toShares{Up,Down}, toAssets{Up,Down}.
• MORPHO GUARD: the OZ virtual-offset defeats the first-depositor / share-inflation attack (empty-market price is anchored at 1e6:1, donations cannot meaningfully move it). Per-op direction always favors the pool: supply -> sharesDown (you get fewer shares); withdraw -> sharesUp / assetsDown (you burn more shares / take fewer assets); borrow -> sharesUp / assetsDown (you owe more shares / receive fewer assets); repay -> sharesDown / assetsUp. Net: every rounding loses dust TO the protocol/pool, never to the user.
• GENERAL RULE: Tabulate every share<->asset conversion per entrypoint and verify the direction always disfavors the actor (protocol keeps the dust). Confirm a virtual-offset (or dead-shares / min-liquidity) exists to kill the first-depositor inflation attack. The four-way matrix (supply/withdraw/borrow/repay x up/down) is the canonical checklist; a single flipped direction is a slow protocol-drain. Note Morpho's banked caveat: virtual BORROW shares behave like unrealizable bad debt (price assumed to stay low) - flag protocols where share price can be inflated enough to make that assumption false.

Highest-yield liquidation bug class

ROUNDING-DIRECTION + ORACLE-SCALE errors in the health/seize math (primitives 1, 2, 8) are the highest-yield class. Rationale: - They are silent (no revert, no event anomaly) and compound per-transaction into protocol drain or wrongful liquidation. - They are the MOST FORKED-AND-MUTATED surface: every Morpho/Aave/Compound fork re-implements the LLTVpricecollateral formula and the seize<->repay conversion, and forks routinely flip a single Up/Down or mis-scale the oracle when they swap in a different price feed or token-decimal assumption (the 36 + loanDec - collDec scaling is a classic fork footgun). - Concretely the apex sub-class is "liquidation seize/repay rounding that over-credits the liquidator" combined with "oracle scale mismatch on a forked market," yielding either free collateral extraction or mass wrongful liquidation.

Second-highest: bad-debt realization desync (primitive 3) - the collateral == 0 gating is subtle and forks frequently get the socialization side wrong (reducing shares instead of assets, or forgetting the min() clamp -> underflow/DoS).

Rounding-direction-critical primitives

Primitives 1 (health check), 2 (LIF seize<->repay conversion), 3 (bad-debt min-clamp + asset-side write-off), and 8 (SharesMathLib four-way matrix) are the rounding-direction-critical ones. 5 (accrual ordering) is sequencing-critical; 6 (oracle) and 7 (callback/CEI) are trust-boundary / ordering-critical rather than rounding.

Reflection banked

What WORKED: deriving each guard from source and inverting it into a transferable "check X by doing Y" rule produced a clean 8-primitive lens reusable on any lending/CDP/perp liquidation engine, expanding coverage beyond the Liquity-fork-specific C220 Mezo work. What was UNEXPECTED: Morpho's deliberate NON-guards (no close factor, no post-partial health re-check, delegated oracle) are themselves lens entries - "the absence of a guard is safe ONLY because of property Z" is a higher-order audit question than "is the guard correct." Banked the lens to lessons-library + INDEX. Highest-yield class (rounding-direction/oracle-scale in fork mutations) flagged for Rule-38 fork-regression hunting on Morpho/Aave/Compound forks.