@morpho-org/midnight-sdk 0.1.0 → 1.1.1

package/lib/cjs/offers/OfferUtils.d.ts

@@ -1,108 +1,6 @@
-import type { BigIntish } from "@morpho-org/morpho-ts";
-import type { Address, Hash } from "viem";
+import { type BigIntish } from "@morpho-org/morpho-ts";
+import { type Address, type Hash } from "viem";
 import { type BuildOfferParams, type IOffer, Offer, type OfferStruct } from "./Offer.js";
-/**
- * Parameters for {@link OfferUtils.validateOfferGroup}.
- *
- * Use this lower-level shape when validating a would-be `Group` before the
- * offers are committed to a tree.
- *
- * @example
- * ```ts
- * import type { ValidateOfferGroupParams } from "@morpho-org/midnight-sdk";
- *
- * const params = { offers: [] } as ValidateOfferGroupParams;
- * console.log(Array.from(params.offers).length);
- * ```
- */
-export interface ValidateOfferGroupParams {
-    /** Offers to validate as one protocol consumption group. */
-    readonly offers: Iterable<IOffer>;
-}
-/**
- * Parameters for {@link OfferUtils.toStruct}.
- *
- * The group id is read from the offer by default. Supply `group` only when a
- * caller intentionally needs to encode the same offer with an override, such as
- * deriving a group id from an offer hashed with the zero group id.
- *
- * @example
- * ```ts
- * import { Offer, type OfferStructParams } from "@morpho-org/midnight-sdk";
- * import { zeroAddress } from "viem";
- *
- * const params: OfferStructParams = {
- *   offer: Offer.create({
- *     market: {
- *       loanToken: "0x0000000000000000000000000000000000006000",
- *       collateralParams: [
- *         {
- *           token: "0x0000000000000000000000000000000000007000",
- *           lltv: 770000000000000000n,
- *           maxLif: 1061007957559681697n,
- *           oracle: "0x0000000000000000000000000000000000008000",
- *         },
- *       ],
- *       maturity: 54_000n,
- *       rcfThreshold: 0n,
- *       enterGate: zeroAddress,
- *       liquidatorGate: zeroAddress,
- *     },
- *     buy: true,
- *     maker: "0x0000000000000000000000000000000000009000",
- *     tick: 5_000n,
- *     expiry: 3_600n,
- *     ratifier: "0x0000000000000000000000000000000000004000",
- *     maxUnits: 100n,
- *   }),
- * };
- * console.log(params.offer);
- * ```
- */
-export interface OfferStructParams {
-    /** Offer to encode. */
-    readonly offer: IOffer;
-    /** Optional protocol group id override encoded into the ABI offer. */
-    readonly group?: Hash;
-}
-/**
- * Deterministic make-offer parameters after protocol validation.
- *
- * @example
- * ```ts
- * import type { ValidatedOfferParams } from "@morpho-org/midnight-sdk";
- * import { zeroAddress } from "viem";
- *
- * const params: ValidatedOfferParams = {
- *   tick: 5_000n,
- *   tickSpacing: 4n,
- *   start: 0n,
- *   expiry: 3_600n,
- *   maxUnits: 100n,
- *   maxAssets: 0n,
- *   receiverIfMakerIsSeller: zeroAddress,
- * };
- * console.log(params.tick);
- * ```
- */
-export interface ValidatedOfferParams {
-    /** Tick in the deployed range and aligned to `tickSpacing`. */
-    readonly tick: bigint;
-    /** Market tick spacing used to validate tick accessibility. */
-    readonly tickSpacing: bigint;
-    /** Offer start timestamp. */
-    readonly start: bigint;
-    /** Offer expiry timestamp. */
-    readonly expiry: bigint;
-    /** Maximum units, with exactly one cap non-zero. */
-    readonly maxUnits: bigint;
-    /** Maximum buyer or seller assets, with exactly one cap non-zero. */
-    readonly maxAssets: bigint;
-    /** Maximum market continuous fee accepted by this offer. */
-    readonly continuousFeeCap: bigint;
-    /** Receiver used only when maker is seller. */
-    readonly receiverIfMakerIsSeller: Address;
-}
 /**
  * Object-compatible helpers for Midnight offer construction, grouping, and
  * take-side encoding.
@@ -136,12 +34,14 @@ export declare namespace OfferUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -161,7 +61,10 @@ export declare namespace OfferUtils {
      * console.log(struct.tick);
      * ```
      */
-    function toStruct(params: OfferStructParams): OfferStruct;
+    function toStruct(params: {
+        readonly offer: IOffer;
+        readonly group?: Hash;
+    }): OfferStruct;
     /**
      * Computes the canonical protocol offer hash for an ABI-compatible offer.
      *
@@ -180,12 +83,14 @@ export declare namespace OfferUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -223,12 +128,14 @@ export declare namespace OfferUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -249,9 +156,7 @@ export declare namespace OfferUtils {
      * console.log(hash);
      * ```
      */
