Morpho Blue Supply Shares vs Assets

Morpho Blue supply shares are internal units of a lender's position; assets are units of the market's loan token. Convert with the market's accrued totals, one virtual asset and one million virtual shares. Asset-sized supplies round shares down; asset-sized withdrawals round shares up. To close a lender position, specify its full share balance and check available liquidity separately.

Read the direct Blue position

In a direct Blue market, position(id, user).supplyShares records the lender's shares. These internal units are non-transferable. A Morpho Vault share token belongs to a separate layer, with its own accounting. Morpho's market-mechanics documentation distinguishes these market positions from ERC-4626 vaults.

This walkthrough follows variable-rate Blue code at reference commit 8e26ca6a8dbc, checked on 28 October 2026. It does not establish the code at a particular deployed address. Vault V1, Vault V2 and Midnight fixed-rate markets are outside its scope.

Start with the chain, Morpho contract and exact market. The market-ID versus token-pair guide explains why naming two tokens does not identify every market parameter. Then distinguish the loan token supplied by lenders from the collateral token posted by borrowers.

An asset amount here is a loan-token quantity, without an assumed dollar value. A share count needs a conversion before token decimals can format its asset equivalent. The Aave scaled-balance example illustrates a different implementation: Aave applies a normalized-income index. Blue uses its market's supply assets and supply shares.

Include the virtual units before rounding

Let A be totalSupplyAssets and S be totalSupplyShares, both after the relevant interest accrual. Let a be an asset input and s a share input. The pinned SharesMathLib adds one raw asset unit and 1,000,000 raw share units to its conversions:

• Assets to shares: multiply a by (S + 1,000,000) / (A + 1).
• Shares to assets: multiply s by (A + 1) / (S + 1,000,000).

Apply the operation's rounding after that multiplication and division. At an empty market, supplying one asset base unit therefore produces 1,000,000 share units. Those shares do not mean one million whole loan tokens.

The virtual quantities are calculation terms. They do not appear as spendable tokens or redeemable wallet shares, and should not be added to a cash-flow ledger. Omitting them can change an exact result even when a plain A/S ratio looks close.

The core supply and withdrawal branches select the following directions:

Exactly one of the assets and shares inputs must be zero. Choosing the input determines what stays fixed; reversing a rounded output from another branch can leave a different position.

The ERC-4626 shares-versus-assets guide covers similar directional questions for standardized vault methods. Its particular virtual-offset example cannot replace Blue's constants or function calls.

Follow a 401-unit supply through a complete exit

This is a hypothetical integer ledger, constructed to expose rounding. U is a fictional six-decimal loan token. Every asset amount below is a raw base-unit integer: 401 means 0.000401 U. Shares remain raw internal integers throughout.

Assume ordinary token transfers, sufficient balances and approvals, an authorized caller and a valid receiver. The market fee is zero throughout. Other lenders initially own 799,000,001 shares; Alice owns none. Opening supply assets are 999 and borrow assets are 600. The opening snapshot has just accrued interest, so Alice's supply triggers no additional accrual.

Entry credits an integer share amount

Alice specifies 401 assets and zero shares. The conversion before rounding is:

401 × 800,000,001 / 1,000 = 320,800,000.401 shares.

Rounding down credits 320,800,000 shares. The market adds the full 401 asset units, without pretending that the fractional 0.401 share was issued. Using the unadjusted ratio would instead produce 320,719,720 shares after flooring, which fails to reproduce the library.

Immediately after entry, converting Alice's actual shares back to assets and flooring gives 400. A supply followed by a share-sized exit can therefore return less than the input even with a zero market fee. This example deliberately makes an asset base unit large relative to the position so that the effect is visible.

Accrual changes assets before the next withdrawal

For the next observation, assume 31,536,000 seconds have elapsed and the selected interest-rate model returns a raw per-second borrow rate of 1,000,000,000 for that accrual call. The rate uses a 10^18 scale. These invented inputs describe one calculation; they do not characterize every Blue IRM or quote a live rate.

The pinned MathLib interest calculation uses a three-term Taylor approximation with integer divisions. For these inputs, its scaled factor is 32,038,486,841,419,776. Applying it to the 600 borrowed units gives:

