@sovryn-zero/lib-base 0.1.0

package/src/ZEROStake.ts

@@ -0,0 +1,99 @@
+import { Decimal, Decimalish } from "./Decimal";
+
+/**
+ * Represents the change between two states of an ZERO Stake.
+ *
+ * @public
+ */
+export type ZEROStakeChange<T> =
+  | { stakeZERO: T; unstakeZERO?: undefined }
+  | { stakeZERO?: undefined; unstakeZERO: T; unstakeAllZERO: boolean };
+
+/** 
+ * Represents a user's ZERO stake and accrued gains.
+ * 
+ * @remarks
+ * Returned by the {@link ReadableLiquity.getZEROStake | getZEROStake()} function.
+
+ * @public
+ */
+export class ZEROStake {
+  /** The amount of ZERO that's staked. */
+  readonly stakedZERO: Decimal;
+
+  /** Collateral gain available to withdraw. */
+  readonly collateralGain: Decimal;
+
+  /** ZUSD gain available to withdraw. */
+  readonly zusdGain: Decimal;
+
+  /** @internal */
+  constructor(stakedZERO = Decimal.ZERO, collateralGain = Decimal.ZERO, zusdGain = Decimal.ZERO) {
+    this.stakedZERO = stakedZERO;
+    this.collateralGain = collateralGain;
+    this.zusdGain = zusdGain;
+  }
+
+  get isEmpty(): boolean {
+    return this.stakedZERO.isZero && this.collateralGain.isZero && this.zusdGain.isZero;
+  }
+
+  /** @internal */
+  toString(): string {
+    return (
+      `{ stakedZERO: ${this.stakedZERO}` +
+      `, collateralGain: ${this.collateralGain}` +
+      `, zusdGain: ${this.zusdGain} }`
+    );
+  }
+
+  /**
+   * Compare to another instance of `ZEROStake`.
+   */
+  equals(that: ZEROStake): boolean {
+    return (
+      this.stakedZERO.eq(that.stakedZERO) &&
+      this.collateralGain.eq(that.collateralGain) &&
+      this.zusdGain.eq(that.zusdGain)
+    );
+  }
+
+  /**
+   * Calculate the difference between this `ZEROStake` and `thatStakedZERO`.
+   *
+   * @returns An object representing the change, or `undefined` if the staked amounts are equal.
+   */
+  whatChanged(thatStakedZERO: Decimalish): ZEROStakeChange<Decimal> | undefined {
+    thatStakedZERO = Decimal.from(thatStakedZERO);
+
+    if (thatStakedZERO.lt(this.stakedZERO)) {
+      return {
+        unstakeZERO: this.stakedZERO.sub(thatStakedZERO),
+        unstakeAllZERO: thatStakedZERO.isZero
+      };
+    }
+
+    if (thatStakedZERO.gt(this.stakedZERO)) {
+      return { stakeZERO: thatStakedZERO.sub(this.stakedZERO) };
+    }
+  }
+
+  /**
+   * Apply a {@link ZEROStakeChange} to this `ZEROStake`.
+   *
+   * @returns The new staked ZERO amount.
+   */
+  apply(change: ZEROStakeChange<Decimalish> | undefined): Decimal {
+    if (!change) {
+      return this.stakedZERO;
+    }
+
+    if (change.unstakeZERO !== undefined) {
+      return change.unstakeAllZERO || this.stakedZERO.lte(change.unstakeZERO)
+        ? Decimal.ZERO
+        : this.stakedZERO.sub(change.unstakeZERO);
+    } else {
+      return this.stakedZERO.add(change.stakeZERO);
+    }
+  }
+}

package/src/_CachedReadableLiquity.ts

