Skip to main content

Integration guide

If you're building an interface, bot or contract integration for RAI Dollar, this page collects the integration surface for borrowing, redemption, and Stability Pool deposits.

Integration: hints​

Both openTrove / adjustTrove (and the wrappers that move collateral or debt) and Aggregator.redeemCollateral take sorted-list hints. Integrations typically pre-compute hints client-side using GlobalHintHelper:

// Redemption hints (multi-branch; no branch index, no price arg):
GlobalHintHelper.getRedemptionHints(RDAmount, maxIterations)
returns (address[] firstRedemptionHints, uint[] partialRedemptionHintNICRs, uint[] truncatedRDamounts)

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

// Approximate insert hint for a given branch's base list:
GlobalHintHelper.getApproxHint(troveManagerAddress, NICR, numTrials, inputRandomSeed)
returns (hintAddress, diff, latestRandomSeed)

The standard pattern:

  1. Read current branch state (price, accumulated rates, par).
  2. Call getApproxHint with reasonable numTrials (the contract suggests about 15 × sqrt(numTroves)). It samples the base list only; for a trove with Redemption Shield enabled, sample that branch's Redemption Shield SortedTroves list yourself or pass a nearby trove from it.
  3. From the approx hint, refine with SortedTroves.findInsertPosition(NICR, hint, hint) to get the exact upper/lower.
  4. Pass those into the operation.

If your hints are stale by the time the tx lands, the operation still succeeds, it just costs more gas as the sorted list re-walks from the bad hint.

Integration: redemption​

Aggregator.redeemCollateral takes arrays of hints, one entry per branch:

function redeemCollateral(
uint256 _RDamount,
address[] calldata _firstRedemptionHint, // length = N branches
address[] calldata _upperPartialRedemptionHint, // length = N branches
address[] calldata _lowerPartialRedemptionHint, // length = N branches
uint256[] calldata _partialRedemptionHintNICR, // length = N branches
uint256 _maxIterations
) external

Every array has one entry per registered branch (Aggregator.troveManagerLength()), shut-down branches included. For each branch i, the hints describe redeeming _RDamount × weights[i] / sumWeight into that branch, with (weights, sumWeight) = Aggregator.redemptionBasketWeights(); getRedemptionHints does this split for you. Pass address(0) and 0 for zero-weight branches (shut down, or no base debt); the Aggregator skips them.

The redemption tx reverts entirely if any branch reverts, or if any branch that still has redeemable debt fills less than 90% as completely as the best-filled one. The caller needs _RDamount plus the 0.25% protocol fee in RD. Simulate first with GlobalHintHelper.getRedemptionQuote(_RDamount, _maxIterations), which reports per-branch output, requiredRDBalance, exceedsQuota and basketBalanced. See Redemption.

Integration: borrowing​

// Open
BorrowerOperations.openTrove(coll, RDAmount, upperHint, lowerHint, redemptionShield)

// Adjust (combined op)
BorrowerOperations.adjustTrove(
collToAdd, collWithdraw,
debtChange, isDebtIncrease,
toggleShield, upperHint, lowerHint
)

// Wrappers
BorrowerOperations.addColl(amount, upperHint, lowerHint)
BorrowerOperations.withdrawColl(amount, upperHint, lowerHint)
BorrowerOperations.withdrawRD(amount, upperHint, lowerHint)
BorrowerOperations.repayRD(amount, upperHint, lowerHint)
BorrowerOperations.closeTrove()

For all hints, the relevant NICR for the user's post-operation trove is what matters. Compute it client-side; don't reuse pre-op hints. Collateral approvals go to the branch ActivePool (or ActiveShieldedPool for a trove with Redemption Shield enabled). Show the borrower the live capacity from BorrowerOperations.maxBorrowAmount() and, for repayments within 6 hours of a debt increase, the 2% early-repayment fee from getEarlyRepayFee(borrower, amount). See Borrowing operations.

Integration: Stability Pool​

StabilityPool.provideToSP(uint256 _amount, address(0))
StabilityPool.withdrawFromSP(uint256 _amount)
StabilityPool.withdrawCollateralGainToTrove(address _upperHint, address _lowerHint)

The second argument is a front-end tag. The contracts support front ends that register and take a share of their depositors' MOAI rewards (a kickback rate), but the team promotes a single canonical front end that takes nothing, so this system is unused: pass address(0). The tag is only recorded when a deposit is first created; top-ups keep the existing tag whatever you pass. So address(0) gives the depositor all of their MOAI only for a new deposit, or one that was already untagged. A deposit that already carries a tag stays subject to that front end's kickback rate until it is fully withdrawn and redeposited with address(0). Read the current tag from deposits(depositor).frontEndTag before telling a user they keep all of their rewards. Surface the 1-day withdrawal lockup after each deposit and the per-branch deposit cap (getDepositHeadroom()).

Practical advice​

  • Surface the live numbers. Par, market price, branch TCR, your trove's ICR, your effective APR, redemption quota. SystemView.systemStats() returns most of them in one call; the underlying reads are on Aggregator, RateParControl, MarketOracleAggregator, and each branch's TroveManager / PriceFeed / InterestEngine. See Reading state.
  • Compute hints client-side and verify before sending. Cheaper for users.
  • Don't show "the redemption fee is X%"; show the realized output. The collateral fee depends on the branch the redemption hits and is paid on top of the 0.25% RD protocol fee; users care about RD-in vs collateral-out.
  • Surface bootstrap and shutdown state clearly. During bootstrap, redemption is disabled and each branch's borrowing is capped by its bootstrap ceiling. During branch shutdown, the discount schedule applies. Both are easy to mis-render.
  • Handle the gas-comp reserve in the open-trove UI. Users see "Borrow 1800 RD" and expect to receive 1800 RD; the 200 RD reserve is held by the protocol, not transferred to them, and their debt is 2,000 RD. On close they repay only the net debt, because the reserve is burned against the last 200 RD.

Deep dive​