-    function hash(offer: IOffer & {
-        readonly group: Hash;
-    }): Hash;
+    function hash(offer: IOffer & Required<Pick<IOffer, "group">>): Hash;
     /**
      * Computes the offer hash used to derive a content-addressed group id.
      *
@@ -268,12 +173,14 @@ export declare namespace OfferUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -328,7 +235,7 @@ export declare namespace OfferUtils {
      * @param params.start - Optional offer start timestamp; defaults to zero.
      * @param params.expiry - Offer expiry timestamp.
      * @returns Normalized start and expiry timestamps.
-     * @throws {InvalidOfferParameterError} when the range is negative or not strictly increasing.
+     * @throws {InvalidOfferParameterError} when the range is negative or expiry is before start.
      * @example
      * ```ts
      * import { OfferUtils } from "@morpho-org/midnight-sdk";
@@ -373,8 +280,8 @@ export declare namespace OfferUtils {
      * Validates and normalizes the maximum continuous fee an offer accepts.
      *
      * Use this before `Offer.create` when a maker UI exposes fee tolerance.
-     * `Offer.create` calls it internally and defaults omitted values to
-     * {@link MAX_CONTINUOUS_FEE}.
+     * `Offer.create` calls it internally and defaults omitted values to zero so
+     * fresh offers fail closed unless the maker explicitly accepts a fee cap.
      *
      * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer.
      * @returns Normalized continuous fee cap.
@@ -426,22 +333,16 @@ export declare namespace OfferUtils {
      * instantiating an `Offer`. `Offer.create` uses the same validation and then
      * constructs the class instance for grouping and trees.
      *
-     * @param params.market - Market params or hydrated market this offer trades.
      * @param params.buy - Whether the maker buys loan assets.
      * @param params.maker - Maker address.
      * @param params.tick - Offer tick.
-     * @param params.group - Optional consumption group id for already-grouped offers.
      * @param params.tickSpacing - Optional market tick spacing; defaults to `DEFAULT_TICK_SPACING`.
      * @param params.maxUnits - Optional unit cap; defaults to zero.
      * @param params.maxAssets - Optional buyer or seller asset cap; defaults to zero.
-     * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer; defaults to `MAX_CONTINUOUS_FEE`.
+     * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer; defaults to zero.
      * @param params.start - Optional offer start timestamp; defaults to zero.
      * @param params.expiry - Offer expiry timestamp.
-     * @param params.callback - Optional callback address; defaults to the zero address.
-     * @param params.callbackData - Optional callback payload; defaults to `0x`.
      * @param params.receiverIfMakerIsSeller - Optional receiver used when maker is seller.
-     * @param params.ratifier - Ratifier contract address.
-     * @param params.reduceOnly - Optional flag restricting the offer to exposure-reducing execution.
      * @returns Normalized deterministic offer parameters.
      * @throws {InvalidOfferParameterError} when a deterministic offer parameter cannot satisfy protocol rules.
      * @example
@@ -449,32 +350,25 @@ export declare namespace OfferUtils {
      * import { OfferUtils } from "@morpho-org/midnight-sdk";
      *
      * const params = OfferUtils.validateOfferParams({
-     *   market: {
-     *     loanToken: "0x0000000000000000000000000000000000006000",
-     *     collateralParams: [
-     *       {
-     *         token: "0x0000000000000000000000000000000000007000",
-     *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
-     *         oracle: "0x0000000000000000000000000000000000008000",
-     *       },
-     *     ],
-     *     maturity: 54_000n,
-     *     rcfThreshold: 0n,
-     *     enterGate: "0x0000000000000000000000000000000000000000",
-     *     liquidatorGate: "0x0000000000000000000000000000000000000000",
-     *   },
      *   buy: true,
      *   maker: "0x0000000000000000000000000000000000009000",
      *   tick: 5_000n,
      *   expiry: 3_600n,
-     *   ratifier: "0x0000000000000000000000000000000000004000",
      *   maxUnits: 100n,
      * });
      * console.log(params.maxAssets);
      * ```
      */
-    function validateOfferParams(params: BuildOfferParams): ValidatedOfferParams;
+    function validateOfferParams(params: Pick<BuildOfferParams, "buy" | "maker" | "tick" | "tickSpacing" | "maxUnits" | "maxAssets" | "continuousFeeCap" | "start" | "expiry" | "receiverIfMakerIsSeller">): {
+        readonly tick: bigint;
+        readonly tickSpacing: bigint;
+        readonly start: bigint;
+        readonly expiry: bigint;
+        readonly maxUnits: bigint;
+        readonly maxAssets: bigint;
+        readonly continuousFeeCap: bigint;
+        readonly receiverIfMakerIsSeller: Address;
+    };
     /**
      * Validates protocol-level mechanics for one Midnight offer consumption group.
      *
@@ -494,12 +388,14 @@ export declare namespace OfferUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -519,7 +415,215 @@ export declare namespace OfferUtils {
      * console.log(offers.length);
      * ```
      */
