@morpho-org/midnight-sdk 0.1.0

package/lib/esm/market/Position.js

@@ -0,0 +1,420 @@
+import { MathLib } from "@morpho-org/morpho-ts";
+import { Market } from "./Market.js";
+import { PositionUtils } from "./PositionUtils.js";
+/**
+ * Midnight user position as stored by the core contract.
+ *
+ * @example
+ * ```ts
+ * import { Position } from "@morpho-org/midnight-sdk";
+ *
+ * const position = new Position({
+ *   credit: 0n,
+ *   pendingFee: 0n,
+ *   lastLossFactor: 0n,
+ *   lastAccrual: 0n,
+ *   debt: 0n,
+ *   collateralBitmap: 0n,
+ *   collateral: [],
+ * });
+ * console.log(position.debt);
+ * ```
+ */
+export class Position {
+    /** User credit. */
+    credit;
+    /** Pending continuous fee. */
+    pendingFee;
+    /** Last loss factor seen by the position. */
+    lastLossFactor;
+    /** Last accrual timestamp. */
+    lastAccrual;
+    /** User debt. */
+    debt;
+    /** Collateral bitmap. */
+    collateralBitmap;
+    /** Collateral balances by index. */
+    collateral;
+    constructor(position) {
+        this.credit = BigInt(position.credit);
+        this.pendingFee = BigInt(position.pendingFee);
+        this.lastLossFactor = BigInt(position.lastLossFactor);
+        this.lastAccrual = BigInt(position.lastAccrual);
+        this.debt = BigInt(position.debt);
+        this.collateralBitmap = BigInt(position.collateralBitmap);
+        this.collateral = position.collateral.map((assets) => BigInt(assets));
+    }
+    /**
+     * Returns credit net of pending fee, floored to zero for invalid raw inputs.
+     *
+     * @returns Credit minus pending fee.
+     * @example
+     * ```ts
+     * import { Position } from "@morpho-org/midnight-sdk";
+     *
+     * const position = new Position({
+     *   credit: 1_000n,
+     *   pendingFee: 100n,
+     *   lastLossFactor: 0n,
+     *   lastAccrual: 0n,
+     *   debt: 0n,
+     *   collateralBitmap: 1n,
+     *   collateral: [50n],
+     * });
+     * console.log(position.faceValue);
+     * ```
+     */
+    get faceValue() {
+        return MathLib.zeroFloorSub(this.credit, this.pendingFee);
+    }
+}
+/**
+ * Midnight position paired with its hydrated market.
+ *
+ * @example
+ * ```ts
+ * import { registerCustomAddresses } from "@morpho-org/morpho-ts";
+ * import { AccrualPosition } from "@morpho-org/midnight-sdk";
+ *
+ * registerCustomAddresses({
+ *   addresses: {
+ *     31337: {
+ *       morpho: "0x0000000000000000000000000000000000000001",
+ *       bundler3: {
+ *         bundler3: "0x0000000000000000000000000000000000000002",
+ *         generalAdapter1: "0x0000000000000000000000000000000000000003",
+ *       },
+ *       adaptiveCurveIrm: "0x0000000000000000000000000000000000000004",
+ *       midnight: "0x0000000000000000000000000000000000001000",
+ *     },
+ *   },
+ * });
+ *
+ * const position = new AccrualPosition(
+ *   {
+ *     credit: 1_000n,
+ *     pendingFee: 100n,
+ *     lastLossFactor: 0n,
+ *     lastAccrual: 1_000n,
+ *     debt: 0n,
+ *     collateralBitmap: 1n,
+ *     collateral: [50n],
+ *   },
+ *   {
+ *     chainId: 31337,
+ *     params: {
+ *       loanToken: "0x0000000000000000000000000000000000006000",
+ *       collateralParams: [
+ *         {
+ *           token: "0x0000000000000000000000000000000000007000",
+ *           lltv: 770000000000000000n,
+ *           maxLif: 1061007957559681697n,
+ *           oracle: "0x0000000000000000000000000000000000008000",
+ *         },
+ *       ],
+ *       maturity: 54_000n,
+ *       rcfThreshold: 0n,
+ *       enterGate: "0x0000000000000000000000000000000000000000",
+ *       liquidatorGate: "0x0000000000000000000000000000000000000000",
+ *     },
+ *     totalUnits: 1_000n,
+ *     lossFactor: 0n,
+ *     withdrawable: 500n,
+ *     continuousFeeCredit: 0n,
+ *     settlementFeeCbps: [1, 2, 3, 4, 5, 6, 7],
+ *     continuousFee: 10,
+ *     tickSpacing: 4,
+ *   },
+ * );
+ * console.log(position.market.id);
+ * ```
+ */
+export class AccrualPosition extends Position {
+    /** Hydrated market for this position. */
+    market;
+    constructor(position, market) {
+        super(position);
+        this.market = market instanceof Market ? market : new Market(market);
+    }
+    /**
+     * Returns the position collateral balance at an index configured by the market.
+     *
+     * @param index - Collateral index.
+     * @returns Collateral balance, or undefined when the index is not configured.
+     * @example
+     * ```ts
+     * import { registerCustomAddresses } from "@morpho-org/morpho-ts";
+     * import { AccrualPosition } from "@morpho-org/midnight-sdk";
+     *
+     * registerCustomAddresses({
+     *   addresses: {
+     *     31337: {
+     *       morpho: "0x0000000000000000000000000000000000000001",
+     *       bundler3: {
+     *         bundler3: "0x0000000000000000000000000000000000000002",
+     *         generalAdapter1: "0x0000000000000000000000000000000000000003",
+     *       },
+     *       adaptiveCurveIrm: "0x0000000000000000000000000000000000000004",
+     *       midnight: "0x0000000000000000000000000000000000001000",
+     *     },
+     *   },
+     * });
+     *
+     * const position = new AccrualPosition(
+     *   {
+     *     credit: 1_000n,
+     *     pendingFee: 100n,
+     *     lastLossFactor: 0n,
+     *     lastAccrual: 1_000n,
+     *     debt: 0n,
+     *     collateralBitmap: 1n,
+     *     collateral: [50n],
+     *   },
+     *   {
+     *     chainId: 31337,
+     *     params: {
+     *       loanToken: "0x0000000000000000000000000000000000006000",
+     *       collateralParams: [
+     *         {
+     *           token: "0x0000000000000000000000000000000000007000",
+     *           lltv: 770000000000000000n,
+     *           maxLif: 1061007957559681697n,
+     *           oracle: "0x0000000000000000000000000000000000008000",
+     *         },
+     *       ],
+     *       maturity: 54_000n,
+     *       rcfThreshold: 0n,
+     *       enterGate: "0x0000000000000000000000000000000000000000",
+     *       liquidatorGate: "0x0000000000000000000000000000000000000000",
+     *     },
+     *     totalUnits: 1_000n,
+     *     lossFactor: 0n,
+     *     withdrawable: 500n,
+     *     continuousFeeCredit: 0n,
+     *     settlementFeeCbps: [1, 2, 3, 4, 5, 6, 7],
+     *     continuousFee: 10,
+     *     tickSpacing: 4,
+     *   },
+     * );
+     * const balance = position.getCollateralBalanceByIndex(0);
+     * console.log(balance);
+     * ```
+     */
+    getCollateralBalanceByIndex(index) {
+        const normalizedIndex = BigInt(index);
+        if (this.market.getCollateralParamsByIndex(normalizedIndex) == null)
+            return undefined;
+        return this.collateral[Number(normalizedIndex)] ?? 0n;
+    }
+    /**
+     * Returns the position collateral balance for a configured token.
+     *
+     * @param token - Collateral token address.
+     * @returns Collateral balance, or undefined when the token is not configured.
+     * @example
+     * ```ts
+     * import { registerCustomAddresses } from "@morpho-org/morpho-ts";
+     * import { AccrualPosition } from "@morpho-org/midnight-sdk";
+     *
+     * registerCustomAddresses({
+     *   addresses: {
+     *     31337: {
+     *       morpho: "0x0000000000000000000000000000000000000001",
+     *       bundler3: {
+     *         bundler3: "0x0000000000000000000000000000000000000002",
+     *         generalAdapter1: "0x0000000000000000000000000000000000000003",
+     *       },
+     *       adaptiveCurveIrm: "0x0000000000000000000000000000000000000004",
+     *       midnight: "0x0000000000000000000000000000000000001000",
+     *     },
+     *   },
+     * });
+     *
+     * const collateralToken = "0x0000000000000000000000000000000000007000";
+     * const position = new AccrualPosition(
+     *   {
+     *     credit: 1_000n,
+     *     pendingFee: 100n,
+     *     lastLossFactor: 0n,
+     *     lastAccrual: 1_000n,
+     *     debt: 0n,
+     *     collateralBitmap: 1n,
+     *     collateral: [50n],
+     *   },
+     *   {
+     *     chainId: 31337,
+     *     params: {
+     *       loanToken: "0x0000000000000000000000000000000000006000",
+     *       collateralParams: [
+     *         {
+     *           token: collateralToken,
+     *           lltv: 770000000000000000n,
+     *           maxLif: 1061007957559681697n,
+     *           oracle: "0x0000000000000000000000000000000000008000",
+     *         },
+     *       ],
+     *       maturity: 54_000n,
+     *       rcfThreshold: 0n,
+     *       enterGate: "0x0000000000000000000000000000000000000000",
+     *       liquidatorGate: "0x0000000000000000000000000000000000000000",
+     *     },
+     *     totalUnits: 1_000n,
+     *     lossFactor: 0n,
+     *     withdrawable: 500n,
+     *     continuousFeeCredit: 0n,
+     *     settlementFeeCbps: [1, 2, 3, 4, 5, 6, 7],
+     *     continuousFee: 10,
+     *     tickSpacing: 4,
+     *   },
+     * );
+     * const balance = position.getCollateralBalanceByToken(collateralToken);
+     * console.log(balance);
+     * ```
+     */
+    getCollateralBalanceByToken(token) {
+        const index = this.market.getCollateralIndexByToken(token);
+        return index == null ? undefined : this.getCollateralBalanceByIndex(index);
+    }
+    /**
+     * Returns the market settlement fee at a timestamp.
+     *
+     * @param timestamp - Timestamp used to compute time to maturity.
+     * @returns WAD-scaled settlement fee.
+     * @example
+     * ```ts
+     * import { registerCustomAddresses } from "@morpho-org/morpho-ts";
+     * import { AccrualPosition } from "@morpho-org/midnight-sdk";
+     *
+     * registerCustomAddresses({
+     *   addresses: {
+     *     31337: {
+     *       morpho: "0x0000000000000000000000000000000000000001",
+     *       bundler3: {
+     *         bundler3: "0x0000000000000000000000000000000000000002",
+     *         generalAdapter1: "0x0000000000000000000000000000000000000003",
+     *       },
+     *       adaptiveCurveIrm: "0x0000000000000000000000000000000000000004",
+     *       midnight: "0x0000000000000000000000000000000000001000",
+     *     },
+     *   },
+     * });
+     *
+     * const position = new AccrualPosition(
+     *   {
+     *     credit: 1_000n,
+     *     pendingFee: 100n,
+     *     lastLossFactor: 0n,
+     *     lastAccrual: 1_000n,
+     *     debt: 0n,
+     *     collateralBitmap: 1n,
+     *     collateral: [50n],
+     *   },
+     *   {
+     *     chainId: 31337,
+     *     params: {
+     *       loanToken: "0x0000000000000000000000000000000000006000",
+     *       collateralParams: [
+     *         {
+     *           token: "0x0000000000000000000000000000000000007000",
+     *           lltv: 770000000000000000n,
+     *           maxLif: 1061007957559681697n,
+     *           oracle: "0x0000000000000000000000000000000000008000",
+     *         },
+     *       ],
+     *       maturity: 54_000n,
+     *       rcfThreshold: 0n,
+     *       enterGate: "0x0000000000000000000000000000000000000000",
+     *       liquidatorGate: "0x0000000000000000000000000000000000000000",
+     *     },
+     *     totalUnits: 1_000n,
+     *     lossFactor: 0n,
+     *     withdrawable: 500n,
+     *     continuousFeeCredit: 0n,
+     *     settlementFeeCbps: [1, 2, 3, 4, 5, 6, 7],
+     *     continuousFee: 10,
+     *     tickSpacing: 4,
+     *   },
+     * );
+     * const fee = position.getSettlementFee(0n);
+     * console.log(fee);
+     * ```
+     */
+    getSettlementFee(timestamp) {
+        return this.market.getSettlementFee(this.market.timeToMaturity(timestamp));
+    }
+    /**
+     * Returns a new position locally accrued like Midnight `updatePositionView`.
+     *
+     * @param timestamp - Timestamp at which to accrue. Must be greater than or equal to `lastAccrual`.
+     * @returns New accrual position with updated credit, pending fee, last loss factor, last accrual, and market continuous-fee credit.
+     * @throws {InvalidPositionAccrualTimestampError} when timestamp is before `lastAccrual`.
+     * @throws {InvalidPositionLossFactorError} when the market loss factor is older than the position loss factor.
+     * @throws {InvalidPositionAccrualStateError} when raw inputs violate Midnight accounting invariants.
+     * @example
+     * ```ts
+     * import { registerCustomAddresses } from "@morpho-org/morpho-ts";
+     * import { AccrualPosition } from "@morpho-org/midnight-sdk";
+     *
+     * registerCustomAddresses({
+     *   addresses: {
+     *     31337: {
+     *       morpho: "0x0000000000000000000000000000000000000001",
+     *       bundler3: {
+     *         bundler3: "0x0000000000000000000000000000000000000002",
+     *         generalAdapter1: "0x0000000000000000000000000000000000000003",
+     *       },
+     *       adaptiveCurveIrm: "0x0000000000000000000000000000000000000004",
+     *       midnight: "0x0000000000000000000000000000000000001000",
+     *     },
+     *   },
+     * });
+     *
+     * const position = new AccrualPosition(
+     *   {
+     *     credit: 1_000n,
+     *     pendingFee: 100n,
+     *     lastLossFactor: 0n,
+     *     lastAccrual: 1_000n,
+     *     debt: 0n,
+     *     collateralBitmap: 1n,
+     *     collateral: [50n],
+     *   },
+     *   {
+     *     chainId: 31337,
+     *     params: {
+     *       loanToken: "0x0000000000000000000000000000000000006000",
+     *       collateralParams: [
+     *         {
+     *           token: "0x0000000000000000000000000000000000007000",
+     *           lltv: 770000000000000000n,
+     *           maxLif: 1061007957559681697n,
+     *           oracle: "0x0000000000000000000000000000000000008000",
+     *         },
+     *       ],
+     *       maturity: 54_000n,
+     *       rcfThreshold: 0n,
+     *       enterGate: "0x0000000000000000000000000000000000000000",
+     *       liquidatorGate: "0x0000000000000000000000000000000000000000",
+     *     },
+     *     totalUnits: 1_000n,
+     *     lossFactor: 0n,
+     *     withdrawable: 500n,
+     *     continuousFeeCredit: 0n,
+     *     settlementFeeCbps: [1, 2, 3, 4, 5, 6, 7],
+     *     continuousFee: 10,
+     *     tickSpacing: 4,
+     *   },
+     * );
+     * const accrued = position.accrueInterest(1_500n);
+     * console.log(accrued.credit);
+     * ```
+     */
+    accrueInterest(timestamp) {
+        const { position, market } = PositionUtils.accrueInterest({
+            position: this,
+            market: this.market,
+            timestamp,
+        });
+        return new AccrualPosition(position, market);
+    }
+}

