Skip to main content

Borrowing operations

The callable surface for troves. Concept: Open a trove and Adjust, repay, close. Mechanics: Interest model, Rates vs. utilization.

All functions below are on the branch's BorrowerOperations unless noted. Collateral is pulled by the pool that holds the trove: approve the branch's ActivePool (or ActiveShieldedPool for a trove with Redemption Shield enabled) before any call that adds collateral.

Open​

BorrowerOperations.openTrove(
uint256 _collateralAmount, // collateral deposited (token units)
uint256 _RDAmount, // net debt minted (1,800 RD floor)
address _upperHint,
address _lowerHint,
bool _redemptionShield // true = enable Redemption Shield at open
)

Opens a trove at ≥ 2,000 RD total debt (_RDAmount net + 200 RD gas reserve). Mints _RDAmount to the caller and 200 RD to the GasPool. ICR is computed with par: coll × price / (debt × par).

Read the branch's live borrowing capacity first with BorrowerOperations.maxBorrowAmount(). It is the Aggregator's allowance for the branch (the bootstrap-ceiling headroom during the 14-day bootstrap; afterwards the lower of the issuance quota and the utilization cap) minus BORROW_ALLOWANCE_BUFFER() = 10,450 RD, which is held back so MinTrove opens (below) keep room.

Reverts:

  • "Resulting ICR < MCR" — ICR below the branch minimum.
  • "Net debt below min" — _RDAmount below 1,800 RD.
  • Normal mode: "BO: tcr<ccr" — the open would push branch TCR below CCR.
  • Recovery mode (branch TCR already < CCR): "Resulting ICR < CCR" — a fresh open must reach ICR ≥ CCR.
  • "BO: alw" / "BO: rsv" — _RDAmount exceeds maxBorrowAmount(), or the branch allowance is no larger than the buffer; retry after the quota refills (mechanics in Rates vs. utilization).
  • "Coll cap exceeded" — the branch collateral cap would be exceeded.
  • "BO: shut" — the branch is shut down or can be shut down; "BO: oracle" — the price feed is failing; "BO: coll backing" — a branch collateral pool is underbacked.
  • "Trove active" — the caller already has an active trove on this branch.
  • "Shield toggle too soon" — _redemptionShield differs from the caller's last setting on this branch and 24 hours have not passed (see below).

Adjust​

BorrowerOperations.adjustTrove(
uint256 _collateralToAdd,
uint256 _collWithdrawal,
uint256 _RDChange,
bool _isDebtIncrease,
bool _toggleShield, // toggles Redemption Shield in the same tx
address _upperHint,
address _lowerHint
)

One direction per call for collateral (add or withdraw, else "BO: cw+ca") and for debt (increase or repay). Conditions:

  • Normal mode (branch TCR ≥ CCR): the new ICR must be ≥ MCR and the new TCR ≥ CCR ("Resulting TCR < CCR").
  • Recovery mode (TCR < CCR): collateral top-ups and repayments are always allowed; a collateral withdrawal must keep ICR ≥ MCR and must not lower it; a debt increase must reach ICR ≥ CCR and must not lower it ("Cannot reduce ICR in RM").
  • A partial repayment must leave net debt ≥ 1,800 RD ("Net debt below min") and cannot exceed actual debt − 200 RD ("BO: rp>debt").
  • A debt increase or collateral withdrawal must leave actual debt ≥ 2,000 RD. A trove below that (after a partial redemption or negative base interest) can still add collateral, toggle Redemption Shield, close, or borrow enough to bring actual debt back to at least 2,000 RD, but cannot withdraw collateral or partially repay.
  • A debt increase is limited by maxBorrowAmount(), like an open.

Early-repayment fee. Repaying (or closing) within EARLY_REPAY_WINDOW = 6 hours of the trove's last debt increase costs an extra EARLY_REPAY_FEE_BPS = 2% of the principal repaid, rounded up. The caller must hold principal + fee. Quote it with BorrowerOperations.getEarlyRepayFee(borrower, principal).

Convenience wrappers​

Thin calls into the same accounting — pick whichever matches intent.