@@ -0,0 +1,186 @@
+import { Decimal } from "./Decimal";
+import { Fees } from "./Fees";
+import { ZEROStake } from "./ZEROStake";
+import { StabilityDeposit } from "./StabilityDeposit";
+import { Trove, TroveWithPendingRedistribution, UserTrove } from "./Trove";
+import { FrontendStatus, ReadableLiquity, TroveListingParams } from "./ReadableLiquity";
+
+/** @internal */
+export type _ReadableLiquityWithExtraParamsBase<T extends unknown[]> = {
+  [P in keyof ReadableLiquity]: ReadableLiquity[P] extends (...params: infer A) => infer R
+    ? (...params: [...originalParams: A, ...extraParams: T]) => R
+    : never;
+};
+
+/** @internal */
+export type _LiquityReadCacheBase<T extends unknown[]> = {
+  [P in keyof ReadableLiquity]: ReadableLiquity[P] extends (...args: infer A) => Promise<infer R>
+    ? (...params: [...originalParams: A, ...extraParams: T]) => R | undefined
+    : never;
+};
+
+// Overloads get lost in the mapping, so we need to define them again...
+
+/** @internal */
+export interface _ReadableLiquityWithExtraParams<T extends unknown[]>
+  extends _ReadableLiquityWithExtraParamsBase<T> {
+  getTroves(
+    params: TroveListingParams & { beforeRedistribution: true },
+    ...extraParams: T
+  ): Promise<TroveWithPendingRedistribution[]>;
+
+  getTroves(params: TroveListingParams, ...extraParams: T): Promise<UserTrove[]>;
+}
+
+/** @internal */
+export interface _LiquityReadCache<T extends unknown[]> extends _LiquityReadCacheBase<T> {
+  getTroves(
+    params: TroveListingParams & { beforeRedistribution: true },
+    ...extraParams: T
+  ): TroveWithPendingRedistribution[] | undefined;
+
+  getTroves(params: TroveListingParams, ...extraParams: T): UserTrove[] | undefined;
+}
+
+/** @internal */
+export class _CachedReadableLiquity<T extends unknown[]>
+  implements _ReadableLiquityWithExtraParams<T> {
+  private _readable: _ReadableLiquityWithExtraParams<T>;
+  private _cache: _LiquityReadCache<T>;
+
+  constructor(readable: _ReadableLiquityWithExtraParams<T>, cache: _LiquityReadCache<T>) {
+    this._readable = readable;
+    this._cache = cache;
+  }
+
+  async getTotalRedistributed(...extraParams: T): Promise<Trove> {
+    return (
+      this._cache.getTotalRedistributed(...extraParams) ??
+      this._readable.getTotalRedistributed(...extraParams)
+    );
+  }
+
+  async getTroveBeforeRedistribution(
+    address?: string,
+    ...extraParams: T
+  ): Promise<TroveWithPendingRedistribution> {
+    return (
+      this._cache.getTroveBeforeRedistribution(address, ...extraParams) ??
+      this._readable.getTroveBeforeRedistribution(address, ...extraParams)
+    );
+  }
+
+  async getTrove(address?: string, ...extraParams: T): Promise<UserTrove> {
+    const [troveBeforeRedistribution, totalRedistributed] = await Promise.all([
+      this.getTroveBeforeRedistribution(address, ...extraParams),
+      this.getTotalRedistributed(...extraParams)
+    ]);
+
+    return troveBeforeRedistribution.applyRedistribution(totalRedistributed);
+  }
+
+  async getNumberOfTroves(...extraParams: T): Promise<number> {
+    return (
+      this._cache.getNumberOfTroves(...extraParams) ??
+      this._readable.getNumberOfTroves(...extraParams)
+    );
+  }
+
+  async getPrice(...extraParams: T): Promise<Decimal> {
+    return this._cache.getPrice(...extraParams) ?? this._readable.getPrice(...extraParams);
+  }
+
+  async getTotal(...extraParams: T): Promise<Trove> {
+    return this._cache.getTotal(...extraParams) ?? this._readable.getTotal(...extraParams);
+  }
+
+  async getStabilityDeposit(address?: string, ...extraParams: T): Promise<StabilityDeposit> {
+    return (
+      this._cache.getStabilityDeposit(address, ...extraParams) ??
+      this._readable.getStabilityDeposit(address, ...extraParams)
+    );
+  }
+
+  async getRemainingStabilityPoolZEROReward(...extraParams: T): Promise<Decimal> {
+    return (
+      this._cache.getRemainingStabilityPoolZEROReward(...extraParams) ??
+      this._readable.getRemainingStabilityPoolZEROReward(...extraParams)
+    );
+  }
+
+  async getZUSDInStabilityPool(...extraParams: T): Promise<Decimal> {
+    return (
+      this._cache.getZUSDInStabilityPool(...extraParams) ??
+      this._readable.getZUSDInStabilityPool(...extraParams)
+    );
+  }
+
+  async getZUSDBalance(address?: string, ...extraParams: T): Promise<Decimal> {
+    return (
+      this._cache.getZUSDBalance(address, ...extraParams) ??
+      this._readable.getZUSDBalance(address, ...extraParams)
+    );
+  }
+
+  async getZEROBalance(address?: string, ...extraParams: T): Promise<Decimal> {
+    return (
+      this._cache.getZEROBalance(address, ...extraParams) ??
+      this._readable.getZEROBalance(address, ...extraParams)
+    );
+  }
+
+  async getCollateralSurplusBalance(address?: string, ...extraParams: T): Promise<Decimal> {
+    return (
+      this._cache.getCollateralSurplusBalance(address, ...extraParams) ??
+      this._readable.getCollateralSurplusBalance(address, ...extraParams)
+    );
+  }
+
+  getTroves(
+    params: TroveListingParams & { beforeRedistribution: true },
+    ...extraParams: T
+  ): Promise<TroveWithPendingRedistribution[]>;
+
+  getTroves(params: TroveListingParams, ...extraParams: T): Promise<UserTrove[]>;
+
+  async getTroves(params: TroveListingParams, ...extraParams: T): Promise<UserTrove[]> {
+    const { beforeRedistribution, ...restOfParams } = params;
+
+    const [totalRedistributed, troves] = await Promise.all([
+      beforeRedistribution ? undefined : this.getTotalRedistributed(...extraParams),
+      this._cache.getTroves({ beforeRedistribution: true, ...restOfParams }, ...extraParams) ??
+        this._readable.getTroves({ beforeRedistribution: true, ...restOfParams }, ...extraParams)
+    ]);
+
+    if (totalRedistributed) {
+      return troves.map(trove => trove.applyRedistribution(totalRedistributed));
+    } else {
+      return troves;
+    }
+  }
+
+  async getFees(...extraParams: T): Promise<Fees> {
+    return this._cache.getFees(...extraParams) ?? this._readable.getFees(...extraParams);
+  }
+
+  async getZEROStake(address?: string, ...extraParams: T): Promise<ZEROStake> {
+    return (
+      this._cache.getZEROStake(address, ...extraParams) ??
+      this._readable.getZEROStake(address, ...extraParams)
+    );
+  }
+
+  async getTotalStakedZERO(...extraParams: T): Promise<Decimal> {
+    return (
+      this._cache.getTotalStakedZERO(...extraParams) ??
+      this._readable.getTotalStakedZERO(...extraParams)
+    );
+  }
+
+  async getFrontendStatus(address?: string, ...extraParams: T): Promise<FrontendStatus> {
+    return (
+      this._cache.getFrontendStatus(address, ...extraParams) ??
+      this._readable.getFrontendStatus(address, ...extraParams)
+    );
+  }
+}

