Morpho Vault V2 absolute caps limit an ID's allocation in raw units of the vault asset. Below 100%, relative caps limit it as a WAD-scaled fraction of firstTotalAssets, the transaction's initial accrued asset total. At 100%, the relative comparison is skipped. An allocation must satisfy the applicable checks for every ID returned by its adapter. Lowering either cap can leave existing exposure above the new limit; it does not withdraw assets.
Read the amount and percentage in their own units
An absolute cap answers how many underlying asset units an allocation may contain. A relative cap answers how large that allocation may be against the vault's reference asset total. Morpho's Vault V2 overview describes these controls as limits on shared risk identifiers, such as a collateral or a market.
This explanation follows VaultV2 and MorphoMarketV1AdapterV2 at reference commit a0ba9df, checked on 29 October 2026. Applying it to a live vault requires identifying that vault's chain, implementation and adapters. Vault V1 supply caps and direct Blue position accounting are separate implementations.
The contract reference groups three values under each ID:
| Value | Unit | Meaning |
|---|---|---|
allocation(id) | Raw vault-asset units | Recorded exposure associated with this ID |
absoluteCap(id) | Raw vault-asset units | Fixed ceiling for that exposure |
relativeCap(id) | WAD-scaled fraction | Relative ceiling, with 10^18 representing 100% |
For a six-decimal asset U, an absolute cap of 3,600 U is the integer 3,600,000,000. WAD represents one whole as 10^18, so a relative cap of 25% is 250,000,000,000,000,000. Token decimals format the first number; they do not change the percentage's WAD scale. Neither amount implies a dollar value.
These caps constrain an underlying-asset allocation. Blue's internal supply shares must first be valued in assets; the Morpho Blue shares-versus-assets example follows that conversion. Substituting the adapter's raw share count into a cap comparison mixes units.
Apply both checks to every returned ID
For a relative cap below 100%, define F as firstTotalAssets, r as the WAD fraction, A as the absolute cap, and q as the recorded allocation. The relative asset ceiling is:
Relative ceiling = floor(F × r / 10^18).
With a positive absolute cap, the two ceilings combine as:
Effective ceiling = min(A, relative ceiling).
When a transfer increases allocation one-for-one, additional headroom is:
Headroom = max(0, effective ceiling − q).
The integer math library floors the multiplication/division result. For example, F of 8,000,000,003 raw U units at 20% gives 1,600,000,000 raw units. The remaining 0.6 of a base unit cannot enlarge the permitted allocation.
Two implementation details qualify those formulas. A zero absolute cap blocks allocation. At r = 10^18, the allocation branch skips the relative comparison entirely; it does not enforce F as another ceiling. The absolute check still applies.
The named adapter returns three IDs: its adapter ID, a shared collateral-token ID, and an adapter-specific market ID. Each receives the signed allocation change. The pinned adapter compares its new expected market assets with the previously recorded market allocation to calculate that change. Accrued interest or losses can therefore make the change differ from the amount transferred.
An allocator needs room under every returned ID. A market may have 500 U of room while its shared collateral has only 100 U. Under an exact-transfer assumption, the latter limits an additional allocation to 100 U. Adding those two rooms together would misread overlapping exposure limits.
Identify the scope before doing the arithmetic. The cap ID and idData guide explains the raw setter bytes and hashed getter keys. An accurately calculated percentage for the wrong ID still describes the wrong limit.
Follow a deposit, withdrawal and cap reduction
This is a hypothetical cap ledger, using fictional six-decimal asset U. The vault begins with 10,000 U: 2,000 U allocated to the target market and 8,000 U idle. Its market cap is 3,600 U absolute and 25% relative. All other returned IDs have positive, nonbinding caps.
Assume no interest, losses, donations, fees or rounding losses during the sequence. Adapter changes equal transfers exactly. There is no configured liquidity adapter, so deposits remain idle. Callers have the required authority, share balances and approvals, gates permit the actions, and the market can return the modeled deallocations.
Each completed row below is followed by a fresh transaction. With these assumptions, the vault-assets column supplies F for the next allocation check. The ceiling column uses the caps active in that row.
| Completed event | Vault assets U | Target allocation U | Effective ceiling U | Extra room U |
|---|---|---|---|---|
| Opening state | 10,000 | 2,000 | 2,500 | 500 |
| Deposit 6,000 to idle | 16,000 | 2,000 | 3,600 | 1,600 |
| Allocate 1,600 | 16,000 | 3,600 | 3,600 | 0 |
| Withdraw 8,000 from idle | 8,000 | 3,600 | 2,000 | 0 |
| Lower caps to 1,800 and 20% | 8,000 | 3,600 | 1,600 | 0 |
| Deallocate 1,000 | 8,000 | 2,600 | 1,600 | 0 |
| Deallocate another 1,000 | 8,000 | 1,600 | 1,600 | 0 |
A growing vault changes which cap binds
Initially, 25% of 10,000 U is 2,500 U. The relative ceiling binds before the 3,600 U absolute ceiling. An extra 501 U would produce 2,501 U of exposure: the absolute comparison passes, but the relative comparison fails. That attempted allocation reverts and leaves the opening position unchanged.
After the separate 6,000 U deposit completes, the next transaction starts with 16,000 U. Its relative ceiling is 4,000 U. The unchanged absolute cap now binds at 3,600 U, allowing 1,600 U more. Moving that amount into the market leaves 12,400 U idle and 3,600 U allocated. Total assets remain 16,000 U because the movement stayed inside the vault's holdings.
The Yearn idle-versus-debt ledger illustrates the same need to separate location from income. Its reporting rules differ from Morpho's; the shared accounting lesson is to avoid recording an internal allocation as a new deposit or profit.
A withdrawal from idle leaves the allocation in place
A user next withdraws 8,000 U from the 12,400 U idle balance. The target remains 3,600 U, idle becomes 4,400 U, and vault assets fall to 8,000 U. The target now represents 45% of the vault.
The 25% cap has not changed. Its ceiling for the next fresh transaction is 2,000 U, leaving existing exposure 1,600 U above it. Morpho's deposit and withdrawal guide separates withdrawal liquidity from allocation caps. A relative cap does not reserve the denominator against user withdrawals.
A lower cap changes policy before assets move
Now the Curator or a Sentinel lowers the absolute cap to 1,800 U and the relative cap to 20%. The new relative ceiling is 1,600 U, making the existing 3,600 U position 2,000 U too large for another ordinary allocation check. Idle remains 4,400 U. Neither cap-setting call returns any U from the market.
An authorized 1,000 U deallocation brings the target to 2,600 U and idle to 5,400 U. The deallocation loop permits a partial reduction even though the remaining position exceeds both new caps. A second 1,000 U deallocation brings the target to 1,600 U and idle to 6,400 U. Together they reconcile to the unchanged 8,000 U total.
The official market-delisting procedure similarly separates cap reduction from asset withdrawal. A low or zero cap should never be reported as proof that the position has already been emptied. The Curator, Allocator and Sentinel guide details the authority needed for these separate actions.
Use the transaction's initial total for relative caps
For a nonempty vault, the first accrual establishes firstTotalAssets for that transaction. Later deposits in the same transaction do not expand it. The pinned core's accrual and entry paths implement that ordering. Its accrued total also need not equal an unrestricted sum of adapter valuations because recognized growth is limited by maxRate.
Consider a separate illustration with 10,000 U at first accrual and zero starting exposure to a liquidity-adapter target. Set that target's absolute cap to 3,600 U and its relative cap to 25%; assume every other check passes. A 3,000 U deposit routed into that target faces a relative ceiling of 2,500 U.
Using the post-deposit 13,000 U total would suggest 3,250 U of relative capacity. That calculation predicts acceptance, but the transaction's fixed denominator rejects the 3,000 U allocation. The whole deposit reverts. The earlier ledger's larger capacity became available in a later transaction after the idle deposit had completed.
Validate the allocation and the asset movement separately
Read the asset address, decimals, adapter and all returned IDs at one block. Record each allocation and both caps. Check shared IDs across other funded markets rather than examining only the proposed destination.
Next, calculate each ending allocation using the adapter's expected signed change. Simulate the complete intended call sequence so the denominator reflects its first accrual. A transfer-sized headroom estimate is useful only when valuation updates and rounding do not change that signed delta. Check token balances, gates, caller authority and market liquidity separately; cap room establishes none of them.
For a reduction, retain both confirmed cap settings and the later deallocation evidence. Compare the target's recorded allocation with expected underlying assets, then reconcile the vault's idle token balance. Interest and losses can separate stored allocations from current valuations, so a stale getter alone is insufficient. Caps constrain allocation actions; they do not insure the assets or establish recoverability.
In the worked ledger, the final evidence should show the reduced caps, a 1,600 U target position, 6,400 U idle and 8,000 U total. Confirm those quantities before describing the 2,000 U exposure reduction as completed.