Skip to main content

Reading state

The view functions and helpers to read before you build a transaction. Nothing here changes state.

Quotas and capacity​

Aggregator.redemptionQuotaAvailable()
returns (uint256 available, uint256 redemptionCapacityNow)
Aggregator.issuanceQuotaAvailable(address troveManager)
returns (uint256 available, uint256 issuanceCapacityNow)
BorrowerOperations.maxBorrowAmount() // per branch: RD a borrower can draw right now
MinTrove.maxMcrTroveAmount() // per branch: largest openTroveAtMCR amount right now

A redemption above available reverts with Aggregator_RedemptionAmountExceedsQuota() (no partial fill). Both quota views return (0, 0) during the 14-day bootstrap (redemption is disabled then; borrowing is limited by each branch's bootstrap ceiling instead), and issuanceQuotaAvailable also returns (0, 0) for a shut-down branch. For borrowing, read maxBorrowAmount(), which already takes the lower of the issuance quota and the utilization cap and subtracts the 10,450 RD BORROW_ALLOWANCE_BUFFER; an open or debt increase above it reverts "BO: alw". Check these before sending.

Hints​

Compute sorted-list hints off-chain with the singleton GlobalHintHelper:

// Multi-branch redemption hints (no branch index, no price arg):
GlobalHintHelper.getRedemptionHints(uint _RDamount, uint _maxIterations)
returns (address[] firstRedemptionHints, uint[] partialRedemptionHintNICRs, uint[] truncatedRDamounts)

// Full redemption simulation: per-branch output, fees, quota and completion check:
GlobalHintHelper.getRedemptionQuote(uint _RDamount, uint _maxIterations)
returns (RedemptionQuote quote)

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

// Approximate insert hint in one branch's base list:
GlobalHintHelper.getApproxHint(address troveManager, uint _NICR, uint _numTrials, uint _inputRandomSeed)
returns (address hintAddress, uint diff, uint latestRandomSeed)
// Same, for several branches in one call (NICR 0 = skip that branch):
GlobalHintHelper.getApproxHintsForBranches(address[] troveManagers, uint[] NICRs, uint _numTrials, uint _inputRandomSeed)
returns (address[] hintAddresses, uint latestRandomSeed)

Standard pattern: read branch state → getApproxHint with numTrials ≈ 15 × sqrt(numTroves) → refine with SortedTroves.findInsertPosition(NICR, hint, hint) for the exact upper/lower. Always use the trove's post-operation NICR. getApproxHint samples only the base list; for a trove with Redemption Shield enabled, start from a trove in that branch's Redemption Shield SortedTroves list.

Prices and ratios​

  • RateParControl.par() — the internal redemption price (normally 1e18). rate() and mode() give the controller's rate and mode; see Peg control.
  • MarketOracleAggregator.getResultWithValidity() returns (uint256 value, bool valid, bool accepted) — the RD/USD market price the controller reads, whether a qualified price exists, and whether it is accepted for control.
  • PriceFeed.viewLatestPrice(bool isRedemption) — the branch collateral USD price, without changing state (fetchPrice is the state-changing version used by the protocol). previewWillShutdown(bool) tells you whether the next fetch would find the oracle failing.
  • TroveManager.getCurrentICR(address, price) / getCurrentICRPar(address, price, par) — a trove's live ICR, including pending redistribution. getTCR(price) and checkRecoveryMode(price) for the branch.
  • TroveManager.getEntireDebtAndColl(address) / getTroveActualDebt(address) — a trove's debt and collateral; shielded(address) — its Redemption Shield setting.
  • Aggregator.redemptionBasketWeights() returns (uint256[] weights, uint256 sumWeight) — the redemption basket weight for each branch, in TroveManager registry order. Aggregator.redemptionRate(troveManager) is that branch's redemption fee.
  • BorrowerOperations.getEarlyRepayFee(address borrower, uint256 principal) — the early-repayment fee a repayment would pay now.

Periphery views​

Singleton read-only contracts for front ends and integrators. Each exposes getBranches() for the branch order it uses.

ContractCallReturns
SystemViewsystemStats()(GlobalStats global, BranchStats[] branches): RD supply, global debt and TCR, par, rate, controller mode, market price, debt EMA, redemption quota; and per branch status, price, TCR, MCR/CCR/SCR, debt by cohort, Redemption Shield share, rates, Stability Pool deposits, maxBorrow and redemption fee
RateViewgetCurrentBranchRates(tm)the base and Redemption Shield rates in effect for a branch
RateViewgetBranchCurve(tm, numPoints) / getBranchPricedCurve(tm, numPoints)base and Redemption Shield APY across Redemption Shield shares from 0% to 100% (2–101 points)
RedemptionRankViewgetTroveRank(tm, borrower)a base trove's position in its branch's redemption queue: rank, debt ahead, and whether normal redemption can currently run
RedemptionRankViewgetRankForICR(tm, icr)the same for a hypothetical ICR, for example a trove with Redemption Shield enabled previewing turning it off
MultiTroveGettergetMultipleSortedTroves(tm, startIdx, count, shielded) / getAllMultipleSortedTroves(startIdx, count, shielded)a page of troves from one list (one branch, or every branch); a negative startIdx counts from the low-ICR end

Front-ends should surface the realized RD-in vs collateral-out for redemptions (the collateral fee depends on which branch is hit, and the 0.25% protocol fee is charged in RD on top), not a headline fee percentage. getRedemptionQuote gives these figures. See the Integration guide.