package/src/constants.ts

@@ -0,0 +1,68 @@
+import { Decimal } from "./Decimal";
+
+/**
+ * Total collateral ratio below which recovery mode is triggered.
+ *
+ * @public
+ */
+export const CRITICAL_COLLATERAL_RATIO = Decimal.from(1.5);
+
+/**
+ * Collateral ratio below which a Trove can be liquidated in normal mode.
+ *
+ * @public
+ */
+export const MINIMUM_COLLATERAL_RATIO = Decimal.from(1.1);
+
+/**
+ * Amount of ZUSD that's reserved for compensating the liquidator of a Trove.
+ *
+ * @public
+ */
+export const ZUSD_LIQUIDATION_RESERVE = Decimal.from(20);
+
+/**
+ * A Trove must always have at least this much debt on top of the
+ * {@link ZUSD_LIQUIDATION_RESERVE | liquidation reserve}.
+ *
+ * @remarks
+ * Any transaction that would result in a Trove with less net debt than this will be reverted.
+ *
+ * @public
+ */
+export const ZUSD_MINIMUM_NET_DEBT = Decimal.from(180);
+
+/**
+ * A Trove must always have at least this much debt.
+ *
+ * @remarks
+ * Any transaction that would result in a Trove with less debt than this will be reverted.
+ *
+ * @public
+ */
+export const ZUSD_MINIMUM_DEBT = ZUSD_LIQUIDATION_RESERVE.add(ZUSD_MINIMUM_NET_DEBT);
+
+/**
+ * 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.025);
+
+/**
+ * Value that the {@link Fees.borrowingRate | borrowing rate} will never exceed.
+ *
+ * @public
+ */
+export const MAXIMUM_BORROWING_RATE = Decimal.from(0.05);
+
+/**
+ * Value that the {@link Fees.redemptionRate | redemption rate} will never decay below.
+ *
+ * @public
+ */
+export const MINIMUM_REDEMPTION_RATE = Decimal.from(0.025);

package/test/Decimal.test.ts

