Skip to main content

Developer Reference

The concept sections (Introduction, Borrowing, Holding & Redeeming RD, Earning) explain what the protocol does and why. This section is the call surface: the entry points, parameters, hints, and revert reasons for the common on-chain paths, kept concise for integrators and tooling. It is not an exhaustive contract dump — for the deep mechanics of any subsystem, follow the "Mechanics" links into the Advanced section.

Everything here is per-branch unless noted. There are no admin keys, no upgradeable proxies, and no privileged callers on any of these functions.

Pages​

  • Borrowing operations — open, adjust, repay, close, claim surplus, toggle shield, open at MCR.
  • Redemption — the multi-branch redeemCollateral call and its per-branch hints; the shutdown path.
  • Earning — Stability Pool deposits, and MOAI / FLX / LP staking.
  • Liquidation & cleanup — liquidate, plus the mini-dwarf sweep path.
  • Integration guide — hints, redemption arrays, and practical advice for building an interface.
  • Reading state — the view functions and hint helpers to read before you send.

Conventions used everywhere​

Sorted-list hints. Borrow ops and redemption take upperHint / lowerHint (or arrays of them) that tell the branch's SortedTroves where to (re)insert a trove. Hints are advisory — wrong hints cost extra gas as the list re-walks, they never change correctness. Compute them off-chain with GlobalHintHelper:

// Approx insert hint for one branch's base list, refine with SortedTroves.findInsertPosition:
GlobalHintHelper.getApproxHint(troveManager, NICR, numTrials, randomSeed)
// Multi-branch redemption hints (no branch index, no price arg):
GlobalHintHelper.getRedemptionHints(RDamount, maxIterations)

The relevant NICR is always the trove's post-operation value — don't reuse pre-op hints. See Reading state.

Par. Collateral ratios, redemption, and liquidation value RD at the protocol's internal par (normally $1.00), read from RateParControl.par().

Gas-compensation reserve. Every trove carries a fixed 200 RD of debt whose RD sits in the branch GasPool for the trove's whole life. On closeTrove it is burned against the trove's last 200 RD of debt (it is not paid back to the borrower; the borrower repays only the net debt); on liquidation it is paid to the liquidator. A "Borrow 1,800 RD" open mints 1,800 RD to the user and 200 RD to the pool, for 2,000 RD of debt; surface that in UI.

Approvals. Collateral is pulled by the branch's ActivePool (or its ActiveShieldedPool for a trove with Redemption Shield enabled), not by BorrowerOperations: approve the pool that will hold the trove before opening or adding collateral.

Custom errors. Several contracts revert with custom errors rather than strings (for example Aggregator's AggBootstrap(), AggIssuanceQuota(), Aggregator_RedemptionAmountExceedsQuota(), and MOAIStaking's LockupNotExpired(...)). Decode them from the contract ABI.

Contract map​

ContractScopeRole
BorrowerOperationsper branchopen / adjust / close / shield toggle / claim surplus, shutdown()
MinTroveper branchopenTroveAtMCR: open a base trove at exactly the MCR (1,800–10,000 RD net debt)
AggregatorsingletonredeemCollateral, issuance/redemption quotas, cross-branch coordination
StabilityPoolper branchprovideToSP / withdrawFromSP / withdrawCollateralGainToTrove
Liquidationsper branchliquidate / liquidateTroves / batchLiquidate and the scan fallbacks
Redemptionsper branchshutdown redemption (redeemCollateralForShutdown); normal redemption is called only by the Aggregator
TroveManagerper branchtrove state, mini-dwarf sweeps, ICR reads
LPStakingone per RD market pool (RD/USDC, RD/USDT)LP-share staking
MOAIStaking / FLXStakingsingletonstaking entry points
GlobalHintHelpersingletonoff-chain hint construction and redemption quotes
SystemView / RateView / RedemptionRankView / MultiTroveGettersingletonread-only views for front ends (see Reading state)
RateParControl / MarketOracleAggregatorsingletonpar and rate / RD market price
PriceFeedper branchcollateral price

DSProxy scripts​

For wallets that act through a DSProxy, each branch also has two delegatecall-only scripts that wrap the calls above, plus MOAIStakingScript and one LPStakingWrappersScript per market pool for staking. Call them through the proxy's execute(script, calldata); called directly they revert.

  • BorrowerWrappersScript — the BorrowerOperations calls (openTrove, adjustTrove, addColl, withdrawColl, withdrawRD, repayRD, closeTrove, claimCollateral), plus combined flows: claimCollateralAndOpenTrove, openTroveAndProvideToSP, adjustTroveAndProvideToSP, closeTroveFromWallet (pulls the RD from the proxy owner's wallet), and claimSPRewardsAndRecycle / claimStakingGainsAndRecycle (with ...WithTier variants) that move gains back into the trove, the Stability Pool and MOAI staking.
  • StabilityPoolScript — provideToSP, withdrawFromSP, withdrawCollateralGainToTrove.
  • LPStakingWrappersScript — claimLPRewardsAndStake / claimLPRewardsAndStakeWithTier: claim LP rewards and stake the MOAI.