feat: implement querying of remaining Stability Pool LQTY reward

docs/sdk/lib-base.liquitystorebasestate.md

@@ -29,6 +29,7 @@ export interface LiquityStoreBaseState
 |  [ownFrontend](./lib-base.liquitystorebasestate.ownfrontend.md) | [FrontendStatus](./lib-base.frontendstatus.md) | Status of user's own frontend. |
 |  [price](./lib-base.liquitystorebasestate.price.md) | [Decimal](./lib-base.decimal.md) | Current price of the native currency (e.g. Ether) in USD. |
 |  [remainingLiquidityMiningLQTYReward](./lib-base.liquitystorebasestate.remainingliquiditymininglqtyreward.md) | [Decimal](./lib-base.decimal.md) | Remaining LQTY that will be collectively rewarded to liquidity miners. |
+|  [remainingStabilityPoolLQTYReward](./lib-base.liquitystorebasestate.remainingstabilitypoollqtyreward.md) | [Decimal](./lib-base.decimal.md) | Remaining LQTY that will be collectively rewarded to stability depositors. |
 |  [stabilityDeposit](./lib-base.liquitystorebasestate.stabilitydeposit.md) | [StabilityDeposit](./lib-base.stabilitydeposit.md) | User's stability deposit. |
 |  [total](./lib-base.liquitystorebasestate.total.md) | [Trove](./lib-base.trove.md) | Total collateral and debt in the Liquity system. |
 |  [totalRedistributed](./lib-base.liquitystorebasestate.totalredistributed.md) | [Trove](./lib-base.trove.md) | Total collateral and debt per stake that has been liquidated through redistribution. |

docs/sdk/lib-base.liquitystorebasestate.remainingstabilitypoollqtyreward.md

@@ -0,0 +1,13 @@
+<!-- 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; [remainingStabilityPoolLQTYReward](./lib-base.liquitystorebasestate.remainingstabilitypoollqtyreward.md)
+
+## LiquityStoreBaseState.remainingStabilityPoolLQTYReward property
+
+Remaining LQTY that will be collectively rewarded to stability depositors.
+
+<b>Signature:</b>
+
+```typescript
+remainingStabilityPoolLQTYReward: Decimal;
+```

docs/sdk/lib-base.readableliquity.getremainingstabilitypoollqtyreward.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [ReadableLiquity](./lib-base.readableliquity.md) &gt; [getRemainingStabilityPoolLQTYReward](./lib-base.readableliquity.getremainingstabilitypoollqtyreward.md)
+
+## ReadableLiquity.getRemainingStabilityPoolLQTYReward() method
+
+Get the remaining LQTY that will be collectively rewarded to stability depositors.
+
+<b>Signature:</b>
+
+```typescript
+getRemainingStabilityPoolLQTYReward(): Promise<Decimal>;
+```
+<b>Returns:</b>
+
+Promise&lt;[Decimal](./lib-base.decimal.md)<!-- -->&gt;
+

docs/sdk/lib-base.readableliquity.md

@@ -32,6 +32,7 @@ Implemented by [EthersLiquity](./lib-ethers.ethersliquity.md)<!-- -->.
 |  [getNumberOfTroves()](./lib-base.readableliquity.getnumberoftroves.md) | Get number of Troves that are currently open. |
 |  [getPrice()](./lib-base.readableliquity.getprice.md) | Get the current price of the native currency (e.g. Ether) in USD. |
 |  [getRemainingLiquidityMiningLQTYReward()](./lib-base.readableliquity.getremainingliquiditymininglqtyreward.md) | Get the remaining LQTY that will be collectively rewarded to liquidity miners. |
+|  [getRemainingStabilityPoolLQTYReward()](./lib-base.readableliquity.getremainingstabilitypoollqtyreward.md) | Get the remaining LQTY that will be collectively rewarded to stability depositors. |
 |  [getStabilityDeposit(address)](./lib-base.readableliquity.getstabilitydeposit.md) | Get the current state of a Stability Deposit. |
 |  [getTotal()](./lib-base.readableliquity.gettotal.md) | Get the total amount of collateral and debt in the Liquity system. |
 |  [getTotalRedistributed()](./lib-base.readableliquity.gettotalredistributed.md) | Get the total collateral and debt per stake that has been liquidated through redistribution. |