@@ -0,0 +1,212 @@
+import { describe, it } from "mocha";
+import { expect } from "chai";
+import fc from "fast-check";
+
+import { Decimal, Difference } from "../src/Decimal";
+
+describe("Decimal", () => {
+  describe(".from()", () => {
+    describe("when passing a string", () => {
+      it("should throw if it's empty", () => {
+        expect(() => Decimal.from("")).to.throw("bad decimal format");
+      });
+
+      it("should throw if it's non-numeric", () => {
+        expect(() => Decimal.from("12O")).to.throw("bad decimal format");
+      });
+
+      it("should convert it if it has no decimal point", () => {
+        expect(Decimal.from("123456789123456789123456789").bigNumber)
+          //                                               |<----- 18 ----->|
+          /********/ .to.equal("123456789123456789123456789000000000000000000");
+      });
+
+      it("should convert it if it has decimal point", () => {
+        expect(Decimal.from("123456789123456789.123456789").bigNumber)
+          //                                       |<----- 18 ----->|
+          /*********/ .to.equal("123456789123456789123456789000000000");
+      });
+
+      it("should convert it if characteristic is missing", () => {
+        expect(Decimal.from(".123456789").bigNumber)
+          //                     |<----- 18 ----->|
+          /*********/ .to.equal("123456789000000000");
+      });
+
+      it("should convert it if mantissa is missing", () => {
+        expect(Decimal.from("123456789.").bigNumber)
+          //                             |<----- 18 ----->|
+          /********/ .to.equal("123456789000000000000000000");
+      });
+
+      it("should truncate if mantissa is too long", () => {
+        expect(Decimal.from("1.123456789123456789123456789").bigNumber)
+          //                      |<----- 18 ----->|
+          /*********/ .to.equal("1123456789123456789");
+      });
+
+      describe("in scientific notation", () => {
+        it("should convert it if exponent has no sign", () => {
+          expect(Decimal.from("1.23456789e7").bigNumber)
+            //                      |<-7->||<----- 18 ----->|
+            /*********/ .to.equal("12345678900000000000000000");
+        });
+
+        it("should convert it if exponent has '+' sign", () => {
+          expect(Decimal.from("1.23456789e+9").bigNumber)
+            //                      |<- 9 ->||<----- 18 ----->|
+            /*********/ .to.equal("1234567890000000000000000000");
+        });
+
+        it("should convert it if exponent has '-' sign", () => {
+          expect(Decimal.from("123456789.123456789e-10").bigNumber)
+            //                              |<- 8->|
+            /*********/ .to.equal("12345678912345678");
+        });
+      });
+    });
+
+    describe("when passing a number", () => {
+      it("should preserve fractional part", () => {
+        expect(Decimal.from(1.23456789).bigNumber)
+          //                     |<----- 18 ----->|
+          /********/ .to.equal("1234567890000000000");
+      });
+
+      it("should convert it even if it's very small", () => {
+        expect(Decimal.from(1e-15).bigNumber).to.equal("1000");
+      });
+
+      it("should convert it even if it's very large", () => {
+        expect(Decimal.from(1e25).bigNumber)
+          //          |<--------- 25 -------->||<----- 18 ----->|
+          .to.equal("10000000000000000000000000000000000000000000");
+      });
+    });
+
+    describe("when passing a Decimal", () => {
+      it("should return the same Decimal", () => {
+        const decimal = Decimal.from("123456789");
+        expect(Decimal.from(decimal)).to.equal(decimal);
+      });
+    });
+  });
+
+  describe(".toString()", () => {
+    describe("when not passing a parameter", () => {
+      it("should not include '.' for integers", () => {
+        expect(Decimal.fromBigNumberString("123456789000000000000000000").toString())
+          //                                      |<----- 18 ----->|
+          /*****************/ .to.equal("123456789");
+      });
+
+      it("should include '.' for fractions", () => {
+        expect(Decimal.fromBigNumberString("123456789000000000123456789").toString())
+          //                                      |<----- 18 ----->|
+          /****************/ .to.equal("123456789.000000000123456789");
+      });
+
+      it("should trim trailing zeros from fractions", () => {
+        expect(Decimal.fromBigNumberString("123456789123456789000000000").toString())
+          //                                      |<----- 18 ----->|
+          /****************/ .to.equal("123456789.123456789");
+      });
+    });
+
+    describe("when passing a precision parameter", () => {
+      it("should round to the nearest decimal", () => {
+        expect(Decimal.fromBigNumberString("123456789000499999999999999").toString(3))
+          //                                      |<----- 18 ----->|
+          /****************/ .to.equal("123456789.000");
+
+        expect(Decimal.fromBigNumberString("123456789000500000000000000").toString(3))
+          //                                      |<----- 18 ----->|
+          /****************/ .to.equal("123456789.001");
+      });
+
+      it("should include '.' and decimal zeros for integers if precision is >0", () => {
+        expect(Decimal.fromBigNumberString("123456789000000000000000000").toString(2))
+          //                                      |<----- 18 ----->|
+          /****************/ .to.equal("123456789.00");
+      });
+
+      it("should not include '.' if precision is 0", () => {
+        expect(Decimal.fromBigNumberString("123456789123456789123456789").toString(0))
+          //                                      |<----- 18 ----->|
+          /*****************/ .to.equal("123456789");
+      });
+    });
+  });
+
+  describe(".shorten()", () => {
+    const cases = [
+      ["0.123", "0.12"],
+      ["1.234", "1.23"],
+      ["12.345", "12.3"],
+      ["123.456", "123"],
+      ["1234.567", "1.23K"],
+      ["12345.678", "12.3K"],
+      ["123456.789", "123K"],
+      ["1234567.891", "1.23M"],
+      ["12345678.912", "12.3M"],
+      ["123456789.123", "123M"],
+      ["1234567891.234", "1.23B"],
+      ["12345678912.345", "12.3B"],
+      ["123456789123.456", "123B"],
+      ["1234567891234.567", "1.23T"],
+      ["12345678912345.678", "12.3T"],
+      ["123456789123456.789", "123T"],
+      ["1234567891234567.891", "1,235T"],
+      ["12345678912345678.912", "12,346T"],
+      ["123456789123456789.123", "123,457T"],
+      ["1234567891234567891.234", "1,234,568T"]
+    ];
+
+    for (const [input, expectedOutput] of cases) {
+      it(`should turn '${input}' into '${expectedOutput}'`, () => {
+        expect(Decimal.from(input).shorten()).to.equal(expectedOutput);
+      });
+    }
+  });
+
+  describe(".mul()", () => {
+    it("should multiply", () => {
+      expect(Decimal.from(2).mul(3).toString()).to.equal("6");
+    });
+  });
+
+  describe(".div()", () => {
+    it("should divide", () => {
+      expect(Decimal.from(3).div(2).toString()).to.equal("1.5");
+    });
+  });
+
+  describe(".mulDiv()", () => {
+    it("should multiply then divide", () => {
+      expect(Decimal.from(2).mulDiv(3, 2).toString()).to.equal("3");
+    });
+  });
+
+  describe(".pow()", () => {
+    it("should be roughly the same as Math.pow()", () => {
+      fc.assert(
+        fc.property(
+          fc.float(),
+          fc.integer({ min: 0, max: 0xffffffff }),
+          (x, y) =>
+            !!Difference.between(Math.pow(x, y), Decimal.from(x).pow(y)).absoluteValue?.lt(1e-9)
+        )
+      );
+    });
+  });
+
+  describe(".isZero", () => {
+    it("should be true if Decimal is zero", () => {
+      expect(Decimal.from("0.0").isZero).to.be.true;
+    });
+
+    it("should be false if Decimal is non-zero", () => {
+      expect(Decimal.from("0.1").isZero).to.be.false;
+    });
+  });
+});

