Aave Supply Cap vs Borrow Cap: A Reserve Ledger

In Aave V3, a supply cap limits new supplies into a reserve, while a borrow cap limits new borrowing of that reserve's asset. Both are reserve-wide limits, separate from your account's collateral capacity and the tokens available for withdrawal. A full cap does not by itself stop repayment or withdrawal; those actions still face their own checks.

A cap answers whether a particular kind of exposure may grow. To explain a rejected transaction, also track what the reserve owes suppliers, what borrowers owe the reserve, and how much underlying liquidity remains.

The implementation details below use the Aave V3 Origin v3.7 source at commit cff15de6. This identifies inspected code, not the version deployed by every market. Aave's current V4 Hub documentation instead exposes per-asset configurations for Hub/Spoke pairs. Keep that architecture separate from this V3 reserve example.

Start with the action being attempted

A reserve is a particular token within a particular pool. Its parameters can differ across markets, even for the same token. A supply cap or borrow cap is therefore neither a wallet-wide allowance nor a universal limit attached to a ticker. Aave V3 reserve documentation.

The four ordinary actions change different balances:

Supply creates aTokens representing the supply position; withdrawal burns them. Borrowing creates debt, and repayment reduces it. These are the ordinary underlying-token routes described in the V3 Pool reference. Repayment using aTokens has a different cash effect, considered below.

Consequently, supplying checks the supply cap and borrowing checks the borrow cap. Neither repayment nor withdrawal applies either cap as its admission test in the inspected validation functions. Amount, reserve status and account constraints still matter. A borrower also needs sufficient collateral support; LTV versus liquidation threshold explains that separate account calculation.

Follow one illustrative reserve through eight requests

This is a constructed educational ledger, not an observed Aave market. Token T is invented. Set its supply cap to 1,000 T and borrow cap to 800 T. Start with 1,000 T of supplied claims, 700 T of debt and 300 T of available underlying.

For this sequence, freeze interest accrual, use indices of one, and exclude treasury accrual, deficits, fees and rounding. Assume virtual liquidity matches transferable underlying, transfers behave normally, all account permissions pass, and each withdrawing supplier has enough claims and no collateral constraint. Borrowers have adequate collateral elsewhere in the same pool. These assumptions isolate cap and liquidity effects.

Every row follows the preceding row. A rejected request leaves all balances unchanged.

Initially, supply headroom is zero and borrow headroom is 100 T. Request 1 would raise supply to 1,050 T, exceeding its cap. Request 2 leaves supply unchanged and raises debt exactly to 800 T, so the two cap tests lead to different outcomes.

Request 3 returns 150 T from a borrower's external balance. Debt falls to 650 T and cash rises to 350 T. Suppliers still hold 1,000 T of claims: ordinary repayment did not mint or burn those claims. Another supply remains blocked even though the reserve has more cash and 150 T of borrow-cap room.

Request 4 burns 200 T of a supplier's claims and transfers 200 T out. Supply becomes 800 T; debt remains 650 T. The next 150 T borrow reaches the borrow cap and empties the remaining cash. Now 200 T of supply-cap headroom exists alongside zero available liquidity.

That is why request 6 cannot withdraw 25 T. Its problem is liquidity, rather than either cap. Request 7 replenishes cash by supplying within the supply cap, but it leaves debt at 800 T. The final borrow therefore fails despite 100 T of cash being present.

Each accepted transition preserves the simplified identity supplied claims = cash + debt. The pinned supply and withdrawal logic updates reserve liquidity as funds enter or leave. Actual accounting needs more fields than this deliberately simplified identity.

Reconstruct what the cap actually counts

Do not substitute idle cash for supply-cap usage. In the pinned implementation, the supply test combines existing scaled aToken supply, the proposed scaled mint and scaled treasury accrual, then converts that total at the updated liquidity index. The borrow test converts existing plus proposed scaled variable debt at the updated variable borrow index. Both compare the result with the respective nonzero cap multiplied by the reserve's decimal unit. V3 cap validation source.