docs/sdk/lib-ethers.ethersliquity.getremainingstabilitypoollqtyreward.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@liquity/lib-ethers](./lib-ethers.md) &gt; [EthersLiquity](./lib-ethers.ethersliquity.md) &gt; [getRemainingStabilityPoolLQTYReward](./lib-ethers.ethersliquity.getremainingstabilitypoollqtyreward.md)
+
+## EthersLiquity.getRemainingStabilityPoolLQTYReward() method
+
+Get the remaining LQTY that will be collectively rewarded to stability depositors.
+
+<b>Signature:</b>
+
+```typescript
+getRemainingStabilityPoolLQTYReward(overrides?: EthersCallOverrides): Promise<Decimal>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  overrides | [EthersCallOverrides](./lib-ethers.etherscalloverrides.md) |  |
+
+<b>Returns:</b>
+
+Promise&lt;[Decimal](./lib-base.decimal.md)<!-- -->&gt;
+

docs/sdk/lib-ethers.ethersliquity.md

@@ -50,6 +50,7 @@ The constructor for this class is marked as internal. Third-party code should no
 |  [getNumberOfTroves(overrides)](./lib-ethers.ethersliquity.getnumberoftroves.md) |  | Get number of Troves that are currently open. |
 |  [getPrice(overrides)](./lib-ethers.ethersliquity.getprice.md) |  | Get the current price of the native currency (e.g. Ether) in USD. |
 |  [getRemainingLiquidityMiningLQTYReward(overrides)](./lib-ethers.ethersliquity.getremainingliquiditymininglqtyreward.md) |  | Get the remaining LQTY that will be collectively rewarded to liquidity miners. |
+|  [getRemainingStabilityPoolLQTYReward(overrides)](./lib-ethers.ethersliquity.getremainingstabilitypoollqtyreward.md) |  | Get the remaining LQTY that will be collectively rewarded to stability depositors. |
 |  [getStabilityDeposit(address, overrides)](./lib-ethers.ethersliquity.getstabilitydeposit.md) |  | Get the current state of a Stability Deposit. |
 |  [getTotal(overrides)](./lib-ethers.ethersliquity.gettotal.md) |  | Get the total amount of collateral and debt in the Liquity system. |
 |  [getTotalRedistributed(overrides)](./lib-ethers.ethersliquity.gettotalredistributed.md) |  | Get the total collateral and debt per stake that has been liquidated through redistribution. |

docs/sdk/lib-ethers.ethersliquityconnection.md

@@ -29,5 +29,6 @@ Exposed through [ReadableEthersLiquity.connection](./lib-ethers.readableethersli
 |  [deploymentDate](./lib-ethers.ethersliquityconnection.deploymentdate.md) | Date | Date when the Liquity contracts were deployed. |
 |  [provider](./lib-ethers.ethersliquityconnection.provider.md) | [EthersProvider](./lib-ethers.ethersprovider.md) | Ethers <code>Provider</code> used for connecting to the network. |
 |  [signer?](./lib-ethers.ethersliquityconnection.signer.md) | [EthersSigner](./lib-ethers.etherssigner.md) | <i>(Optional)</i> Ethers <code>Signer</code> used for sending transactions. |
+|  [totalStabilityPoolLQTYReward](./lib-ethers.ethersliquityconnection.totalstabilitypoollqtyreward.md) | [Decimal](./lib-base.decimal.md) | Total amount of LQTY allocated for rewarding stability depositors. |
 |  [version](./lib-ethers.ethersliquityconnection.version.md) | string | Version of the Liquity contracts (Git commit hash). |
 

docs/sdk/lib-ethers.ethersliquityconnection.totalstabilitypoollqtyreward.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@liquity/lib-ethers](./lib-ethers.md) &gt; [EthersLiquityConnection](./lib-ethers.ethersliquityconnection.md) &gt; [totalStabilityPoolLQTYReward](./lib-ethers.ethersliquityconnection.totalstabilitypoollqtyreward.md)
+
+## EthersLiquityConnection.totalStabilityPoolLQTYReward property
+
+Total amount of LQTY allocated for rewarding stability depositors.
+
+<b>Signature:</b>
+
+```typescript
+readonly totalStabilityPoolLQTYReward: Decimal;
+```

docs/sdk/lib-ethers.readableethersliquity.getremainingstabilitypoollqtyreward.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@liquity/lib-ethers](./lib-ethers.md) &gt; [ReadableEthersLiquity](./lib-ethers.readableethersliquity.md) &gt; [getRemainingStabilityPoolLQTYReward](./lib-ethers.readableethersliquity.getremainingstabilitypoollqtyreward.md)
+
+## ReadableEthersLiquity.getRemainingStabilityPoolLQTYReward() method
+
+Get the remaining LQTY that will be collectively rewarded to stability depositors.
+
+<b>Signature:</b>
+
+```typescript
+getRemainingStabilityPoolLQTYReward(overrides?: EthersCallOverrides): Promise<Decimal>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  overrides | [EthersCallOverrides](./lib-ethers.etherscalloverrides.md) |  |
+
+<b>Returns:</b>
+
+Promise&lt;[Decimal](./lib-base.decimal.md)<!-- -->&gt;
+

