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
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
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:
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.
Fee accounting
GlobalFeeRouter.)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)whereBAD_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.
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:
| Hint | What 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 byRedemptions.redeemCollateralForShutdown; the protocol derives reinsertion hints from the ends of the relevant book.2 = shutdown_local_reinsert, used byRedemptions.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
- Redemption (user view): same content, less detail.
- Shutdown redemption and Collateral shutdown: the off-the-normal-path version.