floor(600 × 32,038,486,841,419,776 / 10^18) = 19.

Accrual adds 19 to both borrow assets and supply assets. Borrow assets become 619 and supply assets become 1,419. With the stipulated zero fee, supply shares stay unchanged. Alice's rounded asset equivalent now becomes 406, using 320,800,000 shares and the updated totals.

This is accounting accrual. The interest step does not transfer 19 loan-token base units into Morpho: supply assets minus borrow assets remain 800. Assume the partial and final withdrawals below occur at that same timestamp, without other activity or further accrual.

A 100-asset withdrawal removes shares rounded up

Alice now fixes the withdrawal at 100 assets. The share cost is:

ceil(100 × 1,120,800,001 / 1,420) = 78,929,578.

Flooring that expression would give 78,929,577 shares. At this state, those fewer shares pay only 99 asset units when converted down. The upward rounding supplies the share cost required by the asset-sized branch.

After the successful withdrawal, Alice has 320,800,000 − 78,929,578 = 241,870,422 shares. Market supply assets fall to 1,319 and supply shares fall to 1,040,870,423. Use these new totals for the next calculation.

All remaining shares close the position

For the final exit, Alice specifies zero assets and her remaining 241,870,422 shares. The asset payment is:

floor(241,870,422 × 1,320 / 1,041,870,423) = 306.

The confirmed operation removes every remaining Alice share and pays 306 asset units. Morpho's withdrawal reference recommends the share input for withdrawing a full position.

Substituting an asset amount produces two instructive alternatives at the pre-exit state. Asking for 306 assets removes only 241,524,508 shares, leaving 345,914 shares behind. Rounding the asset estimate upward and asking for 307 instead requires 242,313,803 shares, more than Alice owns, so that request reverts. Neither substitution reproduces a full-share exit.

Alice receives 100 plus 306, or 406 asset units in total. Against her 401-unit supply, the completed flow leaves a five-unit increase, equivalent to 0.000005 U. It includes the example's accrual and rounding; it is not the market's entire 19-unit interest amount.

The market closes at 999 + 401 + 19 − 100 − 306 = 1,013 supply assets. Its shares return to the other lenders' 799,000,001. Virtual units never enter either reconciliation.

An asset equivalent does not establish exit liquidity

Before Alice's final exit, supply assets minus borrow assets are 1,319 − 619 = 700. Her 306-unit exit fits. The core withdrawal checks that remaining supply assets still cover borrow assets. A valid share conversion alone does not satisfy that liquidity condition.

Ordinary lender shares can stay fixed while fees change total supply shares. The pinned interface warns that stored totals omit pending interest and pending fee-recipient shares. A nonzero market fee therefore requires an accrual calculation that includes those additional shares. Realized bad debt can also reduce supply assets in the core liquidation path; this example assumes none.

Keep borrow-share conversions in their own ledger. The borrow-shares versus repay-assets example follows that separate denominator and repayment rounding.

Reproduce the intended operation at one state

Save the exact market parameters, owner, receiver, observation block and raw position shares. Read the market's supply totals, borrow assets, last-update timestamp and fee at that same state. Mixing an old share denominator with newly accrued assets produces an explanation that no transaction actually used.

For a later timestamp, the pinned MorphoBalancesLib projects market balances after accrual. Its expectedSupplyAssets helper rounds down, and explicitly warns that it omits the fee recipient's pending position-share increase. Treat that account separately. An expected balance remains an estimate for a state, not an execution lock.

Choose the transaction input from the actual objective: assets for an exact token withdrawal, or the current share balance for a full exit. Recompute with the matching upward or downward conversion, then check position ownership, authorization and market liquidity. Core withdraw has no separate minimum-assets or maximum-shares argument; check any wrapper's enforced bounds when converting off chain.

After confirmation, retain both quantities from the Supply or Withdraw event, and verify the recipient's actual token movement. For this fixture, the final record is 241,870,422 shares removed, 306 raw assets received, zero Alice supply shares remaining, and the new market totals. Those integers let another reader reproduce the exit without guessing from a rounded balance display.