docs/sdk/lib-ethers.readableethersliquity.md

@@ -40,6 +40,7 @@ The constructor for this class is marked as internal. Third-party code should no
 |  [getNumberOfTroves(overrides)](./lib-ethers.readableethersliquity.getnumberoftroves.md) |  | Get number of Troves that are currently open. |
 |  [getPrice(overrides)](./lib-ethers.readableethersliquity.getprice.md) |  | Get the current price of the native currency (e.g. Ether) in USD. |
 |  [getRemainingLiquidityMiningLQTYReward(overrides)](./lib-ethers.readableethersliquity.getremainingliquiditymininglqtyreward.md) |  | Get the remaining LQTY that will be collectively rewarded to liquidity miners. |
+|  [getRemainingStabilityPoolLQTYReward(overrides)](./lib-ethers.readableethersliquity.getremainingstabilitypoollqtyreward.md) |  | Get the remaining LQTY that will be collectively rewarded to stability depositors. |
 |  [getStabilityDeposit(address, overrides)](./lib-ethers.readableethersliquity.getstabilitydeposit.md) |  | Get the current state of a Stability Deposit. |
 |  [getTotal(overrides)](./lib-ethers.readableethersliquity.gettotal.md) |  | Get the total amount of collateral and debt in the Liquity system. |
 |  [getTotalRedistributed(overrides)](./lib-ethers.readableethersliquity.gettotalredistributed.md) |  | Get the total collateral and debt per stake that has been liquidated through redistribution. |

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

@@ -32,6 +32,8 @@ export class _CachedReadableLiquity<T extends unknown[]> implements _ReadableLiq
     // (undocumented)
     getRemainingLiquidityMiningLQTYReward(...extraParams: T): Promise<Decimal>;
     // (undocumented)
+    getRemainingStabilityPoolLQTYReward(...extraParams: T): Promise<Decimal>;
+    // (undocumented)
     getStabilityDeposit(address?: string, ...extraParams: T): Promise<StabilityDeposit>;
     // (undocumented)
     getTotal(...extraParams: T): Promise<Trove>;
