@morpho-org/blue-sdk 3.0.3 → 3.0.5

package/lib/market/Market.d.ts

@@ -104,21 +104,63 @@ export declare class Market implements IMarket {
     /**
      * Returns the rate at which interest accrued for suppliers of this market,
      * since the last time the market was updated (scaled by WAD).
+     * @deprecated There's no such thing as a supply rate in Morpho. Only the supply APY is meaningful.
      */
     get supplyRate(): bigint;
     /**
-     * Returns the rate at which interest accrued for borrowers of this market,
-     * since the last time the market was updated (scaled by WAD).
+     * Returns the average rate at which interest _would_ accrue from `lastUpdate`
+     * till now, if `accrueInterest` was called immediately onchain (scaled by WAD).
+     * If `accrueInterest` was just called, the average rate equals the instantaneous rate,
+     * so it is equivalent to `getBorrowRate(lastUpdate)`.
+     *
+     * In most cases, `accrueInterest` will not be called immediately onchain, so the
+     * average rate doesn't correspond to anything "real".
+     *
+     * If interested in the instantaneous rate experienced by existing market actors at a specific timestamp,
+     * use `getBorrowRate(timestamp)`, `getBorrowApy(timestamp)`, or `getSupplyApy(timestamp)` instead.
      */
     get borrowRate(): bigint;
     /**
-     * The market's supply-side Annual Percentage Yield (APY) (scaled by WAD).
+     * The market's current, instantaneous supply-side Annual Percentage Yield (APY) (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getSupplyApy(timestamp)` instead.
      */
     get supplyApy(): bigint;
     /**
-     * The market's borrow-side Annual Percentage Yield (APY) (scaled by WAD).
+     * The market's current, instantaneous borrow-side Annual Percentage Yield (APY) (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getBorrowApy(timestamp)` instead.
      */
     get borrowApy(): bigint;
+    /**
+     * Returns the instantaneous rate at which interest accrues for borrowers of this market,
+     * at the given timestamp, if the state remains unchanged (not accrued) (scaled by WAD).
+     * It is fundamentally different from the rate at which interest is paid by borrowers to lenders in the case of an interest accrual,
+     * as in the case of the AdaptiveCurveIRM, the (approximated) average rate since the last update is used instead.
+     * @param timestamp The timestamp at which to calculate the borrow rate. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current borrow rate).
+     */
+    getBorrowRate(timestamp?: BigIntish): bigint;
+    /**
+     * Returns the rate at which interest accrues for borrowers of this market,
+     * at the given timestamp, if the state remains unchanged (not accrued) (scaled by WAD).
+     * @param timestamp The timestamp at which to calculate the accrual borrow rate. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current borrow rate).
+     */
+    protected getAccrualBorrowRate(timestamp?: BigIntish): {
+        elapsed: bigint;
+        avgBorrowRate: bigint;
+        endBorrowRate: bigint;
+        endRateAtTarget?: bigint;
+    };
+    /**
+     * The market's instantaneous borrow-side Annual Percentage Yield (APY) at the given timestamp,
+     * if the state remains unchanged (not accrued) (scaled by WAD).
+     * @param timestamp The timestamp at which to calculate the borrow APY. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current borrow APY).
+     */
+    getBorrowApy(timestamp?: BigIntish): bigint;
+    /**
+     * The market's instantaneous supply-side Annual Percentage Yield (APY) at the given timestamp,
+     * if the state remains unchanged (not accrued) (scaled by WAD).
+     * @param timestamp The timestamp at which to calculate the supply APY. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current supply APY).
+     */
+    getSupplyApy(timestamp?: BigIntish): bigint;
     /**
      * Returns a new market derived from this market, whose interest has been accrued up to the given timestamp.
      * @param timestamp The timestamp at which to accrue interest. Must be greater than or equal to `lastUpdate`. Defaults to `lastUpdate` (returns a copy of the market).

package/lib/market/Market.js

@@ -103,57 +103,111 @@ class Market {
     /**
      * Returns the rate at which interest accrued for suppliers of this market,
      * since the last time the market was updated (scaled by WAD).
+     * @deprecated There's no such thing as a supply rate in Morpho. Only the supply APY is meaningful.
      */
     get supplyRate() {
         return MarketUtils_js_1.MarketUtils.getSupplyRate(this.borrowRate, this);
     }
     /**
-     * Returns the rate at which interest accrued for borrowers of this market,
-     * since the last time the market was updated (scaled by WAD).
+     * Returns the average rate at which interest _would_ accrue from `lastUpdate`
+     * till now, if `accrueInterest` was called immediately onchain (scaled by WAD).
+     * If `accrueInterest` was just called, the average rate equals the instantaneous rate,
+     * so it is equivalent to `getBorrowRate(lastUpdate)`.
+     *
+     * In most cases, `accrueInterest` will not be called immediately onchain, so the
+     * average rate doesn't correspond to anything "real".
+     *
+     * If interested in the instantaneous rate experienced by existing market actors at a specific timestamp,
+     * use `getBorrowRate(timestamp)`, `getBorrowApy(timestamp)`, or `getSupplyApy(timestamp)` instead.
      */
     get borrowRate() {
-        if (this.rateAtTarget == null)
-            return 0n;
-        return index_js_1.AdaptiveCurveIrmLib.getBorrowRate(this.utilization, this.rateAtTarget, 0n).avgBorrowRate;
+        return this.getAccrualBorrowRate().avgBorrowRate;
     }
     /**
-     * The market's supply-side Annual Percentage Yield (APY) (scaled by WAD).
+     * The market's current, instantaneous supply-side Annual Percentage Yield (APY) (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getSupplyApy(timestamp)` instead.
      */
     get supplyApy() {
-        return MarketUtils_js_1.MarketUtils.compoundRate(this.supplyRate);
+        return this.getSupplyApy();
     }
     /**
-     * The market's borrow-side Annual Percentage Yield (APY) (scaled by WAD).
+     * The market's current, instantaneous borrow-side Annual Percentage Yield (APY) (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getBorrowApy(timestamp)` instead.
      */
     get borrowApy() {
-        return MarketUtils_js_1.MarketUtils.compoundRate(this.borrowRate);
+        return this.getBorrowApy();
     }
     /**
-     * Returns a new market derived from this market, whose interest has been accrued up to the given timestamp.
-     * @param timestamp The timestamp at which to accrue interest. Must be greater than or equal to `lastUpdate`. Defaults to `lastUpdate` (returns a copy of the market).
+     * Returns the instantaneous rate at which interest accrues for borrowers of this market,
+     * at the given timestamp, if the state remains unchanged (not accrued) (scaled by WAD).
+     * It is fundamentally different from the rate at which interest is paid by borrowers to lenders in the case of an interest accrual,
+     * as in the case of the AdaptiveCurveIRM, the (approximated) average rate since the last update is used instead.
+     * @param timestamp The timestamp at which to calculate the borrow rate. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current borrow rate).
      */
-    accrueInterest(timestamp = this.lastUpdate) {
+    getBorrowRate(timestamp = morpho_ts_1.Time.timestamp()) {
+        if (this.rateAtTarget == null)
+            return 0n;
         timestamp = BigInt(timestamp);
         const elapsed = timestamp - this.lastUpdate;
         if (elapsed < 0n)
             throw new errors_js_1.BlueErrors.InvalidInterestAccrual(this.id, timestamp, this.lastUpdate);
-        if (elapsed === 0n)
-            return new Market(this);
-        let borrowRate = 0n;
-        let { rateAtTarget } = this;
-        if (rateAtTarget != null) {
-            const { avgBorrowRate, endRateAtTarget } = index_js_1.AdaptiveCurveIrmLib.getBorrowRate(this.utilization, rateAtTarget, elapsed);
-            borrowRate = avgBorrowRate;
-            rateAtTarget = endRateAtTarget;
-        }
-        const { interest, feeShares } = MarketUtils_js_1.MarketUtils.getAccruedInterest(borrowRate, this, elapsed);
+        const { endBorrowRate } = index_js_1.AdaptiveCurveIrmLib.getBorrowRate(this.utilization, this.rateAtTarget, elapsed);
+        return endBorrowRate;
+    }
+    /**
+     * Returns the rate at which interest accrues for borrowers of this market,
+     * at the given timestamp, if the state remains unchanged (not accrued) (scaled by WAD).
+     * @param timestamp The timestamp at which to calculate the accrual borrow rate. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current borrow rate).
+     */
+    getAccrualBorrowRate(timestamp = morpho_ts_1.Time.timestamp()) {
+        timestamp = BigInt(timestamp);
+        const elapsed = timestamp - this.lastUpdate;
+        if (elapsed < 0n)
+            throw new errors_js_1.BlueErrors.InvalidInterestAccrual(this.id, timestamp, this.lastUpdate);
+        if (this.rateAtTarget == null)
+            return {
+                elapsed,
+                avgBorrowRate: 0n,
+                endBorrowRate: 0n,
+            };
+        return {
+            elapsed,
+            ...index_js_1.AdaptiveCurveIrmLib.getBorrowRate(this.utilization, this.rateAtTarget, elapsed),
+        };
+    }
+    /**
+     * The market's instantaneous borrow-side Annual Percentage Yield (APY) at the given timestamp,
+     * if the state remains unchanged (not accrued) (scaled by WAD).
+     * @param timestamp The timestamp at which to calculate the borrow APY. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current borrow APY).
+     */
+    getBorrowApy(timestamp = morpho_ts_1.Time.timestamp()) {
+        const borrowRate = this.getBorrowRate(timestamp);
+        return MarketUtils_js_1.MarketUtils.compoundRate(borrowRate);
+    }
+    /**
+     * The market's instantaneous supply-side Annual Percentage Yield (APY) at the given timestamp,
+     * if the state remains unchanged (not accrued) (scaled by WAD).
+     * @param timestamp The timestamp at which to calculate the supply APY. Must be greater than or equal to `lastUpdate`. Defaults to `Time.timestamp()` (returns the current supply APY).
+     */
+    getSupplyApy(timestamp = morpho_ts_1.Time.timestamp()) {
+        const borrowApy = this.getBorrowApy(timestamp);
+        return index_js_1.MathLib.wMulUp(index_js_1.MathLib.wMulDown(borrowApy, this.utilization), index_js_1.MathLib.WAD - this.fee);
+    }
+    /**
+     * Returns a new market derived from this market, whose interest has been accrued up to the given timestamp.
+     * @param timestamp The timestamp at which to accrue interest. Must be greater than or equal to `lastUpdate`. Defaults to `lastUpdate` (returns a copy of the market).
+     */
+    accrueInterest(timestamp = this.lastUpdate) {
+        timestamp = BigInt(timestamp);
+        const { elapsed, avgBorrowRate, endRateAtTarget } = this.getAccrualBorrowRate(timestamp);
+        const { interest, feeShares } = MarketUtils_js_1.MarketUtils.getAccruedInterest(avgBorrowRate, this, elapsed);
         return new Market({
             ...this,
             totalSupplyAssets: this.totalSupplyAssets + interest,
             totalBorrowAssets: this.totalBorrowAssets + interest,
             totalSupplyShares: this.totalSupplyShares + feeShares,
             lastUpdate: timestamp,
-            rateAtTarget,
+            rateAtTarget: endRateAtTarget,
         });
     }
     supply(assets, shares, timestamp) {

package/lib/market/MarketUtils.d.ts

@@ -30,6 +30,7 @@ export declare namespace MarketUtils {
      * since the last time the market was updated (scaled by WAD).
      * @param borrowRate The average borrow rate since the last market update (scaled by WAD).
      * @param market The market state.
+     * @deprecated There's no such thing as a supply rate in Morpho. Only the supply APY is meaningful.
      */
     function getSupplyRate(borrowRate: BigIntish, { utilization, fee }: {
         utilization: BigIntish;

package/lib/market/MarketUtils.js

@@ -54,6 +54,7 @@ var MarketUtils;
      * since the last time the market was updated (scaled by WAD).
      * @param borrowRate The average borrow rate since the last market update (scaled by WAD).
      * @param market The market state.
+     * @deprecated There's no such thing as a supply rate in Morpho. Only the supply APY is meaningful.
      */
     function getSupplyRate(borrowRate, { utilization, fee }) {
         const borrowRateWithoutFees = index_js_1.MathLib.wMulUp(borrowRate, utilization);

package/lib/math/AdaptiveCurveIrmLib.d.ts

@@ -33,6 +33,7 @@ export declare namespace AdaptiveCurveIrmLib {
     function wExp(x: BigIntish): bigint;
     function getBorrowRate(startUtilization: BigIntish, startRateAtTarget: BigIntish, elapsed: BigIntish): {
         avgBorrowRate: bigint;
+        endBorrowRate: bigint;
         endRateAtTarget: bigint;
     };
     function getUtilizationAtBorrowRate(borrowRate: BigIntish, rateAtTarget: BigIntish): bigint;

package/lib/math/AdaptiveCurveIrmLib.js

@@ -109,9 +109,11 @@ var AdaptiveCurveIrmLib;
         const coeff = err < 0
             ? MathLib_js_1.MathLib.WAD - MathLib_js_1.MathLib.wDivDown(MathLib_js_1.MathLib.WAD, AdaptiveCurveIrmLib.CURVE_STEEPNESS)
             : AdaptiveCurveIrmLib.CURVE_STEEPNESS - MathLib_js_1.MathLib.WAD;
+        const _curve = (rateAtTarget) => MathLib_js_1.MathLib.wMulDown(MathLib_js_1.MathLib.wMulDown(coeff, err) + MathLib_js_1.MathLib.WAD, rateAtTarget);
         // Non negative if avgRateAtTarget >= 0 because if err < 0, coeff <= 1.
         return {
-            avgBorrowRate: MathLib_js_1.MathLib.wMulDown(MathLib_js_1.MathLib.wMulDown(coeff, err) + MathLib_js_1.MathLib.WAD, avgRateAtTarget),
+            avgBorrowRate: _curve(avgRateAtTarget),
+            endBorrowRate: _curve(endRateAtTarget),
             endRateAtTarget,
         };
     }

package/lib/vault/Vault.d.ts

@@ -148,13 +148,29 @@ export declare class AccrualVault extends Vault implements IAccrualVault {
      */
     get liquidity(): bigint;
     /**
-     * The MetaMorpho vault's APY on its assets averaged over its market deposits, before deducting the performance fee.
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * before deducting the performance fee, at the time of each market's last update (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getApy(timestamp)` instead.
      */
     get apy(): bigint;
     /**
-     * The MetaMorpho vault's APY on its assets averaged over its market deposits, after deducting the performance fee.
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * after deducting the performance fee, at the time of each market's last update (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getApy(timestamp)` instead.
      */
     get netApy(): bigint;
+    /**
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * before deducting the performance fee, at the given timestamp,
+     * if the state of all the markets remains unchanged (not accrued) (scaled by WAD).
+     */
+    getApy(timestamp: BigIntish): bigint;
+    /**
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * after deducting the performance fee, at the given timestamp,
+     * if the state of all the markets remains unchanged (not accrued) (scaled by WAD).
+     */
+    getNetApy(timestamp: BigIntish): bigint;
     getAllocationProportion(marketId: MarketId): bigint;
     getDepositCapacityLimit(assets: bigint): CapacityLimit;
     getWithdrawCapacityLimit(shares: bigint): CapacityLimit;

package/lib/vault/Vault.js

@@ -153,7 +153,9 @@ class AccrualVault extends Vault {
             .reduce((total, { position }) => total + position.withdrawCapacityLimit.value, 0n);
     }
     /**
-     * The MetaMorpho vault's APY on its assets averaged over its market deposits, before deducting the performance fee.
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * before deducting the performance fee, at the time of each market's last update (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getApy(timestamp)` instead.
      */
     get apy() {
         if (this.totalAssets === 0n)
@@ -163,11 +165,34 @@ class AccrualVault extends Vault {
             .reduce((total, { position }) => total + position.market.supplyApy * position.supplyAssets, 0n) / this.totalAssets);
     }
     /**
-     * The MetaMorpho vault's APY on its assets averaged over its market deposits, after deducting the performance fee.
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * after deducting the performance fee, at the time of each market's last update (scaled by WAD).
+     * If interested in the APY at a specific timestamp, use `getApy(timestamp)` instead.
      */
     get netApy() {
         return index_js_2.MathLib.wMulDown(this.apy, index_js_2.MathLib.WAD - this.fee);
     }
+    /**
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * before deducting the performance fee, at the given timestamp,
+     * if the state of all the markets remains unchanged (not accrued) (scaled by WAD).
+     */
+    getApy(timestamp) {
+        if (this.totalAssets === 0n)
+            return 0n;
+        return (this.allocations
+            .values()
+            .reduce((total, { position }) => total +
+            position.market.getSupplyApy(timestamp) * position.supplyAssets, 0n) / this.totalAssets);
+    }
+    /**
+     * The MetaMorpho vault's APY on its assets averaged over its market deposits,
+     * after deducting the performance fee, at the given timestamp,
+     * if the state of all the markets remains unchanged (not accrued) (scaled by WAD).
+     */
+    getNetApy(timestamp) {
+        return index_js_2.MathLib.wMulDown(this.getApy(timestamp), index_js_2.MathLib.WAD - this.fee);
+    }
     getAllocationProportion(marketId) {
         if (this.totalAssets === 0n)
             return 0n;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morpho-org/blue-sdk",
   "description": "Framework-agnostic package that defines Morpho-related entity classes (such as `Market`, `Token`, `Vault`).",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "author": "Morpho Association <contact@morpho.org>",
   "contributors": [
     "Rubilmax <rmilon@gmail.com>"