Skip to main content

Redemption

The callable surface for exchanging RD for collateral at par. Concept: Redemption and Shutdown redemption. Mechanics: Redemption mechanism.

The call​

One function on the singleton Aggregator, taking arrays of hints — one entry per branch, in TroveManager registry order:

Aggregator.redeemCollateral(
uint256 _RDamount,
address[] _firstRedemptionHint, // length = N branches
address[] _upperPartialRedemptionHint, // length = N branches
address[] _lowerPartialRedemptionHint, // length = N branches
uint256[] _partialRedemptionHintNICR, // length = N branches
uint256 _maxIterations // per-branch cap on troves selected; 0 = no cap
)

Every array must have length Aggregator.troveManagerLength() (shut-down branches included), else Aggregator_InvalidRedemptionHints().

The Aggregator splits _RDamount across the active (non-shutdown) branches in proportion to each branch's base debt EMA, then each branch's Redemptions walks that branch's base list from the lowest ICR up, skipping troves below MCR and mini-dwarfs. A revert in any branch reverts the whole transaction.

Fees. Each branch charges its redemption fee (0.75% on every mainnet branch, Aggregator.redemptionRate(troveManager)) in collateral, which stays with the redeemed trove. On top, the Aggregator burns a 0.25% redemption protocol fee in RD on the amount actually redeemed. The caller must hold _RDamount plus 0.25% of it, else AggBalance(). While a shut-down branch carries bad debt, each branch's slice is reduced to reserve the branch fee and a 0.5% bad-debt surcharge (BAD_DEBT_REDEEM_FRAC), both burned against that branch's debt; see Fees.

Completion rule. A branch may fill less than its slice only if it ran out of normal-mode redeemable debt. Every other branch must fill at least 90% as completely as the best-filled branch, else Aggregator_RedemptionBasketMismatch(). If nothing is redeemed the call reverts AggNoRedeem().

Other reverts: AggBootstrap() during the 14-day bootstrap; AggAmountZero(); Aggregator_RedemptionAmountExceedsQuota() if _RDamount exceeds the available redemption quota (checked against the full requested amount, even if fewer RD would be redeemed); AggNoWeights() if no branch has base debt.

Building the hints​

Use the singleton GlobalHintHelper:

GlobalHintHelper.getRedemptionHints(uint _RDamount, uint _maxIterations)
returns (address[] firstRedemptionHints, uint[] partialRedemptionHintNICRs, uint[] truncatedRDamounts)

// Exact upper/lower reinsert positions for one branch's partial redemption:
GlobalHintHelper.getInsertHintsForRedemption(address troveManager, uint targetNICR, uint numTrials, uint seed)
returns (address upper, address lower, uint seedOut)

getRedemptionHints simulates the same split and walk as execution and returns, per branch, the first trove the walk should consider, the expected NICR of the final partially redeemed trove, and how much RD that branch can absorb under the iteration cap. Feed each non-zero NICR into getInsertHintsForRedemption for that branch's upper/lower hints. Branches with zero weight come back as address(0) / 0, which the Aggregator skips.

GlobalHintHelper.getRedemptionQuote(_RDamount, _maxIterations) returns the same simulation as a quote: per-branch RD redeemed, collateral sent and collateral fee, the projected and maximum protocol fee, requiredRDBalance, the available quota, exceedsQuota, and basketBalanced (whether the 90% completion rule would pass). Check it before sending.

Wrong hints cost gas, not correctness: a stale first hint makes that branch's walk start from the bottom of its list; a stale partial NICR cancels that branch's partial redemption (the branch redeems only full closes), which can then trip the completion rule.

The basket weights themselves are readable with Aggregator.redemptionBasketWeights() (returns uint256[] weights, uint256 sumWeight); shut-down branches and branches with no base debt get zero.

Read live capacity with Aggregator.redemptionQuotaAvailable(). See Reading state.

Shutdown path​

When a branch is shut down, redemption on it uses a time-based price multiplier instead of the fees, walks both the base and Redemption Shield lists together in ascending ICR order, and has no quota, no bootstrap gate and no protocol fee. The Aggregator excludes shut-down branches from the basket, so you call that branch's Redemptions contract directly. It takes no hints:

Redemptions.redeemCollateralForShutdown(uint _RDamount, uint _maxIterations)
Redemptions.redeemCollateralForShutdownWithMode(uint _RDamount, uint _maxIterations, bool _useLocalReinsert)
Redemptions.getPriceMultiplier() // view: the current multiplier (1e18 = no discount)

Shutdown is triggered (by anyone, once the branch qualifies) via:

  • BorrowerOperations.shutdown() — branch TCR below SCR, or the branch price feed would fail on the next fetch.
  • Aggregator.tryAllShutdown() — try every branch, including the collateral-custody checks (underbacked pools, and the zero-amount transfer probe on blacklistable collateral); Aggregator.tryShutdown(troveManager) does the same for one branch.

BorrowerOperations.shutdownFromOracleFailure() is not a public trigger: only the branch price feed can call it, during a price fetch that finds the oracle failing.

The schedule constants live in Redemptions (BASE_DISCOUNT, BREAKPOINT_TIME_SCR, BREAKPOINT_DISCOUNT, MAX_DISCOUNT_TCR_BELOW_SCR, MAX_DISCOUNT_TIME_SCR, MAX_DISCOUNT_ORACLE_FAILURE, MAX_DISCOUNT_TIME_FAILURE); the curves are described in Shutdown redemption and Collateral shutdown.

Events​

EventContractEmitted on
AggregatorRedemption(uint requested, uint redeemed, uint protocolFee, uint quotaRemainingAfter, uint globalDebtSpotAfter)Aggregatoreach basket redemption
Redemption(uint _attemptedRDAmount, uint _actualRDAmount, uint _collateralSent, uint _collateralFee, uint8 _mode, uint _price, uint _par, uint _redemptionRate, uint _priceMultiplier, bool _oracleFailurePricing)branch Redemptionseach branch leg, and each shutdown redemption
TroveRedeemed(address indexed _borrower, uint _rdRedeemed, uint _collateralDrawn, uint _collateralFee, bool _shielded)branch Redemptionseach trove a redemption takes RD from
DebtRepaidFromRedemption(address _tm, uint256 _amount)Aggregatorbad-debt repayment from a redemption