@@ -271,6 +273,7 @@ export interface LiquityStoreBaseState {
     ownFrontend: FrontendStatus;
     price: Decimal;
     remainingLiquidityMiningLQTYReward: Decimal;
+    remainingStabilityPoolLQTYReward: Decimal;
     // @internal (undocumented)
     _riskiestTroveBeforeRedistribution: TroveWithPendingRedistribution;
     stabilityDeposit: StabilityDeposit;
@@ -499,6 +502,7 @@ export interface ReadableLiquity {
     getNumberOfTroves(): Promise<number>;
     getPrice(): Promise<Decimal>;
     getRemainingLiquidityMiningLQTYReward(): Promise<Decimal>;
+    getRemainingStabilityPoolLQTYReward(): Promise<Decimal>;
     getStabilityDeposit(address?: string): Promise<StabilityDeposit>;
     getTotal(): Promise<Trove>;
     getTotalRedistributed(): Promise<Trove>;

packages/lib-base/src/LiquityStore.ts

@@ -87,6 +87,9 @@ export interface LiquityStoreBaseState {
   /** User's stability deposit. */
   stabilityDeposit: StabilityDeposit;
 
+  /** Remaining LQTY that will be collectively rewarded to stability depositors. */
+  remainingStabilityPoolLQTYReward: Decimal;
+
   /** @internal */
   _feesInNormalMode: Fees;
 
@@ -397,9 +400,8 @@ export abstract class LiquityStore<T = unknown> {
         baseStateUpdate.totalStakedUniTokens
       ),
 
-      liquidityMiningLQTYReward: this._updateIfChanged(
+      liquidityMiningLQTYReward: this._silentlyUpdateIfChanged(
         eq,
-        "liquidityMiningLQTYReward",
         baseState.liquidityMiningLQTYReward,
         baseStateUpdate.liquidityMiningLQTYReward
       ),
@@ -443,6 +445,12 @@ export abstract class LiquityStore<T = unknown> {
         baseStateUpdate.stabilityDeposit
       ),
 
+      remainingStabilityPoolLQTYReward: this._silentlyUpdateIfChanged(
+        eq,
+        baseState.remainingStabilityPoolLQTYReward,
+        baseStateUpdate.remainingStabilityPoolLQTYReward
+      ),
+
       _feesInNormalMode: this._silentlyUpdateIfChanged(
         equals,
         baseState._feesInNormalMode,

packages/lib-base/src/ReadableLiquity.ts

@@ -101,6 +101,11 @@ export interface ReadableLiquity {
    */
   getStabilityDeposit(address?: string): Promise<StabilityDeposit>;
 
+  /**
+   * Get the remaining LQTY that will be collectively rewarded to stability depositors.
+   */
+  getRemainingStabilityPoolLQTYReward(): Promise<Decimal>;
+
   /**
    * Get the total amount of LUSD currently deposited in the Stability Pool.
    */

packages/lib-base/src/_CachedReadableLiquity.ts

@@ -101,6 +101,13 @@ export class _CachedReadableLiquity<T extends unknown[]>
     );
   }
 
+  async getRemainingStabilityPoolLQTYReward(...extraParams: T): Promise<Decimal> {
+    return (
+      this._cache.getRemainingStabilityPoolLQTYReward(...extraParams) ??
+      this._readable.getRemainingStabilityPoolLQTYReward(...extraParams)
+    );
+  }
+
   async getLUSDInStabilityPool(...extraParams: T): Promise<Decimal> {
     return (
       this._cache.getLUSDInStabilityPool(...extraParams) ??

packages/lib-ethers/deployments/default/goerli.json

@@ -3,6 +3,7 @@
   "version": "6201cfd8c83fc3828483e17f5f05ca4168f56c0c",
   "deploymentDate": 1616755061000,
   "bootstrapPeriod": 1209600,
+  "totalStabilityPoolLQTYReward": "32000000",
   "_priceFeedIsTestnet": true,
   "_uniTokenIsMock": false,
   "_isDev": false,

packages/lib-ethers/deployments/default/kovan.json

@@ -3,6 +3,7 @@
   "version": "6201cfd8c83fc3828483e17f5f05ca4168f56c0c",
   "deploymentDate": 1616753759000,
   "bootstrapPeriod": 1209600,
+  "totalStabilityPoolLQTYReward": "32000000",
   "_priceFeedIsTestnet": false,
   "_uniTokenIsMock": false,
   "_isDev": false,

packages/lib-ethers/deployments/default/rinkeby.json

@@ -3,6 +3,7 @@
   "version": "6201cfd8c83fc3828483e17f5f05ca4168f56c0c",
   "deploymentDate": 1616758339000,
   "bootstrapPeriod": 1209600,
+  "totalStabilityPoolLQTYReward": "32000000",
   "_priceFeedIsTestnet": true,
   "_uniTokenIsMock": false,
   "_isDev": false,

packages/lib-ethers/deployments/default/ropsten.json

@@ -3,6 +3,7 @@
   "version": "6201cfd8c83fc3828483e17f5f05ca4168f56c0c",
   "deploymentDate": 1616754932000,
   "bootstrapPeriod": 1209600,
+  "totalStabilityPoolLQTYReward": "32000000",
   "_priceFeedIsTestnet": true,
   "_uniTokenIsMock": false,
   "_isDev": false,

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

@@ -147,6 +147,8 @@ export class EthersLiquity implements ReadableEthersLiquity, TransactableLiquity
     // @internal (undocumented)
     _getRemainingLiquidityMiningLQTYRewardCalculator(overrides?: EthersCallOverrides): Promise<(blockTimestamp: number) => Decimal>;
     // (undocumented)
+    getRemainingStabilityPoolLQTYReward(overrides?: EthersCallOverrides): Promise<Decimal>;
+    // (undocumented)
     getStabilityDeposit(address?: string, overrides?: EthersCallOverrides): Promise<StabilityDeposit>;
     // (undocumented)
     getTotal(overrides?: EthersCallOverrides): Promise<Trove>;
@@ -230,6 +232,7 @@ export interface EthersLiquityConnection extends EthersLiquityConnectionOptional
     readonly _priceFeedIsTestnet: boolean;
     readonly provider: EthersProvider;
     readonly signer?: EthersSigner;
+    readonly totalStabilityPoolLQTYReward: Decimal;
     readonly version: string;
 }
 
@@ -436,6 +439,8 @@ export class ReadableEthersLiquity implements ReadableLiquity {
     // @internal (undocumented)
     _getRemainingLiquidityMiningLQTYRewardCalculator(overrides?: EthersCallOverrides): Promise<(blockTimestamp: number) => Decimal>;
     // (undocumented)
+    getRemainingStabilityPoolLQTYReward(overrides?: EthersCallOverrides): Promise<Decimal>;
+    // (undocumented)
     getStabilityDeposit(address?: string, overrides?: EthersCallOverrides): Promise<StabilityDeposit>;
     // (undocumented)
     getTotal(overrides?: EthersCallOverrides): Promise<Trove>;

packages/lib-ethers/src/BlockPolledLiquityStore.ts

@@ -121,6 +121,9 @@ export class BlockPolledLiquityStore extends LiquityStore<BlockPolledLiquityStor
       totalStakedLQTY: this._readable.getTotalStakedLQTY({ blockTag }),
       _riskiestTroveBeforeRedistribution: this._getRiskiestTroveBeforeRedistribution({ blockTag }),
       totalStakedUniTokens: this._readable.getTotalStakedUniTokens({ blockTag }),
+      remainingStabilityPoolLQTYReward: this._readable.getRemainingStabilityPoolLQTYReward({
+        blockTag
+      }),
 
       frontend: frontendTag
         ? this._readable.getFrontendStatus(frontendTag, { blockTag })

packages/lib-ethers/src/EthersLiquity.ts

@@ -199,6 +199,11 @@ export class EthersLiquity implements ReadableEthersLiquity, TransactableLiquity
     return this._readable.getStabilityDeposit(address, overrides);
   }
 
+  /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getRemainingStabilityPoolLQTYReward} */
+  getRemainingStabilityPoolLQTYReward(overrides?: EthersCallOverrides): Promise<Decimal> {
+    return this._readable.getRemainingStabilityPoolLQTYReward(overrides);
+  }
+
   /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getLUSDInStabilityPool} */
   getLUSDInStabilityPool(overrides?: EthersCallOverrides): Promise<Decimal> {
     return this._readable.getLUSDInStabilityPool(overrides);

packages/lib-ethers/src/EthersLiquityConnection.ts

@@ -2,6 +2,8 @@ import { BigNumber } from "@ethersproject/bignumber";
 import { Block, BlockTag } from "@ethersproject/abstract-provider";
 import { Signer } from "@ethersproject/abstract-signer";
 
+import { Decimal } from "@liquity/lib-base";
+
 import devOrNull from "../deployments/dev.json";
 import goerli from "../deployments/goerli.json";
 import kovan from "../deployments/kovan.json";
@@ -65,6 +67,9 @@ export interface EthersLiquityConnection extends EthersLiquityConnectionOptional
   /** Time period (in seconds) after `deploymentDate` during which redemptions are disabled. */
   readonly bootstrapPeriod: number;
 
+  /** Total amount of LQTY allocated for rewarding stability depositors. */
+  readonly totalStabilityPoolLQTYReward: Decimal;
+
   /** A mapping of Liquity contracts' names to their addresses. */
   readonly addresses: Record<string, string>;
 
@@ -90,7 +95,7 @@ const connectionFrom = (
   signer: EthersSigner | undefined,
   _contracts: _LiquityContracts,
   _multicall: _Multicall | undefined,
-  { deploymentDate, ...deployment }: _LiquityDeploymentJSON,
+  { deploymentDate, totalStabilityPoolLQTYReward, ...deployment }: _LiquityDeploymentJSON,
   optionalParams?: EthersLiquityConnectionOptionalParams
 ): _InternalEthersLiquityConnection => {
   if (
@@ -107,6 +112,7 @@ const connectionFrom = (
     _contracts,
     _multicall,
     deploymentDate: new Date(deploymentDate),
+    totalStabilityPoolLQTYReward: Decimal.from(totalStabilityPoolLQTYReward),
     ...deployment,
     ...optionalParams
   });

packages/lib-ethers/src/ReadableEthersLiquity.ts

@@ -281,6 +281,17 @@ export class ReadableEthersLiquity implements ReadableLiquity {
     return new StabilityDeposit(initialLUSD, currentLUSD, collateralGain, lqtyReward);
   }
 
+  /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getRemainingStabilityPoolLQTYReward} */
+  async getRemainingStabilityPoolLQTYReward(overrides?: EthersCallOverrides): Promise<Decimal> {
+    const { communityIssuance } = _getContracts(this.connection);
+
+    const issuanceCap = this.connection.totalStabilityPoolLQTYReward;
+    const totalLQTYIssued = decimalify(await communityIssuance.totalLQTYIssued({ ...overrides }));
+
+    // totalLQTYIssued approaches but never reaches issuanceCap
+    return issuanceCap.sub(totalLQTYIssued);
+  }
+
   /** {@inheritDoc @liquity/lib-base#ReadableLiquity.getLUSDInStabilityPool} */
   getLUSDInStabilityPool(overrides?: EthersCallOverrides): Promise<Decimal> {
     const { stabilityPool } = _getContracts(this.connection);
@@ -602,6 +613,12 @@ class BlockPolledLiquityStoreBasedCache
     }
   }
 
+  getRemainingStabilityPoolLQTYReward(overrides?: EthersCallOverrides): Decimal | undefined {
+    if (this._blockHit(overrides)) {
+      return this._store.state.remainingStabilityPoolLQTYReward;
+    }
+  }
+
   getLUSDInStabilityPool(overrides?: EthersCallOverrides): Decimal | undefined {
     if (this._blockHit(overrides)) {
       return this._store.state.lusdInStabilityPool;

packages/lib-ethers/src/contracts.ts

@@ -225,6 +225,7 @@ export interface _LiquityDeploymentJSON {
   readonly version: string;
   readonly deploymentDate: number;
   readonly bootstrapPeriod: number;
+  readonly totalStabilityPoolLQTYReward: string;
   readonly _priceFeedIsTestnet: boolean;
   readonly _uniTokenIsMock: boolean;
   readonly _isDev: boolean;