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:

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 gas cap
)

The Aggregator splits _RDamount across all active (non-shutdown) branches in proportion to each branch's base debt EMA, then walks each branch's base book from the lowest ICR up. A revert in any branch reverts the whole transaction.

Building the hints​

For each branch i, compute hints as if redeeming _RDamount × weight[i] / sumWeights into that branch, where weight[i] = Aggregator.unshieldedDebtEma(i).ema:

  • _firstRedemptionHint[i] — the first trove the walk should consider on branch i.
  • _upperPartialRedemptionHint[i], _lowerPartialRedemptionHint[i] — where to reinsert the final partially-redeemed trove.
  • _partialRedemptionHintNICR[i] — that trove's expected NICR after the walk.

Pass address(0) / 0 for shutdown or zero-weight branches; the Aggregator skips them. Wrong hints degrade the walk to O(n) on that branch (more gas, same result). Use GlobalHintHelper.getRedemptionHints(RDamount, maxIterations) — see Reading state.

Read live capacity first with Aggregator.redemptionQuotaAvailable(); a redemption exceeding the quota reverts (no partial fill at the Aggregator level). Redemption is disabled during the 14-day bootstrap.

Shutdown path​

When a branch is shut down, redemption on it uses a time-based discount schedule instead of the fee, and can walk both the base and Redemption Shield books. The Aggregator excludes shut-down branches from normal-mode basket weights, so to redeem from one you call that branch's Redemptions contract directly.

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

  • BorrowerOperations.shutdown() — branch TCR below SCR.
  • BorrowerOperations.shutdownFromOracleFailure() — the branch price feed has failed.
  • Aggregator.tryAllShutdown() — sweep every currently-shutdownable branch.

The discount schedule constants live in Redemptions (BASE_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.