-    function validateOfferGroup(params: ValidateOfferGroupParams): readonly Offer[];
+    function validateOfferGroup(params: {
+        readonly offers: Iterable<IOffer>;
+    }): readonly Offer[];
+    /**
+     * Converts an offer tick into its WAD zero-coupon price.
+     *
+     * Use for display or local quote checks when accepting any plain object
+     * matching `IOffer` or an `Offer` instance.
+     *
+     * @param offer - Offer to inspect.
+     * @returns WAD price rounded to the protocol price quantum.
+     * @throws {NegativeValueError} when `offer.tick` is negative.
+     * @throws {TickOutOfRangeError} when `offer.tick` exceeds `MAX_TICK`.
+     * @example
+     * ```ts
+     * import { OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const price = OfferUtils.getPrice({ tick: 5_000n });
+     * console.log(price);
+     * ```
+     */
+    function getPrice(offer: Pick<IOffer, "tick">): bigint;
+    /**
+     * Converts an offer tick into a WAD per-second simple rate at a timestamp.
+     *
+     * The rate is the offer's fixed period rate divided by the market's remaining
+     * time to maturity at `timestamp`, rounded up.
+     *
+     * @param params.offer - Offer to inspect.
+     * @param params.timestamp - Timestamp at which the rate is calculated.
+     * @returns WAD per-second simple rate rounded up.
+     * @throws {NegativeValueError} when `market.maturity`, `timestamp`, or `tick` is negative.
+     * @throws {TickOutOfRangeError} when `tick` exceeds `MAX_TICK`.
+     * @throws {DivisionByZeroError} when the tick price is zero or `timestamp` is at or after maturity.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const offer = Offer.from({
+     *   market: {
+     *     loanToken: "0x0000000000000000000000000000000000006000",
+     *     collateralParams: [
+     *       {
+     *         token: "0x0000000000000000000000000000000000007000",
+     *         lltv: 770000000000000000n,
+     *         liquidationCursor: 250000000000000000n,
+     *         oracle: "0x0000000000000000000000000000000000008000",
+     *       },
+     *     ],
+     *     maturity: 54_000n,
+     *     rcfThreshold: 0n,
+     *     enterGate: "0x0000000000000000000000000000000000000000",
+     *     liquidatorGate: "0x0000000000000000000000000000000000000000",
+     *   },
+     *   buy: true,
+     *   maker: "0x0000000000000000000000000000000000009000",
+     *   start: 0n,
+     *   expiry: 3_600n,
+     *   tick: 5_000n,
+     *   callback: "0x0000000000000000000000000000000000000000",
+     *   callbackData: "0x",
+     *   receiverIfMakerIsSeller: "0x0000000000000000000000000000000000000000",
+     *   ratifier: "0x0000000000000000000000000000000000004000",
+     *   reduceOnly: false,
+     *   maxUnits: 100n,
+     *   maxAssets: 0n,
+     *   continuousFeeCap: 317097919n,
+     * });
+     * const rate = OfferUtils.getRate({ offer, timestamp: 1_000n });
+     * console.log(rate);
+     * ```
+     */
+    function getRate(params: {
+        readonly offer: Pick<IOffer, "market" | "tick">;
+        readonly timestamp: BigIntish;
+    }): bigint;
+    /**
+     * Converts an offer tick into a WAD simple annual percentage rate at a timestamp.
+     *
+     * It computes time to maturity from the offer market and delegates the final
+     * tick annualization to `TickLib.tickToApr`.
+     *
+     * @param params.offer - Offer to inspect.
+     * @param params.timestamp - Timestamp at which the APR is calculated.
+     * @returns WAD simple APR rounded up.
+     * @throws {NegativeValueError} when `market.maturity`, `timestamp`, or `tick` is negative.
+     * @throws {TickOutOfRangeError} when `tick` exceeds `MAX_TICK`.
+     * @throws {DivisionByZeroError} when the tick price is zero or `timestamp` is at or after maturity.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const offer = Offer.from({
+     *   market: {
+     *     loanToken: "0x0000000000000000000000000000000000006000",
+     *     collateralParams: [
+     *       {
+     *         token: "0x0000000000000000000000000000000000007000",
+     *         lltv: 770000000000000000n,
+     *         liquidationCursor: 250000000000000000n,
+     *         oracle: "0x0000000000000000000000000000000000008000",
+     *       },
+     *     ],
+     *     maturity: 54_000n,
+     *     rcfThreshold: 0n,
+     *     enterGate: "0x0000000000000000000000000000000000000000",
+     *     liquidatorGate: "0x0000000000000000000000000000000000000000",
+     *   },
+     *   buy: true,
+     *   maker: "0x0000000000000000000000000000000000009000",
+     *   start: 0n,
+     *   expiry: 3_600n,
+     *   tick: 5_000n,
+     *   callback: "0x0000000000000000000000000000000000000000",
+     *   callbackData: "0x",
+     *   receiverIfMakerIsSeller: "0x0000000000000000000000000000000000000000",
+     *   ratifier: "0x0000000000000000000000000000000000004000",
+     *   reduceOnly: false,
+     *   maxUnits: 100n,
+     *   maxAssets: 0n,
+     *   continuousFeeCap: 317097919n,
+     * });
+     * const apr = OfferUtils.getApr({ offer, timestamp: 1_000n });
+     * console.log(apr);
+     * ```
+     */
+    function getApr(params: {
+        readonly offer: Pick<IOffer, "market" | "tick">;
+        readonly timestamp: BigIntish;
+    }): bigint;
+    /**
+     * Returns remaining units accepted by an offer's cap at a timestamp.
+     *
+     * The offer must carry a hydrated {@link Market} so the current market
+     * continuous fee and settlement-fee buckets are available locally. Fetch the
+     * current `consumed(maker, group)` value separately and pass it as input.
+     *
+     * @param params.offer - Offer to inspect. Its market must be hydrated.
+     * @param params.consumed - Amount already consumed from the offer group.
+     * @param params.timestamp - Timestamp used to compute market time to maturity.
+     * @returns Remaining consumable units accepted by Midnight `take`.
+     * @throws {InvalidOfferParameterError} when the offer does not carry hydrated market state or has invalid caps.
+     * @throws {NegativeValueError} when `consumed`, `timestamp`, offer limits, or delegated math inputs are negative.
+     * @throws {TickOutOfRangeError} when `tick` exceeds `MAX_TICK`.
+     * @throws {SettlementFeeExceedsPriceError} when settlement fee exceeds a buy-offer price.
+     * @example
+     * ```ts
+     * import { OfferUtils, midnightAbi } from "@morpho-org/midnight-sdk";
+     * import { createPublicClient, http } from "viem";
+     * import { base } from "viem/chains";
+     * import { readContract } from "viem/actions";
+     *
+     * const client = createPublicClient({ chain: base, transport: http() });
+     * const offer = {
+     *   market: {
+     *     params: {
+     *       chainId: 8453,
+     *       midnight: "0x0000000000000000000000000000000000001000",
+     *       loanToken: "0x0000000000000000000000000000000000006000",
+     *       collateralParams: [
+     *         {
+     *           token: "0x0000000000000000000000000000000000007000",
+     *           lltv: 770000000000000000n,
+     *           liquidationCursor: 250000000000000000n,
+     *           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,
+     *   },
+     *   buy: true,
+     *   maker: "0x0000000000000000000000000000000000009000",
+     *   start: 0n,
+     *   expiry: 3_600n,
+     *   tick: 5_000n,
+     *   callback: "0x0000000000000000000000000000000000000000",
+     *   callbackData: "0x",
+     *   receiverIfMakerIsSeller: "0x0000000000000000000000000000000000000000",
+     *   ratifier: "0x0000000000000000000000000000000000004000",
+     *   reduceOnly: false,
+     *   maxUnits: 100n,
+     *   maxAssets: 0n,
+     *   continuousFeeCap: 317097919n,
+     * } as const;
+     * const consumed = await readContract(client, {
+     *   address: "0x0000000000000000000000000000000000001000",
+     *   abi: midnightAbi,
+     *   functionName: "consumed",
+     *   args: [offer.maker, "0x1111111111111111111111111111111111111111111111111111111111111111"],
+     * });
+     * const units = OfferUtils.getConsumableUnits({ offer, consumed, timestamp: 1_000n });
+     * console.log(units);
+     * ```
+     */
+    function getConsumableUnits(params: {
+        readonly offer: Pick<IOffer, "market" | "buy" | "start" | "expiry" | "tick" | "maxUnits" | "maxAssets" | "continuousFeeCap">;
+        readonly consumed: BigIntish;
+        readonly timestamp: BigIntish;
+    }): bigint;
     /**
      * Returns an offer expiry timestamp.
      *
@@ -536,12 +640,14 @@ export declare namespace OfferUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -561,5 +667,5 @@ export declare namespace OfferUtils {
      * console.log(expiry);
      * ```
      */
-    function getOfferExpiry(offer: IOffer): bigint;
+    function getOfferExpiry(offer: Pick<IOffer, "expiry">): bigint;
 }