fix!: correct borrowing rate in recovery mode

BREAKING CHANGE: `fees` has been moved from `LiquityStoreBaseState`
to `LiquityStoreDerivedState`.

Most users won't need to make a code change. However, care should
be taken to upgrade both SDK packages at the same time, to ensure
compatibility.

Fixes liquity#300.

Author: danielattilasimon

docs/sdk/lib-base.liquitystorebasestate.md

@@ -18,7 +18,6 @@ export interface LiquityStoreBaseState
 |  --- | --- | --- |
 |  [accountBalance](./lib-base.liquitystorebasestate.accountbalance.md) | [Decimal](./lib-base.decimal.md) | User's native currency balance (e.g. Ether). |
 |  [collateralSurplusBalance](./lib-base.liquitystorebasestate.collateralsurplusbalance.md) | [Decimal](./lib-base.decimal.md) | Amount of leftover collateral available for withdrawal to the user. |
-|  [fees](./lib-base.liquitystorebasestate.fees.md) | [Fees](./lib-base.fees.md) | Calculator for current fees. |
 |  [frontend](./lib-base.liquitystorebasestate.frontend.md) | [FrontendStatus](./lib-base.frontendstatus.md) | Status of currently used frontend. |
 |  [lqtyBalance](./lib-base.liquitystorebasestate.lqtybalance.md) | [Decimal](./lib-base.decimal.md) | User's LQTY token balance. |
 |  [lqtyStake](./lib-base.liquitystorebasestate.lqtystake.md) | [LQTYStake](./lib-base.lqtystake.md) | User's LQTY stake. |

docs/sdk/lib-base.liquitystorebasestate.fees.md renamed to docs/sdk/lib-base.liquitystorederivedstate.fees.md

