Skip to main content

Redemption mechanism

Multi-branch RD-for-collateral exchange at par, modulo a small per-branch fee and a 0.25% protocol fee. This page covers the on-chain flow in full. User view is Redemption.

This describes normal-mode redemption. Shutdown (of a branch or the whole system) uses a different mechanism and pricing schedule; see Shutdown redemption.

Entry point​

Aggregator.redeemCollateral(
uint256 _RDamount,
address[] _firstRedemptionHint, // one per branch
address[] _upperPartialRedemptionHint, // one per branch
address[] _lowerPartialRedemptionHint, // one per branch
uint256[] _partialRedemptionHintNICR, // one per branch
uint256 _maxIterations // gas cap per branch
)

All four hint arrays must equal troveManagers.length. Pass address(0) and 0 for slots corresponding to shutdown / zero-weight branches; the Aggregator skips them.

_RDamount is the maximum to redeem. It must fit the available redemption quota, and the caller's RD balance must cover _RDamount plus the 0.25% redemption protocol fee on it. Redemption is disabled during the 14-day bootstrap period. _maxIterations = 0 means no iteration cap.

Step-by-step​

Aggregator.redeemCollateral(…)anyone can call · reverts during the 14-day bootstrapRefill the quota, check the requestrequest ≤ quota · RD balance ≥ request + 0.25% feeSnapshot parrateParControl.par() — one par for every branchCompute basket weightsweight = base debt EMA · shutdown & Redemption-Shield-only → 0For every branch with weight > 0slice = RD × weight ÷ Σ weightssink branch active? each slice is trimmed (see below)Redemptions.redeemCollateral(slice, hints, fee, par)the slice walks that branch’s book — next figurereverts if any branchcan be shutdownAnything redeemed, branches filled evenly?noRevertyesDeduct the redeemed total from the quotaburn redeemed RD + 0.25% protocol feeIf a bad-debt sink branch existsfee + haircut RD → payDebt(…) on the sink branchCollateral basket to the redeemer · fee → GlobalFeeRouter
One call, every branch. The requested amount must fit the quota up front. The Aggregator then snapshots par once, splits the request by basket weight, and lets each branch walk its own book (next section). Only the RD actually redeemed is taken from the quota. A branch may fall short only if it runs out of redeemable troves; any other uneven fill, or a revert in any branch, reverts everything.

A revert in any branch reverts the whole transaction. A normal redemption on a branch reverts if that branch is eligible for shutdown (BorrowerOperations.canShutdown()), if its collateral pools are underbacked, or if the price read reports an oracle failure; the branch has to be shut down first, which removes it from the basket.

Basket weights​

base debt EMABASKET WEIGHTWETH→48.8%wstETH→18.6%WBTC→16.3%rETH→10.5%weETH→5.8%tBTC→weight 0 · Redemption Shield enabled for all trovesPAXG→weight 0 · branch in shutdown
Each branch's weight is its base debt EMA (72-hour half-life), and the weights are normalized across the branches that qualify. A branch in shutdown, or one whose troves all have Redemption Shield enabled, has weight 0 and is skipped entirely. Values are illustrative.

The EMA has a 72-hour half-life. Using an EMA rather than spot debt makes the weights smoothly responsive, so a sudden borrowing surge on one branch does not immediately redirect all redemption pressure there.

Weights are read from Aggregator.redemptionBasketWeights(). A branch whose current debt without Redemption Shield is zero (only troves with Redemption Shield enabled) has weight 0, even while its EMA is still decaying. A branch in shutdown also has weight 0. Both are excluded from normal-mode redemption; a shutdown branch instead uses direct shutdown redemption, while a live branch with zero base debt simply contributes no normal-mode redemption capacity.

Per-branch walk​

Inside each branch, Redemptions.redeemCollateral walks the base SortedTroves list in ascending ICR order:

One branch’s slice arrivesRedemptions.redeemCollateral(slice, hints, fee, par)Walk to the first redeemable trove_firstRedemptionHint gives the starting guessbelow-MCR troves and mini-dwarfs are skippedRD left to redeem, under the iteration cap?no — walk endsyesSlice ≥ the trove’s entire net debt?yes — fullno — partialFull redemption — the trove closesdebt repaid at par · collateral drawn200 RD gas reserve burned against the last debtsurplus collateral → CollSurplusPoolPartial redemption — the walk endsthe trove keeps > 200 RD of debtreinserted at the hint; NICR mismatch cancels ita partial always ends the branch walknext troveCollateral (minus fee) → the redeemerredeemed RD is burned · the fee stays in the trovethe branch reports its redeemed total to the Aggregator
Inside one branch, the slice walks the base book from the lowest ICR up. A full redemption closes the trove and the walk continues; the first partial redemption ends it. A partial only has to leave the trove's debt above the 200 RD gas reserve, so it can take a trove below the 1,800 RD borrowing minimum. Try it live in the interactive walk below.
0 RDRedeemed Amount
0 RD
4,000108%skip: below MCR5,000112%untouched9,000118%untouched≈0121%skip: gas-only4,000126%untouched12,000140%untouched6,000160%untouched← lowest ICRredemption walks low → high ICRhigher ICR →
Requested 0 RD → redeemed 0 (0 closed).
One branch's base book, ordered by ICR. Redemption consumes debt from the lowest-ICR trove upward. Full redemptions close the trove (the 200 RD gas reserve is burned against the trove's last 200 RD of debt, surplus collateral goes to the CollSurplusPool) and the walk continues; the first partial redemption ends the walk. A partial only has to leave the trove's debt above the 200 RD gas reserve, so it can take a trove below the 1,800 RD minimum net debt that applies to borrowing. Below-MCR and gas-only troves are skipped. Values are illustrative.

Skipped troves​

  • Below MCR. Already in liquidation territory; normal-mode redemption skips them.
  • Mini-dwarfs. Troves whose debt is at or below the 200 RD gas reserve have nothing redeemable and are skipped.
  • Oracle failure. If the branch's price read reports an oracle failure, normal redemption does not price around it: the call reverts, and the branch has to go through shutdown, where the shutdown pricing schedule applies. See Shutdown redemption.

Partial redemptions​

A full redemption repays the trove's debt down to the 200 RD gas reserve, burns that reserve against the remaining debt, closes the trove, and sends any leftover collateral to the CollSurplusPool. The walk then continues to the next trove. The first partial redemption ends the branch's walk. A partial only has to leave the trove's debt above the 200 RD gas reserve, so redemption can take a trove below the 1,800 RD minimum net debt that applies when borrowing.

Troves with Redemption Shield enabled​

In normal mode, the Redemption Shield cohort SortedTroves is never walked, regardless of the base list's state. An empty base list does not redirect redemption into the Redemption Shield cohort book; it simply means the branch contributes nothing to a normal-mode redemption (its basket weight is 0). Only branch shutdown ever routes redemption through troves with Redemption Shield enabled.

In shutdown mode, the protocol can walk both books at the shutdown pricing multiplier.

Putting it together: multi-branch redemption​

The basket split and the per-branch walk, together. A requested redemption is divided across active branches in proportion to their base debt EMA, and each slice then walks that branch's own book from the lowest ICR up. Drag the requested amount, or raise a branch's EMA to pull more of the redemption onto it, and watch a thin branch run out of redeemable troves.

A branch may fill less than its slice only when it has run out of normal-mode redeemable debt. Every other branch must fill at least 90% as completely as the best-filled branch (REDEMPTION_COMPLETION_PERCENT), otherwise the call reverts with Aggregator_RedemptionBasketMismatch.

Note: this demo shows only 3 branches, not the full 7 the production protocol has.

18,000 RD
splits across branches by debt-EMA weight → total redeemed 18,000 RD
WETHdebt EMA 24,000 → weight 47% · allocated 8,471 → redeemed 8,471
4,000108%skip: below MCR5,000113%closed9,000124%partial6,000140%untouched← lowest ICRhigher ICR →
WBTCdebt EMA 15,000 → weight 29% · allocated 5,294 → redeemed 5,294
3,000133%closed7,000141%partial5,000155%untouched← lowest ICRhigher ICR →
rETHdebt EMA 12,000 → weight 24% · allocated 4,235 → redeemed 4,235
4,000123%closed8,000132%partial← lowest ICRhigher ICR →
A redemption is global. Each slider independently sets a branch's raw debt EMA (72-hour half-life, in RD) — move one and the others stay put. The redemption weight a branch gets is its EMA over the current total (so the weights sum to 100%), and that split determines how much RD hits each branch. Raising one branch's EMA pulls more of the redemption onto it. Each slice then walks that branch's base book from the lowest ICR up — full redemptions close a trove and continue, the first partial ends that branch's walk. A partial only has to leave the trove's debt above the 200 RD gas reserve. A branch that runs out of redeemable troves leaves part of its slice unredeemed (the redeemer keeps that RD); every other branch must fill at least 90% as completely as the best-filled one, or the whole call reverts. Troves with Redemption Shield enabled are never on these lists. Because the EMA is a 72-hour-half-life average, a branch's debt EMA can differ from the current sum of the troves without Redemption Shield shown here. Values are illustrative.

