In a Morpho Blue market, totalSupplyAssets records the aggregate supplied loan assets, including interest through the last accrual. Immediately available withdrawal liquidity is totalSupplyAssets minus totalBorrowAssets at the same state. A lender also needs enough supply shares. Accruing interest increases both asset totals equally, so a growing supply claim can coexist with unchanged withdrawal liquidity.
That distinction answers a practical question: why can a position worth more than 400 loan tokens support a withdrawal of only 100? The position measures an accounting claim. The liquidity calculation measures how many loan tokens the market can release before its remaining supply falls below outstanding borrowing.
This article covers a direct lender position in a variable-rate Morpho Blue isolated market. It follows the EVM reference code at commit 8e26ca6a8dbc5089edcd67fb576248810fd2870a, checked on 28 October 2026. It does not identify a live deployment or describe Vault V1/V2 redemption or Midnight fixed-rate lending.
Put supply, borrowing and liquidity in the same unit
Morpho's Blue contract reference separates a market's asset totals from its supply and borrow shares. Asset totals are amounts of the market's loan token. Shares are internal accounting integers used to allocate those amounts among positions.
| Quantity | Meaning for a lender | Common interpretation error |
|---|---|---|
| Total supply assets | Aggregate loan-asset supply accounting | Treating the entire total as idle tokens |
| Total borrow assets | Outstanding loan-token debt, including recognized interest | Subtracting only original borrow principal |
| Supply shares | The lender's internal position units | Reading the integer as a token amount |
| Market liquidity | Supply assets less borrow assets | Adding collateral value to it |
| Lender's asset claim | Supply shares converted using current market totals | Assuming the whole claim is withdrawable now |
Use raw integers for the calculation and token decimals for display. Keep every input on the same chain, market and observation block. Morpho tracks several markets in one contract; that contract's overall loan-token wallet balance does not identify the liquidity attributable to one market. The per-market accounting boundary appears in the pinned market mappings and withdrawal implementation.
Collateral is a separate entry in the position. Depositing more collateral can change a borrower's room to borrow, but it does not supply loan assets to lenders. The LTV versus liquidation-threshold guide explains borrower-side limits in an Aave-style model. Blue's lender withdrawal needs its own accounting test; those Aave parameters do not apply to it.
Follow interest without inventing a cash inflow
Consider an entirely hypothetical market with a fictional six-decimal loan token, U. Alice supplies 400 U and another lender supplies 600 U before any interest accrues. A valid borrower then takes 900 U. Assume ordinary token transfers, zero market fee, valid authorization and no other operations or losses.
The initial 1,000 U supply corresponds to 1,000,000,000 raw asset units. Alice owns 400,000,000,000,000 supply shares out of 1,000,000,000,000,000. These share counts follow the empty-market conversion in SharesMathLib.
Now stipulate that the next accrual calculates exactly 9 U of interest. This is an illustrative output, with no implied rate or elapsed duration. The interest-rate documentation explains why stored totals stop at the last accrual. The actual interest calculation depends on the selected market's interest rate model, or IRM. A current rate read alone does not establish the accumulated amount.
| Observation | Supply assets | Borrow assets | Supply less borrow | Alice's asset claim |
|---|---|---|---|---|
| After the 900 U borrow | 1,000 U | 900 U | 100 U | 400 U |
| After 9 U interest accrues | 1,009 U | 909 U | 100 U | 403.599999 U |
The pinned expected-market-balances calculation adds the same interest integer to supply and borrowing. Interest creates a larger receivable from borrowers and a matching supply balance. It does not transfer 9 U into the contract. The subtraction remains 1,009 − 909 = 100 U. Alice's shares stay unchanged in this zero-fee example, while their conversion value grows.
The exact 403.599999 U requires Blue's conversion rules. The library adds one virtual raw asset unit and 1,000,000 virtual shares. In this six-decimal example, that virtual asset is 0.000001 U. It is not one whole U or spendable market liquidity.
For a full-share withdrawal, convert Alice's shares downward:
assets = floor(shares × (supply assets + 1) ÷ (total supply shares + 1,000,000)).
Using raw integers gives floor(400,000,000,000,000 × 1,009,000,001 ÷ 1,000,000,001,000,000) = 403,599,999. Applying six decimals gives the table's result. Simply multiplying 1,009 U by 40% gives 403.6 U and misses one raw unit in this fixture.
The Aave scaled-balance ledger illustrates a different conversion system. The shared lesson is to retain the stored position units and implementation-specific rounding. Blue uses market shares and virtual constants here, rather than an Aave income index.
Test the withdrawal against both limits
Start from the post-interest row. Hold the state fixed for each proposed request. Alice's candidate withdrawal bound is the smaller of her rounded asset claim and market liquidity: 100 U. This bound assumes the caller and dependencies satisfy the remaining transaction checks.
Blue's withdrawal first accounts for interest. An asset-denominated request converts to shares with upward rounding; a share-denominated request converts to assets with downward rounding. The call then reduces supply and requires remaining borrow assets to be no greater than remaining supply assets. See the pinned withdrawal path.
| Independent request | Hypothetical remaining supply | Borrow assets | Result under the assumptions |
|---|---|---|---|
| Withdraw 80 U | 929 U | 909 U | Fits; 20 U liquidity remains |
| Withdraw 100 U | 909 U | 909 U | Fits; liquidity reaches zero |
| Withdraw 101 U | 908 U | 909 U | Fails the liquidity condition |
| Withdraw all Alice's shares | 605.400001 U | 909 U | Fails the liquidity condition |
Each row resets to the same starting state; they are not successive transactions. The failed rows show hypothetical arithmetic only. A reverted call does not leave Alice's position partly withdrawn or commit those reduced totals.
For the successful 100 U request, upward conversion burns 99,108,027,751,132 supply shares. Alice retains 300,891,972,248,868 shares. Converting that remainder against the resulting totals gives 303.599999 U. Her remaining claim survives even though the market now has zero available loan liquidity.
Passing every supply share is the documented way to request a full position withdrawal. It avoids guessing the asset amount after conversion. It does not tell Blue to find the largest partial withdrawal: the full-share call still fails when its converted amount exceeds market liquidity. The official interface comments describe that full-withdrawal input and the authorization requirement.
Identify the operation that changes available tokens
Return to the 1,009 U supply and 909 U borrow snapshot, before any Alice withdrawal. Compare three independent, otherwise valid operations with no further accrual:
| Operation | New supply assets | New borrow assets | New liquidity |
|---|---|---|---|
| Borrower repays 50 U | 1,009 U | 859 U | 150 U |
| Another lender supplies 50 U | 1,059 U | 909 U | 150 U |
| Borrower borrows another 50 U | 1,009 U | 959 U | 50 U |
A repayment brings back loan tokens and reduces debt. New supply brings in loan tokens and creates the new lender's shares. Another borrow consumes loan tokens. These are separate actions in the Blue supply, borrow and repay reference. In these fixtures Alice's rounded claim remains 403.599999 U, even as the amount available to her changes.
These transitions are different from adding borrower collateral or changing its oracle price. A higher collateral valuation does not pay a supplier. The Blue oracle-scaling guide covers that separate valuation calculation. Keeping valuation outside the cash subtraction prevents a collateral-rich market from appearing to have loan tokens it cannot release.
A nonzero protocol fee also needs careful treatment. Blue mints supply shares to the fee recipient during accrual; the fee is not subtracted as a loan-token cash payment. With the same 9 U interest and an illustrative 10% fee, assume Alice is not the fee recipient. Her exact claim would be 403.239999 U after fee-share dilution, while liquidity would still be 100 U. The pinned expected-balances helper includes the fee-share adjustment. Its individual supply-balance helper also warns about pending fee shares for the fee recipient.
For the relationship between utilization and earned interest, use the Blue borrow-rate versus supply-rate explanation. A higher displayed rate does not itself replenish withdrawal liquidity or establish when borrowers will repay.
Record what an executable withdrawal depends on
Build a reproducible record before interpreting a screen's “available” amount:
- Identify the chain, Blue contract, market ID and all five market parameters. Record the lender, caller and receiver.
- Read the market totals, last-update timestamp, fee and lender supply shares at one block. Keep raw loan-token units and token decimals.
- Account for pending interest using the actual IRM. Include fee shares when calculating the lender's conversion. Preserve both stored and expected values; an expected-balance helper is a view, not an executed update.
- Calculate current market liquidity and the rounded owner claim separately. For an asset request, verify the required upward-rounded share burn against owned shares.
- Simulate the exact call, then reconcile confirmed share changes and receiver token receipts. Another participant can consume liquidity before execution.
An interface can also show liquidity that an allocator could move into the market. Morpho's shared-liquidity documentation distinguishes current market liquidity from reallocatable liquidity and states that neither is reserved. A withdrawal relying on reallocation includes an additional operation, its permissions and its limits. It is a different state transition from the unchanged-market calculation above.
For this ledger, record “403.599999 U claim; 100 U current market liquidity” as two fields. Keep the proposed withdrawal and its simulation block beside them. That record explains both Alice's accrued balance and the exact condition preventing the rest from leaving immediately.