@@ -1,8 +1,8 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [LiquityStoreBaseState](./lib-base.liquitystorebasestate.md) &gt; [fees](./lib-base.liquitystorebasestate.fees.md)
+[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [LiquityStoreDerivedState](./lib-base.liquitystorederivedstate.md) &gt; [fees](./lib-base.liquitystorederivedstate.fees.md)
 
-## LiquityStoreBaseState.fees property
+## LiquityStoreDerivedState.fees property
 
 Calculator for current fees.
 

docs/sdk/lib-base.liquitystorederivedstate.md

@@ -17,6 +17,7 @@ export interface LiquityStoreDerivedState
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [borrowingRate](./lib-base.liquitystorederivedstate.borrowingrate.md) | [Decimal](./lib-base.decimal.md) | Current borrowing rate. |
+|  [fees](./lib-base.liquitystorederivedstate.fees.md) | [Fees](./lib-base.fees.md) | Calculator for current fees. |
 |  [redemptionRate](./lib-base.liquitystorederivedstate.redemptionrate.md) | [Decimal](./lib-base.decimal.md) | Current redemption rate. |
 |  [trove](./lib-base.liquitystorederivedstate.trove.md) | [Trove](./lib-base.trove.md) | Current state of user's Trove |
 

docs/sdk/lib-base.minimum_borrowing_rate.md

@@ -11,3 +11,8 @@ Value that the [borrowing rate](./lib-base.fees.borrowingrate.md) will never dec
 ```typescript
 MINIMUM_BORROWING_RATE: Decimal
 ```
+
+## Remarks
+
+Note that the borrowing rate can still be lower than this during recovery mode, when it's overridden by zero.
+

packages/lib-base/etc/lib-base.api.md

@@ -12,6 +12,8 @@ export class _CachedReadableLiquity<T extends unknown[]> implements _ReadableLiq
     // (undocumented)
     getFees(...extraParams: T): Promise<Fees>;
     // (undocumented)
+    _getFeesInNormalMode(...extraParams: T): Promise<Fees>;
+    // (undocumented)
     getFrontendStatus(address?: string, ...extraParams: T): Promise<FrontendStatus>;
     // (undocumented)
     getLQTYBalance(address?: string, ...extraParams: T): Promise<Decimal>;
@@ -175,13 +177,15 @@ export const _failedReceipt: <R>(rawReceipt: R) => FailedReceipt<R>;
 // @public
 export class Fees {
     // @internal
-    constructor(lastFeeOperation: Date, baseRateWithoutDecay: Decimalish, minuteDecayFactor: Decimalish, beta: Decimalish);
+    constructor(lastFeeOperation: Date, baseRateWithoutDecay: Decimalish, minuteDecayFactor: Decimalish, beta: Decimalish, recoveryMode?: boolean);
     // @internal (undocumented)
     baseRate(when: Date): Decimal;
     borrowingRate(): Decimal;
     equals(that: Fees): boolean;
     redemptionRate(redeemedFractionOfSupply?: Decimalish): Decimal;
     // @internal (undocumented)
+    _setRecoveryMode(recoveryMode: boolean): Fees;
+    // @internal (undocumented)
     toString(): string;
 }
 
@@ -242,7 +246,8 @@ export abstract class LiquityStore<T = unknown> {
 export interface LiquityStoreBaseState {
     accountBalance: Decimal;
     collateralSurplusBalance: Decimal;
-    fees: Fees;
+    // @internal (undocumented)
+    _feesInNormalMode: Fees;
     frontend: FrontendStatus;
     lqtyBalance: Decimal;
     lqtyStake: LQTYStake;
@@ -261,6 +266,7 @@ export interface LiquityStoreBaseState {
 // @public
 export interface LiquityStoreDerivedState {
     borrowingRate: Decimal;
+    fees: Fees;
     redemptionRate: Decimal;
     trove: Trove;
 }
@@ -446,6 +452,8 @@ export interface PopulatedLiquityTransaction<P = unknown, T extends SentLiquityT
 export interface ReadableLiquity {
     getCollateralSurplusBalance(address?: string): Promise<Decimal>;
     getFees(): Promise<Fees>;
+    // @internal (undocumented)
+    _getFeesInNormalMode(): Promise<Fees>;
     getFrontendStatus(address?: string): Promise<FrontendStatus>;
     getLQTYBalance(address?: string): Promise<Decimal>;
     getLQTYStake(address?: string): Promise<LQTYStake>;

packages/lib-base/src/Fees.ts

@@ -21,22 +21,36 @@ export class Fees {
   private readonly _minuteDecayFactor: Decimal;
   private readonly _beta: Decimal;
   private readonly _lastFeeOperation: Date;
+  private readonly _recoveryMode: boolean;
 
   /** @internal */
   constructor(
     lastFeeOperation: Date,
     baseRateWithoutDecay: Decimalish,
     minuteDecayFactor: Decimalish,
-    beta: Decimalish
+    beta: Decimalish,
+    recoveryMode = false
   ) {
     this._lastFeeOperation = lastFeeOperation;
     this._baseRateWithoutDecay = Decimal.from(baseRateWithoutDecay);
     this._minuteDecayFactor = Decimal.from(minuteDecayFactor);
     this._beta = Decimal.from(beta);
+    this._recoveryMode = recoveryMode;
 
     assert(this._minuteDecayFactor.lt(1));
   }
 
+  /** @internal */
+  _setRecoveryMode(recoveryMode: boolean): Fees {
+    return new Fees(
+      this._lastFeeOperation,
+      this._baseRateWithoutDecay,
+      this._minuteDecayFactor,
+      this._beta,
+      recoveryMode
+    );
+  }
+
   /**
    * Compare to another instance of `Fees`.
    */
@@ -45,15 +59,17 @@ export class Fees {
       this._baseRateWithoutDecay.eq(that._baseRateWithoutDecay) &&
       this._minuteDecayFactor.eq(that._minuteDecayFactor) &&
       this._beta.eq(that._beta) &&
-      this._lastFeeOperation.getTime() === that._lastFeeOperation.getTime()
+      this._lastFeeOperation.getTime() === that._lastFeeOperation.getTime() &&
+      this._recoveryMode === that._recoveryMode
     );
   }
 
   /** @internal */
   toString(): string {
     return (
       `{ baseRateWithoutDecay: ${this._baseRateWithoutDecay}` +
-      `, lastFeeOperation: "${this._lastFeeOperation.toLocaleString()}" } `
+      `, lastFeeOperation: "${this._lastFeeOperation.toLocaleString()}"` +
+      `, recoveryMode: ${this._recoveryMode} } `
     );
   }
 
@@ -86,10 +102,9 @@ export class Fees {
    * ```
    */
   borrowingRate(): Decimal {
-    return Decimal.min(
-      MINIMUM_BORROWING_RATE.add(this.baseRate(new Date())),
-      MAXIMUM_BORROWING_RATE
-    );
+    return this._recoveryMode
+      ? Decimal.ZERO
+      : Decimal.min(MINIMUM_BORROWING_RATE.add(this.baseRate(new Date())), MAXIMUM_BORROWING_RATE);
   }
 
   /**

packages/lib-base/src/LiquityStore.ts

@@ -69,8 +69,8 @@ export interface LiquityStoreBaseState {
   /** User's stability deposit. */
   stabilityDeposit: StabilityDeposit;
 
-  /** Calculator for current fees. */
-  fees: Fees;
+  /** @internal */
+  _feesInNormalMode: Fees;
 
   /** User's LQTY stake. */
   lqtyStake: LQTYStake;
@@ -88,6 +88,9 @@ export interface LiquityStoreDerivedState {
   /** Current state of user's Trove */
   trove: Trove;
 
+  /** Calculator for current fees. */
+  fees: Fees;
+
   /**
    * Current borrowing rate.
    *
@@ -359,7 +362,11 @@ export abstract class LiquityStore<T = unknown> {
         baseStateUpdate.stabilityDeposit
       ),
 
-      fees: this._updateIfChanged(equals, "fees", baseState.fees, baseStateUpdate.fees),
+      _feesInNormalMode: this._silentlyUpdateIfChanged(
+        equals,
+        baseState._feesInNormalMode,
+        baseStateUpdate._feesInNormalMode
+      ),
 
       lqtyStake: this._updateIfChanged(
         equals,
@@ -380,10 +387,15 @@ export abstract class LiquityStore<T = unknown> {
   private _derive({
     troveBeforeRedistribution,
     totalRedistributed,
-    fees
+    _feesInNormalMode,
+    total,
+    price
   }: LiquityStoreBaseState): LiquityStoreDerivedState {
+    const fees = _feesInNormalMode._setRecoveryMode(total.collateralRatioIsBelowCritical(price));
+
     return {
       trove: troveBeforeRedistribution.applyRedistribution(totalRedistributed),
+      fees,
       borrowingRate: fees.borrowingRate(),
       redemptionRate: fees.redemptionRate()
     };
@@ -396,6 +408,8 @@ export abstract class LiquityStore<T = unknown> {
     return {
       trove: this._updateIfChanged(equals, "trove", derivedState.trove, derivedStateUpdate.trove),
 
+      fees: this._updateIfChanged(equals, "fees", derivedState.fees, derivedStateUpdate.fees),
+
       borrowingRate: this._silentlyUpdateIfChanged(
         eq,
         derivedState.borrowingRate,

packages/lib-base/src/ReadableLiquity.ts

@@ -144,6 +144,9 @@ export interface ReadableLiquity {
    */
   getTroves(params: TroveListingParams): Promise<[address: string, trove: Trove][]>;
 
+  /** @internal */
+  _getFeesInNormalMode(): Promise<Fees>;
+
   /**
    * Get a calculator for current fees.
    */

packages/lib-base/src/_CachedReadableLiquity.ts

@@ -167,30 +167,40 @@ export class _CachedReadableLiquity<T extends unknown[]>
     }
   }
 
-  async getFees(...extraParams: T): Promise<Fees> {
+  async _getFeesInNormalMode(...extraParams: T): Promise<Fees> {
     return (
-      this._cache.getFees?.call(this._cache, ...extraParams) ??
-      this._readable.getFees(...extraParams)
+      this._cache._getFeesInNormalMode(...extraParams) ??
+      this._readable._getFeesInNormalMode(...extraParams)
     );
   }
 
+  async getFees(...extraParams: T): Promise<Fees> {
+    const [feesInNormalMode, total, price] = await Promise.all([
+      this._getFeesInNormalMode(...extraParams),
+      this.getTotal(...extraParams),
+      this.getPrice(...extraParams)
+    ]);
+
+    return feesInNormalMode._setRecoveryMode(total.collateralRatioIsBelowCritical(price));
+  }
+
   async getLQTYStake(address?: string, ...extraParams: T): Promise<LQTYStake> {
     return (
-      this._cache.getLQTYStake?.call(this._cache, address, ...extraParams) ??
+      this._cache.getLQTYStake(address, ...extraParams) ??
       this._readable.getLQTYStake(address, ...extraParams)
     );
   }
 
   async getTotalStakedLQTY(...extraParams: T): Promise<Decimal> {
     return (
-      this._cache.getTotalStakedLQTY?.call(this._cache, ...extraParams) ??
+      this._cache.getTotalStakedLQTY(...extraParams) ??
       this._readable.getTotalStakedLQTY(...extraParams)
     );
   }
 
   async getFrontendStatus(address?: string, ...extraParams: T): Promise<FrontendStatus> {
     return (
-      this._cache.getFrontendStatus?.call(this._cache, address, ...extraParams) ??
+      this._cache.getFrontendStatus(address, ...extraParams) ??
       this._readable.getFrontendStatus(address, ...extraParams)
     );
   }

packages/lib-base/src/constants.ts

@@ -24,6 +24,10 @@ export const LUSD_LIQUIDATION_RESERVE = Decimal.from(50);
 /**
  * Value that the {@link Fees.borrowingRate | borrowing rate} will never decay below.
  *
+ * @remarks
+ * Note that the borrowing rate can still be lower than this during recovery mode, when it's
+ * overridden by zero.
+ *
  * @public
  */
 export const MINIMUM_BORROWING_RATE = Decimal.from(0.005);

packages/lib-ethers/etc/lib-ethers.api.md

@@ -111,6 +111,8 @@ export class EthersLiquity implements ReadableEthersLiquity, TransactableLiquity
     getCollateralSurplusBalance(address?: string, overrides?: EthersCallOverrides): Promise<Decimal>;
     // (undocumented)
     getFees(overrides?: EthersCallOverrides): Promise<Fees>;
+    // @internal (undocumented)
+    _getFeesInNormalMode(overrides?: EthersCallOverrides): Promise<Fees>;
     // (undocumented)
     getFrontendStatus(address?: string, overrides?: EthersCallOverrides): Promise<FrontendStatus>;
     // (undocumented)
@@ -345,6 +347,8 @@ export class ReadableEthersLiquity implements ReadableLiquity {
     getCollateralSurplusBalance(address?: string, overrides?: EthersCallOverrides): Promise<Decimal>;
     // (undocumented)
     getFees(overrides?: EthersCallOverrides): Promise<Fees>;
+    // @internal (undocumented)
+    _getFeesInNormalMode(overrides?: EthersCallOverrides): Promise<Fees>;
     // (undocumented)
     getFrontendStatus(address?: string, overrides?: EthersCallOverrides): Promise<FrontendStatus>;
     // (undocumented)

packages/lib-ethers/package.json

@@ -33,7 +33,7 @@
     "test-live:run": "cross-env USE_LIVE_VERSION=true hardhat test"
   },
   "peerDependencies": {
-    "@liquity/lib-base": "^1.0.0",
+    "@liquity/lib-base": "^2.0.0",
     "ethers": "^5.0.0"
   },
   "devDependencies": {

packages/lib-ethers/src/BlockPolledLiquityStore.ts

@@ -80,7 +80,7 @@ export class BlockPolledLiquityStore extends LiquityStore<BlockPolledLiquityStor
       totalRedistributed: this._readable.getTotalRedistributed({ blockTag }),
       total: this._readable.getTotal({ blockTag }),
       lusdInStabilityPool: this._readable.getLUSDInStabilityPool({ blockTag }),
-      fees: this._readable.getFees({ blockTag }),
+      _feesInNormalMode: this._readable._getFeesInNormalMode({ blockTag }),
       totalStakedLQTY: this._readable.getTotalStakedLQTY({ blockTag }),
 
       frontend: frontendTag

packages/lib-ethers/src/EthersLiquity.ts

@@ -227,6 +227,11 @@ export class EthersLiquity implements ReadableEthersLiquity, TransactableLiquity
     return this._readable.getTroves(params, overrides);
   }
 
+  /** @internal */
+  _getFeesInNormalMode(overrides?: EthersCallOverrides): Promise<Fees> {
+    return this._readable._getFeesInNormalMode(overrides);
+  }
+
   /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getFees} */
   getFees(overrides?: EthersCallOverrides): Promise<Fees> {
     return this._readable.getFees(overrides);

packages/lib-ethers/src/ReadableEthersLiquity.ts

@@ -168,12 +168,10 @@ export class ReadableEthersLiquity implements ReadableLiquity {
 
   /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getTrove} */
   async getTrove(address?: string, overrides?: EthersCallOverrides): Promise<Trove> {
-    address ??= _requireAddress(this.connection);
-
     const [trove, totalRedistributed] = await Promise.all([
-      this.getTroveBeforeRedistribution(address, { ...overrides }),
-      this.getTotalRedistributed({ ...overrides })
-    ] as const);
+      this.getTroveBeforeRedistribution(address, overrides),
+      this.getTotalRedistributed(overrides)
+    ]);
 
     return trove.applyRedistribution(totalRedistributed);
   }
@@ -316,8 +314,8 @@ export class ReadableEthersLiquity implements ReadableLiquity {
     }
   }
 
-  /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getFees} */
-  async getFees(overrides?: EthersCallOverrides): Promise<Fees> {
+  /** @internal */
+  async _getFeesInNormalMode(overrides?: EthersCallOverrides): Promise<Fees> {
     const { troveManager } = _getContracts(this.connection);
 
     const [lastFeeOperationTime, baseRateWithoutDecay] = await Promise.all([
@@ -330,6 +328,17 @@ export class ReadableEthersLiquity implements ReadableLiquity {
     return new Fees(lastFeeOperation, baseRateWithoutDecay, MINUTE_DECAY_FACTOR, BETA);
   }
 
+  /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getFees} */
+  async getFees(overrides?: EthersCallOverrides): Promise<Fees> {
+    const [feesInNormalMode, total, price] = await Promise.all([
+      this._getFeesInNormalMode(overrides),
+      this.getTotal(overrides),
+      this.getPrice(overrides)
+    ]);
+
+    return feesInNormalMode._setRecoveryMode(total.collateralRatioIsBelowCritical(price));
+  }
+
   /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getLQTYStake} */
   async getLQTYStake(address?: string, overrides?: EthersCallOverrides): Promise<LQTYStake> {
     address ??= _requireAddress(this.connection);
@@ -500,6 +509,12 @@ class BlockPolledLiquityStoreBasedCache
     }
   }
 
+  _getFeesInNormalMode(overrides?: EthersCallOverrides): Fees | undefined {
+    if (this._blockHit(overrides)) {
+      return this._store.state._feesInNormalMode;
+    }
+  }
+
   getFees(overrides?: EthersCallOverrides): Fees | undefined {
     if (this._blockHit(overrides)) {
       return this._store.state.fees;