OpEntry pointWhat it does
Top up collateraladdColl(amount, upper, lower)Pulls more collateral into your trove
Withdraw collateralwithdrawColl(amount, upper, lower)Sends collateral back (same ICR/TCR checks as adjustTrove)
Borrow more RDwithdrawRD(amount, upper, lower)Mints more RD, increases debt
Repay RDrepayRD(amount, upper, lower)Burns RD (plus any early-repayment fee) from your wallet, decreases debt
Enable Redemption ShieldshieldTrove(upper, lower)Migrates the trove to the Redemption Shield cohort; reverts "BO: shielded" if already enabled
Disable Redemption ShieldunShieldTrove(upper, lower)Migrates the trove back to the base; reverts "BO: unshielded" if already disabled
Close trovecloseTrove()Burns your net debt (plus any early-repayment fee) from your wallet, burns the 200 RD reserve in the GasPool against the last 200 RD of debt, returns all collateral
Claim surplusclaimCollateral()Pulls any collateral surplus owed to you from CollSurplusPool (after a full redemption, a capped liquidation, a mini-dwarf sweep, or the shutdown sweep)

closeTrove() requires the caller to hold the trove's actual debt (including accrued interest) minus 200 RD, plus any early-repayment fee ("Insufficient RD balance"). The 200 RD reserve is not paid back to the borrower; it pays off the last 200 RD of debt.

Shield toggle cooldown​

The Redemption Shield setting changes through shieldTrove / unShieldTrove (or adjustTrove(..., _toggleShield: true, ...)). Read the current setting with TroveManager.shielded(borrower). BorrowerOperations enforces SHIELD_TOGGLE_WAIT = 86400 seconds (24 hours): after any setting change — including the choice made at open — another change reverts with "Shield toggle too soon" until 24 hours elapse. The clock is per borrower (shieldToggleData(borrower) packs the last setting and its timestamp) and resets on each change. Closing and reopening with the same setting does not wait.

Open at MCR (MinTrove)​

Each branch also has a MinTrove contract for permissionless peg arbitrage:

MinTrove.openTroveAtMCR(
uint256 _RDAmount, // net debt, 1,800 to 10,000 RD
uint256 _maxCollateralAmount, // cap on collateral pulled
address _upperHint,
address _lowerHint
)
MinTrove.maxMcrTroveAmount() // view: largest _RDAmount allowed right now (0 if none)

It opens a trove without Redemption Shield at exactly ICR = MCR at the current oracle price, pulling the minimum collateral needed (approve the branch ActivePool). Before opening it tries to liquidate up to 10 troves below MCR, with the gas compensation going to the caller. Opens are limited to 10 calls and 18,000 RD of net debt per block timestamp across all callers. The resulting trove is an ordinary trove, managed through BorrowerOperations.

Shutdown​

  • BorrowerOperations.shutdown() — callable by anyone; shuts the branch down when its TCR is below SCR or its price feed would fail on the next fetch, otherwise reverts "TCR >= SCR". canShutdown() previews it.
  • shutdownFromOracleFailure() is callable only by the branch price feed, and shutdownFromCollateralFailure() only by the Aggregator.

After shutdown only pure repayment, closeTrove and claimCollateral work (the early-repayment fee still applies). See Redemption and Collateral shutdown.

Moving Stability Pool gains into a trove​

BorrowerOperations.moveCollateralGainToTrove(...) is callable only by the Stability Pool. Depositors call StabilityPool.withdrawCollateralGainToTrove(_upperHint, _lowerHint) instead. See Earning.

Events​

EventEmitted on
TroveCreated(address indexed _borrower, bool shielded)open (also by MinTrove)
TroveUpdated(address indexed _borrower, uint _debt, uint _coll, uint stake, BorrowerOperation operation)open, adjust, close; operation is openTrove, closeTrove, adjustTrove or openTroveAtMCR
TroveShieldStatusChanged(address indexed _borrower, bool shielded)Redemption Shield toggle
EarlyRepaymentFeeCharged(address indexed _borrower, uint256 _principalRepaid, uint256 _fee)repay or close inside the 6-hour window
BorrowerOperationsShutdown(uint256 _shutdownTime, bool _oracleFailure)branch shutdown