@morpho-org/midnight-sdk 0.1.0

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

@@ -0,0 +1,565 @@
+import type { BigIntish } from "@morpho-org/morpho-ts";
+import type { Address, 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.
+ *
+ * Make-side apps usually call {@link Offer.create}, then `Group.create` or
+ * `Tree.create`. Use these helpers when you need the same validation or ABI
+ * conversion without depending on class instances, or when converting API data
+ * into the structs consumed by payload and take encoders.
+ *
+ * @example
+ * ```ts
+ * import { OfferUtils } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(typeof OfferUtils.getOfferExpiry);
+ * ```
+ */
+export declare namespace OfferUtils {
+    /**
+     * Converts an offer into the tuple object expected by viem ABI encoders.
+     *
+     * This is the bridge from SDK/domain objects
+     * into Merkle leaf hashing, payload items, and take calldata encoding.
+     *
+     * @param params.offer - Offer class or plain offer input to encode.
+     * @param params.group - Optional protocol group id override encoded into the ABI offer.
+     * @returns ABI-compatible offer.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const 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,
+     * });
+     * const struct = OfferUtils.toStruct({ offer });
+     * console.log(struct.tick);
+     * ```
+     */
+    function toStruct(params: OfferStructParams): OfferStruct;
+    /**
+     * Computes the canonical protocol offer hash for an ABI-compatible offer.
+     *
+     * Use when you already have an `OfferStruct`, for example from
+     * `GroupUtils.toStructs`, `TreeUtils.buildDescriptor`, or decoded payload
+     * bytes. Use `hash` when you still have a grouped `Offer` or grouped plain
+     * offer input, and `groupHash` when deriving a group id from the zero-group
+     * hash.
+     *
+     * @param offerStruct - ABI-compatible offer to hash.
+     * @returns Offer hash.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress, zeroHash } from "viem";
+     *
+     * const 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,
+     * });
+     * const hash = OfferUtils.hashStruct(
+     *   OfferUtils.toStruct({ offer, group: zeroHash }),
+     * );
+     * console.log(hash);
+     * ```
+     */
+    function hashStruct(offerStruct: OfferStruct): Hash;
+    /**
+     * Computes the canonical protocol offer hash from the offer's group id.
+     *
+     * Use this for final tree leaves and payload offers after a group has been
+     * assigned. Use `groupHash` for the zero-group hash that derives a group id.
+     *
+     * @param offer - Offer with the protocol group id encoded into the hash.
+     * @returns Offer hash.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress, zeroHash } from "viem";
+     *
+     * const 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,
+     *   group: zeroHash,
+     *   expiry: 3_600n,
+     *   ratifier: "0x0000000000000000000000000000000000004000",
+     *   maxUnits: 100n,
+     * });
+     * const hash = OfferUtils.hash(offer);
+     * console.log(hash);
+     * ```
+     */
+    function hash(offer: IOffer & {
+        readonly group: Hash;
+    }): Hash;
+    /**
+     * Computes the offer hash used to derive a content-addressed group id.
+     *
+     * The encoded group is always the protocol zero hash. Use this only for
+     * standalone or grouped-offer id derivation, not for final tree leaves or
+     * payload offers.
+     *
+     * @param offer - Offer to hash without a group id.
+     * @returns Offer hash encoded with the protocol zero group id.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const 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,
+     * });
+     * const hash = OfferUtils.groupHash(offer);
+     * console.log(hash);
+     * ```
+     */
+    function groupHash(offer: Omit<IOffer, "group">): Hash;
+    /**
+     * Validates and normalizes a Midnight offer tick and spacing.
+     *
+     * Use this for form-level validation before `Offer.create` when you want to
+     * surface a tick-specific issue. `Offer.create` calls it internally.
+     *
+     * @param params.tick - Offer tick to validate.
+     * @param params.tickSpacing - Optional market tick spacing; defaults to `DEFAULT_TICK_SPACING`.
+     * @returns Normalized tick and tick spacing.
+     * @throws {InvalidOfferParameterError} when the tick or spacing cannot be accepted by Midnight.
+     * @example
+     * ```ts
+     * import { OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const { tick } = OfferUtils.validateOfferTick({ tick: 4n });
+     * console.log(tick);
+     * ```
+     */
+    function validateOfferTick(params: {
+        readonly tick: BigIntish;
+        readonly tickSpacing?: BigIntish;
+    }): {
+        tick: bigint;
+        tickSpacing: bigint;
+    };
+    /**
+     * Validates and normalizes an offer start/expiry range.
+     *
+     * Use this before `Offer.create` when a UI edits dates separately from other
+     * offer fields. `Offer.create` calls it internally.
+     *
+     * @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.
+     * @example
+     * ```ts
+     * import { OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const range = OfferUtils.validateOfferTimeRange({ start: 0n, expiry: 1n });
+     * console.log(range.expiry);
+     * ```
+     */
+    function validateOfferTimeRange(params: {
+        readonly start?: BigIntish;
+        readonly expiry: BigIntish;
+    }): {
+        start: bigint;
+        expiry: bigint;
+    };
+    /**
+     * Validates and normalizes mutually exclusive offer caps.
+     *
+     * Use this before `Offer.create` when a UI lets makers choose between a unit
+     * cap and an asset cap. `Offer.create` calls it internally.
+     *
+     * @param params.maxUnits - Optional unit cap; defaults to zero.
+     * @param params.maxAssets - Optional buyer or seller asset cap; defaults to zero.
+     * @returns Normalized unit and asset caps.
+     * @throws {InvalidOfferParameterError} when caps are negative, both zero, or both non-zero.
+     * @example
+     * ```ts
+     * import { OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const caps = OfferUtils.validateOfferCaps({ maxAssets: 100n });
+     * console.log(caps.maxAssets);
+     * ```
+     */
+    function validateOfferCaps(params: {
+        readonly maxUnits?: BigIntish;
+        readonly maxAssets?: BigIntish;
+    }): {
+        maxUnits: bigint;
+        maxAssets: bigint;
+    };
+    /**
+     * 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}.
+     *
+     * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer.
+     * @returns Normalized continuous fee cap.
+     * @throws {InvalidOfferParameterError} when the cap is negative.
+     * @example
+     * ```ts
+     * import { OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const cap = OfferUtils.validateContinuousFeeCap({});
+     * console.log(cap.continuousFeeCap);
+     * ```
+     */
+    function validateContinuousFeeCap(params: {
+        readonly continuousFeeCap?: BigIntish;
+    }): {
+        continuousFeeCap: bigint;
+    };
+    /**
+     * Resolves and validates the maker-seller receiver field for an offer side.
+     *
+     * Use this before `Offer.create` when side-specific receiver defaults must be
+     * displayed to a maker. `Offer.create` calls it internally.
+     *
+     * @param params.buy - Whether the maker buys loan assets.
+     * @param params.maker - Maker address used as the default sell-side receiver.
+     * @param params.receiverIfMakerIsSeller - Optional receiver used when maker is seller.
+     * @returns Receiver address to put on the offer.
+     * @throws {InvalidOfferParameterError} when a buy offer sets a non-zero maker-seller receiver.
+     * @example
+     * ```ts
+     * import { OfferUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const receiver = OfferUtils.resolveReceiverIfMakerIsSeller({
+     *   buy: true,
+     *   maker: "0x0000000000000000000000000000000000000001",
+     * });
+     * console.log(receiver);
+     * ```
+     */
+    function resolveReceiverIfMakerIsSeller(params: {
+        readonly buy: boolean;
+        readonly maker: Address;
+        readonly receiverIfMakerIsSeller?: Address;
+    }): `0x${string}`;
+    /**
+     * Validates deterministic make-offer parameters without constructing an offer.
+     *
+     * Use when an app needs normalized maker input or field-level errors before
+     * 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.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
+     * ```ts
+     * 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;
+    /**
+     * Validates protocol-level mechanics for one Midnight offer consumption group.
+     *
+     * Use before deriving a content-addressed group id. Grouped offers must share
+     * maker, side, loan token, cap mode, and cap value because Midnight tracks one
+     * consumed scalar per maker and group. `Group.create` calls this automatically;
+     * call it directly only when you need the normalized offers without
+     * constructing a `Group`.
+     *
+     * @param params.offers - Offers to validate as one protocol consumption group.
+     * @returns Normalized offers in the same order as the input entries.
+     * @throws {InvalidOfferGroupError} when the group violates protocol mechanics.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const 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,
+     * });
+     * const offers = OfferUtils.validateOfferGroup({ offers: [offer] });
+     * console.log(offers.length);
+     * ```
+     */
+    function validateOfferGroup(params: ValidateOfferGroupParams): readonly Offer[];
+    /**
+     * Returns an offer expiry timestamp.
+     *
+     * Use in maker UIs, API response mappers, or quote filters when accepting
+     * any plain object matching `IOffer` or an `Offer` instance. This does not validate
+     * whether the offer is still live at the current block time.
+     *
+     * @param offer - Offer to inspect.
+     * @returns Offer expiry.
+     * @example
+     * ```ts
+     * import { Offer, OfferUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const 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,
+     * });
+     * const expiry = OfferUtils.getOfferExpiry(offer);
+     * console.log(expiry);
+     * ```
+     */
+    function getOfferExpiry(offer: IOffer): bigint;
+}