package/lib/esm/market/PositionUtils.d.ts

@@ -0,0 +1,115 @@
+import { type BigIntish } from "@morpho-org/morpho-ts";
+import type { IMarket } from "./Market.js";
+import type { IPosition } from "./Position.js";
+/**
+ * Domain helpers for Midnight positions.
+ *
+ * @example
+ * ```ts
+ * import { PositionUtils } from "@morpho-org/midnight-sdk";
+ *
+ * const accrued = PositionUtils.accrueInterest({
+ *   position: {
+ *     credit: 1_000n,
+ *     pendingFee: 100n,
+ *     lastLossFactor: 0n,
+ *     lastAccrual: 1_000n,
+ *     debt: 0n,
+ *     collateralBitmap: 1n,
+ *     collateral: [50n],
+ *   },
+ *   market: {
+ *     chainId: 8453,
+ *     params: {
+ *       loanToken: "0x0000000000000000000000000000000000006000",
+ *       collateralParams: [
+ *         {
+ *           token: "0x0000000000000000000000000000000000007000",
+ *           lltv: 770000000000000000n,
+ *           maxLif: 1061007957559681697n,
+ *           oracle: "0x0000000000000000000000000000000000008000",
+ *         },
+ *       ],
+ *       maturity: 54_000n,
+ *       rcfThreshold: 0n,
+ *       enterGate: "0x0000000000000000000000000000000000000000",
+ *       liquidatorGate: "0x0000000000000000000000000000000000000000",
+ *     },
+ *     totalUnits: 1_000n,
+ *     lossFactor: 0n,
+ *     withdrawable: 500n,
+ *     continuousFeeCredit: 0n,
+ *     settlementFeeCbps: [1, 2, 3, 4, 5, 6, 7],
+ *     continuousFee: 10,
+ *     tickSpacing: 4,
+ *   },
+ *   timestamp: 1_500n,
+ * });
+ * console.log(accrued.position.credit);
+ * ```
+ */
+export declare namespace PositionUtils {
+    /**
+     * Returns plain Midnight position and market objects accrued like Midnight `updatePositionView`.
+     *
+     * @param params.position - Position state to accrue.
+     * @param params.market - Hydrated market state used for loss factor and continuous-fee accrual.
+     * @param params.timestamp - Timestamp at which to accrue.
+     * @returns New plain position and market objects with updated credit, pending fee, last loss factor, last accrual, and market continuous-fee credit.
+     * @throws {InvalidPositionAccrualTimestampError} when timestamp is before `lastAccrual`.
+     * @throws {InvalidPositionLossFactorError} when the market loss factor is older than the position loss factor.
+     * @throws {InvalidPositionAccrualStateError} when raw inputs violate Midnight accounting invariants.
+     * @example
+     * ```ts
+     * import { PositionUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const { position, market } = PositionUtils.accrueInterest({
+     *   position: {
+     *     credit: 1_000n,
+     *     pendingFee: 100n,
+     *     lastLossFactor: 0n,
+     *     lastAccrual: 1_000n,
+     *     debt: 0n,
+     *     collateralBitmap: 1n,
+     *     collateral: [50n],
+     *   },
+     *   market: {
+     *     chainId: 8453,
+     *     params: {
+     *       loanToken: "0x0000000000000000000000000000000000006000",
+     *       collateralParams: [
+     *         {
+     *           token: "0x0000000000000000000000000000000000007000",
+     *           lltv: 770000000000000000n,
+     *           maxLif: 1061007957559681697n,
+     *           oracle: "0x0000000000000000000000000000000000008000",
+     *         },
+     *       ],
+     *       maturity: 54_000n,
+     *       rcfThreshold: 0n,
+     *       enterGate: "0x0000000000000000000000000000000000000000",
+     *       liquidatorGate: "0x0000000000000000000000000000000000000000",
+     *     },
+     *     totalUnits: 1_000n,
+     *     lossFactor: 0n,
+     *     withdrawable: 500n,
+     *     continuousFeeCredit: 0n,
+     *     settlementFeeCbps: [1, 2, 3, 4, 5, 6, 7],
+     *     continuousFee: 10,
+     *     tickSpacing: 4,
+     *   },
+     *   timestamp: 1_500n,
+     * });
+     * console.log(position.lastAccrual, market.continuousFeeCredit);
+     * ```
+     */
+    function accrueInterest(params: {
+        readonly position: IPosition;
+        readonly market: IMarket;
+        readonly timestamp: BigIntish;
+    }): {
+        readonly position: IPosition;
+        readonly market: IMarket;
+        readonly accruedFee: bigint;
+    };
+}