package/test/StabilityDeposit.test.ts

@@ -0,0 +1,30 @@
+import { describe, it } from "mocha";
+import fc from "fast-check";
+
+import { Decimal } from "../src/Decimal";
+import { StabilityDeposit } from "../src/StabilityDeposit";
+
+const arbitraryDeposit = () =>
+  fc
+    .tuple(fc.float(), fc.float(), fc.float(), fc.float())
+    .filter(([initialZUSD, currentZUSD]) => initialZUSD >= currentZUSD)
+    .map(
+      ([a, b, c, d]) =>
+        new StabilityDeposit(Decimal.from(a), Decimal.from(b), Decimal.from(c), Decimal.from(d), "")
+    );
+
+const nonZeroDeposit = () => arbitraryDeposit().filter(({ currentZUSD }) => !currentZUSD.isZero);
+
+describe("StabilityDeposit", () => {
+  it("applying diff of `b` from `a` to `a` should always yield `b`", () => {
+    fc.assert(
+      fc.property(arbitraryDeposit(), fc.float(), (a, b) => a.apply(a.whatChanged(b)).eq(b))
+    );
+  });
+
+  it("applying what changed should preserve zeroing", () => {
+    fc.assert(
+      fc.property(arbitraryDeposit(), nonZeroDeposit(), (a, b) => a.apply(b.whatChanged(0)).eq(0))
+    );
+  });
+});