Accrued treasury claims matter even before their aTokens are minted. A screen showing only the visible aToken total can therefore understate the quantity relevant to the supply test. Likewise, original borrowed principal understates debt after interest accrues. The liquidity index versus variable borrow index guide explains why the two sides need different conversions.

A configured cap is expressed in whole tokens, whereas transaction amounts use raw token units. For a hypothetical six-decimal T, an 800-token cap corresponds to 800,000,000 raw units. Comparing that 800 directly with a raw 1-token request of 1,000,000 units would manufacture a false rejection.

In this implementation, zero means that the respective cap check is bypassed. Record “uncapped” distinctly from “zero headroom”; other reserve restrictions continue to apply.

Even a correctly converted cap difference is an estimate of room, not a promised maximum transaction. The pinned TokenMath library rounds supply minting and debt minting differently. Use the implementation's integer arithmetic when evaluating an amount at the boundary.

Repayment does not always replenish cash

The table used repayment with underlying tokens from outside the reserve. Aave also supports repayment with the same reserve's aTokens. In the pinned BorrowLogic implementation, this burns supplied claims and debt while adding no underlying liquidity.

For a separate illustrative branch, return to request 5's state: 800 T of claims, 800 T of debt and no cash. Suppose an eligible borrower also owns 50 T of aTokens and repays 50 T using them, with account checks satisfied. Claims and debt both become 750 T; cash stays zero. Supply-cap headroom becomes 250 T and borrow-cap headroom becomes 50 T, yet a new underlying borrow still needs liquidity.

A transaction labeled “repay” is therefore insufficient evidence of cash returning. Retain the method and asset flows. This also explains why a cap chart cannot replace a liquidity reconstruction. The utilization and borrow-APR guide addresses a different question: how a specified pool state feeds its rate model.

Above-cap usage does not erase an existing position

Interest accounting can grow balances without a new supply or borrow. The pinned ReserveLogic source updates indices and treasury accrual without using these caps as an interest stop. A cap limits admission of new exposure; it does not freeze the accounting balance at that number.

Consider another constructed snapshot starting with 1,000 T of claims, 800 T of debt and 200 T of cash. Assign 5 T of borrower interest, with 4.5 T attributable to supplier claims and 0.5 T to treasury claims. This is a bookkeeping illustration, not a simulation of V3's elapsed-time interest formulas. Supply-cap usage becomes 1,005 T, debt becomes 805 T, and cash remains 200 T. Both usages exceed their original caps.

A hypothetical 10 T underlying repayment leaves 795 T of debt and 210 T cash while supply-cap usage remains 1,005 T. A subsequent eligible 20 T withdrawal reduces usage to 985 T and cash to 190 T. The actions that reduce or settle claims remain distinct from requests that create new exposure.

Caps can also be lowered. The pinned PoolConfigurator setters change configuration and emit events; these setters do not themselves unwind existing positions. A cap crossing alone is not the account's liquidation test.

Older V3 configurations can add another limit: an isolation debt ceiling. The v3.7 configuration source marks that older field unused. Its accounting boundary differs from an asset's borrow cap, as the isolation debt ceiling versus borrow cap comparison shows. Identify the implementation before applying that older mechanism to a market.

Build a transaction worksheet at one block

Use the following record to diagnose a proposed action. The pinned data provider returns caps in borrow-then-supply order and exposes reserve accounting fields, including a separate virtual-liquidity getter. Confirm that the provider belongs to the intended pool.

Reconstruct the relevant usage after the proposed action, then check liquidity and account eligibility separately. Simulate against the identified deployment when possible. A successful simulation describes its observed state; another transaction, interest accrual or a parameter change can alter the result before inclusion.

After confirmation, reconcile the actual claim, debt and underlying changes. If they differ from the worksheet, first check whether the repayment used aTokens, whether the observation blocks match, and whether updated indices or treasury claims were omitted. Save these three results with the confirmation block: cap permission, available liquidity and account eligibility.