Fee accounting​

Redemption feecollateral leg · 0.75%normalif a bad-debt sink branch existsKept by the redeemed trovestays as residual collateralpost-redemption ICR risesRepairs the bad-debt branchconverted to RD → payDebt(...)autonomous solvency repair
The redemption fee is taken in collateral, not RD. Normally it is retained by the redeemed trove as residual collateral, which nudges that borrower's ICR up. The only exception: while a shut-down branch is carrying bad debt (the Aggregator's sink branch), the fee is taken in RD instead and used to repay that debt. It never reaches MOAI stakers. (The separate 0.25% redemption protocol fee is paid in RD and goes to the GlobalFeeRouter.)
Gross collateral drawnredeemed RD ÷ oracle price × par100%−Redemption feegross × fee — stays in the trove0.75%=Collateral to the redeemergross − fee99.25%
Every redeemed RD retires debt at par; the collateral drawn against it is priced by the branch oracle. The fee is charged on the collateral leg and never leaves the trove. Shown with the 0.75% fee every branch is deployed with (each branch's fee is fixed at deployment, within the contract bounds of 0.5–2.5%).

Each branch has its own redemption fee, fixed at deployment within the contract bounds MIN_REDEMPTION_FEE = 0.5% and MAX_REDEMPTION_FEE = 2.5%. Every branch is deployed at 0.75%. The fee is rounded up, so even a tiny lot pays a non-zero fee.

RedemptionLot.collateralFee is retained by the redeemed trove. The trove's debt decreases by the full redeemed_rd (paid down at par), but its collateral decreases by only collateral_to_redeemer; the fee portion stays inside the trove as residual collateral, increasing its post-redemption ICR. The fee does not flow to the FeeRouter and does not reach MOAI stakers.

Every redeemed RD is credited against borrower debt at par. On top of that, the redeemer pays a redemption protocol fee of 0.25% (REDEMPTION_PROTOCOL_FEE_BPS = 25, rounded up) of the RD actually redeemed. It is burned from the redeemer together with the redeemed RD, and the same amount is routed through GlobalFeeRouter (see Fees). Shutdown redemptions do not charge it.

The one exception is when a bad-debt sink branch is active. In that case the fee on healthy-branch redemptions is converted into RD and routed to the sink branch's payDebt(...) rather than retained by the healthy redeemed trove, see "Fee accounting with bad debt" below.

Fee accounting with bad debt​

A branch becomes a bad-debt sink when it is shut down, all of its collateral has left (through shutdown redemptions or other exits), and debt is still outstanding after the branch's gas-pool RD has been burned against it. Redemptions then flags the branch underCollateralized, the Aggregator designates it as the currentUnderCollateralizedTM, and normal redemption is routed differently:

  • Healthy-branch allocations are reduced by (1 − redemption_fee) × (1 − BAD_DEBT_REDEEM_FRAC) where BAD_DEBT_REDEEM_FRAC = 0.5%.
  • The fee that would have been paid in collateral by the healthy branches is converted into RD and routed to the sink branch's payDebt(...) to chip away at its bad debt.
  • The bad-debt-haircut slice (total_redeemed × BAD_DEBT_REDEEM_FRAC / (1 − BAD_DEBT_REDEEM_FRAC)) is also routed to the sink branch.
  • payDebt(...) stops at the sink branch's remaining debt; the redeemer is only charged for what was actually paid. The 0.25% protocol fee is still charged on the redeemed amount.
Normal redemption — 1,000 RD992.5 in collateral992.5 → the redeemer, in collateral (gross − 0.75% fee)7.5 fee → stays in the redeemed trove as extra collateralBad-debt sink branch active — 1,000 RD≈987.5 in collateral≈987.5 → the redeemer, in collateral (the collateral fee is waived)≈7.5 fee + ≈5 haircut → the sink branch as RD, via payDebt(…)every healthy-branch slice is trimmed ↓
The same 1,000 RD redemption, with and without a bad-debt sink branch. Normally the fee is collateral that stays in the redeemed trove. While a shut-down branch carries bad debt, the fee is collected in RD instead and routed to that branch's payDebt(…), along with an extra 0.5% haircut — the redeemer gives up ~0.5% of output and every redemption repays part of that debt. In both cases the redeemer also pays the 0.25% redemption protocol fee in RD on top. Fee shown at the deployed 0.75%.

In other words: while a sink branch exists, every redemption on healthy branches surrenders a small slice of value to repay the sink branch's debt. Redeemers still get collateral; the sink branch gets RD-denominated relief. This repays residual debt over time without an admin top-up, although the repayment speed depends on redemption and fee volume.

When no sink branch exists, the redemption fee is retained by the redeemed trove (see "Fee accounting" above).

Redemption quota​

The Aggregator maintains a token-bucket-style quota. The bucket refills over time up to the current cap (a function of system debt), and each redemption drains it, so heavy redemption activity throttles itself.

Read live capacity from Aggregator.redemptionQuotaAvailable():

function redemptionQuotaAvailable() external view returns (
uint256 available,
uint256 redemptionCapacityNow
);

A request (_RDamount) larger than the available quota reverts (Aggregator_RedemptionAmountExceedsQuota). The request can then be filled partly (a branch runs out of redeemable troves, the iteration cap is reached, or a partial is cancelled by a stale hint); only the RD actually redeemed is taken from the quota.

The bucket in motion — refill at REDEMPTION_PCT_PER_DAY = 4% per day of the lower of current global debt and the global debt EMA, pooled up to a 6-hour burst reserve (1% of system debt redeemable instantly). The bucket starts empty when the bootstrap period ends. Throw a redemption demand shock at it and drag across the timeline:

Hints​

Each branch takes a starting hint plus three hints to reinsert the partially-redeemed final trove cheaply:

HintWhat it tells the branch
_firstRedemptionHint[i]The first redeemable trove in the base list. It is used only if it is in the list, at or above MCR, can absorb redemption, and no lower-ICR trove above MCR could be redeemed first; otherwise the walk starts from the lowest-ICR end of the list.
_upperPartialRedemptionHint[i]The trove immediately above the post-walk insertion point.
_lowerPartialRedemptionHint[i]The trove immediately below the post-walk insertion point.
_partialRedemptionHintNICR[i]Expected NICR of the final partially-redeemed trove. If it doesn't match, the partial is cancelled and the branch stops there.

The GlobalHintHelper contract computes hints from on-chain state. Front ends and aggregator integrations almost always call it.

If the first hint is stale, the walk starts from the lowest-ICR end of the list and skips below-MCR troves and mini-dwarfs, costing more gas. If the partial NICR hint is stale (someone else's tx landed first), that branch's partial is cancelled: the branch redeems only its full closes, and the call reverts if that leaves nothing redeemed or the branches filled too unevenly.

Reinsert modes​

The post-walk reinsertion has three modes (mode = 0 / 1 / 2):

  • 0 = regular, normal-mode walk, insert in base sorted list at hinted position.
  • 1 = shutdown_end_reinsert, used by Redemptions.redeemCollateralForShutdown; the protocol derives reinsertion hints from the ends of the relevant book.
  • 2 = shutdown_local_reinsert, used by Redemptions.redeemCollateralForShutdownWithMode(..., true); hints come from the trove's prior neighbours.

These are details for redemption batching efficiency in shutdown. The normal-mode user only needs mode 0.

Gas​

Rough redemption gas budget:

  • Aggregator overhead: a few tens of thousands of gas (basket weights, quota refill).
  • Per branch walked: ~50k–80k gas for setup, plus ~30k per trove touched in the walk.
  • Final partial-reinsert: ~80k gas.

_maxIterations is a per-branch cap on troves selected for redemption (skipped below-MCR troves and mini-dwarfs don't count). Setting it too low leaves RD unredeemed in that branch. Because that branch is not exhausted, the call reverts with Aggregator_RedemptionBasketMismatch if its fill falls below 90% of the best-filled branch's.

Deep dive​