Interest model
This page covers how trove debt accrues over time, how the borrow rate is composed, and how troves with Redemption Shield enabled are priced. The contracts involved are InterestEngine (per branch), Aggregator (per-branch delta-rate offsets), and RateParControl (the system rate).
The per-branch utilization controller runs on the production parameters in the interactive rates-vs-utilization simulator — all seven collaterals, their bands, and the shutdown rescale.
The two accumulators
Each branch's InterestEngine maintains two per-second accumulators with 1e27 precision:
| Accumulator | What it accrues | Who pays it |
|---|---|---|
accumulatedRate | The base rate, branch_rate − v | Troves without Redemption Shield |
accumulatedShieldRate | The Redemption Shield cohort rate, branch_rate + u | Troves with Redemption Shield enabled |
Both start at 1e27. A trove stores its debt as a normalized value: its debt divided by its cohort's accumulator at the moment the debt was recorded (in 1e18 RD units). Actual current debt is:
base:
actualDebt = normalizedDebt × accumulatedRate / 1e27
Redemption Shield cohort:
actualDebt = normalizedDebt × accumulatedShieldRate / 1e27
Toggling Redemption Shield converts the trove's normalized debt from one accumulator to the other, keeping its actual debt. The user-relevant fact is that interest accrues continuously: drip() compounds each accumulator by its per-second rate over the elapsed seconds. One exception: while the branch's Stability Pool holds no RD, drip() does nothing and does not advance its clock, so the elapsed time is compounded at the next drip after deposits return.
The effective per-branch rate
The signed branch utilization adjustment is added to the system rate in the per-second-delta domain, then the branch rate is clamped. Working in per-second-delta units (i.e., subtracting the multiplicative identity RATE_PRECISION = 1e27):
branch_delta = (system_rate − 1) + branch_offset
branch_rate = 1 + clamp(branch_delta, MIN_FINAL_DELTA, MAX_FINAL_DELTA)
In annual-rate shorthand:
branch_APY ≈ clamp(system_APY + branch_offset_APY, 0.1%, 70%)
This is the exact composition in Aggregator._calcCollateralRate:
int256 deltaInterestRate = int256(_interestRate - RATE_PRECISION) + _offset;
return RATE_PRECISION + _clipFinalDelta(deltaInterestRate);
The components:
system_rate: output ofRateParControl. Same number across the protocol. Bounded[0.25% APY, 50% APY], biased at2%. See Peg control.branch_offset: the branch utilization adjustment in the reader-facing docs, exposed byAggregator.deltaRateOffset. It is the signed output of the per-branch PI loop on debt utilization: positive when the branch's share of system debt is above its upper soft band (hot); negative when it is below its lower soft band, subject to the final-rate clamp keepingbranch_APY ≥ 0.1%; zero error inside the band.- Branch-rate clamps:
MIN_FINAL_DELTA ≈ 0.1% APY,MAX_FINAL_DELTA ≈ 70% APY. These bind on the branch rate after the offset is added: the upper clamp (70%) sits above the system rate's 50% ceiling, giving stressed branches extra headroom; the lower clamp (0.1%) sits below the system rate's 0.25% floor, so a strongly-negative branch offset can pull the branch rate under the system floor, but never below 0.1%.
The offset controller works on debt utilization: the branch's 72-hour-half-life debt EMA divided by the global debt EMA (capped at 100%). Each branch has a soft band [lowerSoft, upperSoft] and hard bounds around its target share (production values are on the rates-vs-utilization page). The error is zero inside the soft band; outside it, the error is the overshoot divided by the distance from the soft band to the hard bound, capped at ±100%. The PI gains are in per-second delta units and asymmetric, so over-utilization is corrected harder than under-utilization:
over-utilized (error > 0): Kp = MAX_FINAL_DELTA / 10, Ki = MAX_FINAL_DELTA × 11/40
under-utilized (error < 0): Kp = MAX_FINAL_DELTA / 40, Ki = MAX_FINAL_DELTA × 11/100
integral time constant = 7 days
integral leak = 45-day half-life
The leak means a past imbalance fades unless the error persists. The offset is refreshed on every drip and every debt-changing operation on the branch, and the integral is clamped so the branch rate stays inside [0.1%, 70%].
Realized rate ranges
A few representative slices, computed from the controller's integer math: a constant utilization error held from a neutral start (offset and integral at zero), hourly updates, before the Redemption Shield adjustment. The lag of the 72-hour debt EMA itself is not included.
Branch APY at system_rate = 2% APY:
| Debt-utilization error | immediately | after 1 day | after 1 week | after 4 weeks |
|---|---|---|---|---|
| −100% | 0.66% | 0.10% (floor) | 0.10% | 0.10% |
| −50% | 1.33% | 0.91% | 0.10% | 0.10% |
| −25% | 1.66% | 1.45% | 0.27% | 0.10% |
| −10% | 1.86% | 1.78% | 1.30% | 0.10% |
| 0% (inside the soft band) | 2.00% | 2.00% | 2.00% | 2.00% |
| +5% | 2.27% | 2.38% | 2.98% | 4.73% |
| +10% | 2.54% | 2.76% | 3.97% | 7.52% |
| +25% | 3.36% | 3.90% | 7.00% | 16.37% |
| +50% | 4.74% | 5.83% | 12.25% | 32.77% |
| +100% | 7.56% | 9.81% | 23.52% | 70.00% (cap) |
At system_rate = 2.5% APY the same path starts at 2.50% at neutral; at +100% error it is 8.09% immediately, 24.13% after a week and at the 70% cap by four weeks.
At a higher system rate (controller responding to RD trading below $1), the neutral row shifts up and the caps are reached sooner.
Shield pricing
Shield pricing produces two cohort-specific signed additions from the same shield-share curve: a surcharge for the Redemption Shield book and a discount for the base book. From InterestEngine._calcRates:
unShieldedRate = _collRate.sub(v); // base pays branch_rate − v
shieldedRate = _collRate.add(u); // Redemption Shield cohort pays branch_rate + u
u and v are both non-negative quantities derived from the same shield-share curve. So:
- A trove with Redemption Shield enabled pays a positive shield-share adjustment (
+u). Call this the shield surcharge. - A trove without Redemption Shield receives a negative shield-share adjustment (
−v). Call this the base discount.
There is no second 0.1%–70% clamp after these adjustments. That range applies to the input branch rate; the shield-pricing curve bounds the cohort rates separately. At full priced shield share, the base rate reaches −50% APY, while the Redemption Shield rate can exceed 70% APY.
The two are halves of the same mechanism: the Redemption Shield cohort's surcharge and the base cohort's discount are set together from the same shield share, but they are not balanced one-for-one. Below the 85% kink the discount per unit of base debt is twice the surcharge per unit of shielded debt, so total branch interest is below the collateral rate unless the shielded share is large; ShieldPricingMath.enforceAccrualSolvency only guarantees that branch debt never shrinks through a drip. If you prefer to call the whole thing the "shield premium," that's fine, but note the premium is signed: positive for troves with Redemption Shield enabled, negative for troves without Redemption Shield.
The curve is designed so that:
- The Redemption Shield cohort book subsidizes the base book. Every Redemption Shield surcharge corresponds to a base discount.
- The base rate can't go below a floor. Even at full subsidy, the base rate is bounded; the floor is the
_V_MAXendpoint, equivalent to −50% APY. - Both sides scale with Redemption Shield share. A branch with 5% Redemption Shield share has small
uandv; a branch at 80% has much larger ones.
When the base rate is negative, base debt shrinks during a drip. The contract then requires the Redemption Shield cohort's debt growth over that drip to at least cover the base cohort's debt reduction, raising the shield accumulator minimally if rounding would fall short (ShieldPricingMath.enforceAccrualSolvency). Aggregate branch debt therefore never falls through interest.
Constants
_S1 = 0.85e27 // shield-share kink (85%)
_ALPHA = 0.5e27 // surcharge at the kink: u = 0.5 × branch delta
_U_MULT = 2e27 // full-shield surcharge candidate: u = 2 × branch delta
_V_MAX = 21979552668138406918 // full-shield base endpoint (−50% APY)
SHIELD_PRICING_CONSTANT_MIN = 50,000e18 // minimum pricing-floor debt (ShieldPricingMath)
SHIELD_SHARE_EMA_HALFLIFE = 12 hours
With d = branch_rate − 1 (the branch's per-second delta) and s the priced shield share:
- Below the kink (
s ≤ 85%):v = d × s/85%andu = 0.5 × d × s/85%. The base rate falls linearly from the branch rate to 0% at the kink; the surcharge rises to half the branch delta. - Above the kink: with
z = (s − 85%)/15%,v = d + max(_V_MAX, d) × zandurises from0.5 × dtoward the larger of2 × dand a guard term. At full shield the base rate reaches −50% APY.
The priced shield share is not the raw spot share. It is the lower of the raw share and its 12-hour EMA, scaled down on small branches: priced = min(EMA, spot) × branchDebt / max(branchDebt, floorDebt), where floorDebt = max(50,000 RD, lowerSoft × global debt EMA). Taking the lower of the two smooths increases only: a single transaction can't push the price of shield protection up, but a drop in the spot share is priced immediately. The floor keeps a nearly empty branch from pricing at an extreme share.
Why this shape
If shield pricing were flat:
- A branch with 1% Redemption Shield share would charge the same surcharge as one at 90%, even though the second case offers far less protection because almost every trove has Redemption Shield enabled.
- The base book could be redeemed out faster than redemption demand actually creates, leaving every remaining trove with Redemption Shield enabled.
The curve makes the surcharge expensive precisely when Redemption Shield is overcrowded, which is the right economic signal. The matching base discount on high-share branches makes leaving Redemption Shield disabled attractive, which keeps a redeemable book available.
What the dashboard shows
A user's effective borrow rate is the clamped branch rate plus the signed adjustment for their cohort. In per-second units, before annualizing for display:
branch_rate = 1 + clamp((system_rate − 1) + branch_offset, MIN_FINAL_DELTA, MAX_FINAL_DELTA)
your_rate = branch_rate + shield_adjustment
where shield_adjustment depends on the branch's Redemption Shield share:
trove with Redemption Shield enabled → +u (a surcharge; you pay extra)
trove without Redemption Shield → −v (a discount set with the Redemption Shield surcharge)
Both u and v are non-negative and grow with Redemption Shield share. On a high-share branch, troves without Redemption Shield can borrow at a meaningfully lower rate than the branch rate: 0% at an 85% priced share, and negative above it.
Why interest accrues continuously
Liquity v1 had a one-time issuance fee plus a decaying base rate. The continuously-accruing model is closer to a standard variable-rate loan and gives the controller a smoother knob to turn. There's no fee shock at borrow time.
The downside is that ICR moves over time even if collateral price is constant because interest accrues. A trove sitting just above its MCR with debt growing 5% a year will fall below the MCR within weeks to months without any external event. Borrowers should plan for this.
How drip actually fires
Branches drip on three triggers:
- Branch operations: borrower operations, liquidations, Stability Pool deposits and withdrawals, and
MinTrovecallTroveManager.dripUpdateRateParDebtEmaAndDeltaRate(), which drips that branch only (throughInterestEngine.drip(), callable only by the branch'sTroveManager), updatesRateParControl, and refreshes the branch's debt EMA and offset. Aggregator.drip(): anyone can call it. It sweeps every non-shutdown branch throughInterestEngine.aggDrip(...)(callable only by the Aggregator) and routes the batch's fees toGlobalFeeRouteronce. Redemptions call it too.KeeperRewards.updateWithReward(): the paid keeper path. It callsAggregator.dripWithRewardCap()(callable only byKeeperRewards) and updatesRateParControl. The drip reward isDRIP_REWARD_BPS = 2%of the interest banked since the last rewarded drip, times a cubic ramp: zero untilDRIP_INTERVAL = 3 hourshave passed since that reward, reaching full weight atDRIP_INTERVAL_2 = 8 hours. It is capped by the RD balance held inKeeperRewards.
The reward structure pulls some keeper attention without making the drip a profitable game by itself. Any user op already does the drip for free as part of its work.
Deep dive
- Peg control: where
system_ratecomes from. - Borrow rates (user view): same content, less detail.