@morpho-org/midnight-sdk 0.1.0 → 1.0.0

package/lib/cjs/signatures/TreeUtils.d.ts

@@ -1,7 +1,8 @@
 import { type BigIntish } from "@morpho-org/morpho-ts";
-import { type Hash } from "viem";
-import type { MempoolPayloadValidationResult, MidnightApiFetch, MidnightApiRequestOptions } from "../api/types.js";
+import { type Account, type Address, type Chain, type Client, type Hash, type Transport } from "viem";
+import type { MempoolPayloadValidationSuccess, MidnightApiFetch, MidnightApiRequestOptions } from "../api/types.js";
 import { type IOffer, type OfferStruct } from "../offers/index.js";
+import { type EcrecoverSignatureInput } from "./EcrecoverRatifierUtils.js";
 import { type GroupInput } from "./GroupUtils.js";
 import type { Tree } from "./Tree.js";
 /**
@@ -18,12 +19,14 @@ import type { Tree } from "./Tree.js";
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -66,12 +69,14 @@ export interface TreeDescriptor {
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -113,12 +118,14 @@ export interface TreeProof {
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -144,8 +151,8 @@ export type TreeCreateParams = readonly GroupInput[];
  * Plain creation input or class tree accepted by {@link Tree.from}.
  *
  * Use this only at boundaries that intentionally convert caller input into a
- * `Tree`. Utilities that already need a full tree, such as proof and ratifier
- * helpers, accept `Tree` directly to avoid rebuilding.
+ * `Tree`. Ratifier helpers accept {@link RatifierTreeInput} instead, so they
+ * can reuse an existing `Tree` or normalize raw offer/group input.
  *
  * @example
  * ```ts
@@ -154,12 +161,14 @@ export type TreeCreateParams = readonly GroupInput[];
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -181,24 +190,28 @@ export type TreeCreateParams = readonly GroupInput[];
  */
 export type TreeInput = Tree | TreeCreateParams;
 /**
- * Parameters for {@link Tree.mempoolValidate}.
+ * Tree-shaped data required by ratifier helpers.
  *
- * Use this when an already-created tree should be validated by the Midnight
- * API before wallet signature or root approval.
+ * A `Tree` class instance satisfies this shape and is the optimal input when a
+ * caller already built one, because the cached offers, leaves, root, and height
+ * are reused for signatures and proofs. Plain objects with these fields are
+ * also accepted by ratifier helpers.
  *
  * @example
  * ```ts
- * import { Offer, Tree, type TreeMempoolValidateParams } from "@morpho-org/midnight-sdk";
+ * import { Offer, Tree, type TreeLike } from "@morpho-org/midnight-sdk";
  * import { zeroAddress } from "viem";
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -214,45 +227,44 @@ export type TreeInput = Tree | TreeCreateParams;
  *   ratifier: "0x0000000000000000000000000000000000004000",
  *   maxUnits: 100n,
  * });
- * const tree = Tree.create([offer]);
- * const params = { chainId: 8453 } satisfies TreeMempoolValidateParams;
- * const validation = await tree.mempoolValidate(params);
- * console.log(validation.valid);
+ * const tree: TreeLike = Tree.create([offer]);
+ * console.log(tree.root);
  * ```
  */
-export interface TreeMempoolValidateParams {
-    /** Chain id whose API policy should validate the tree. */
-    readonly chainId: number;
-    /** Midnight API URL used for the validation HTTP request. Defaults to `https://api.morpho.org/v1/midnight`. */
-    readonly apiUrl?: string | URL;
-    /** Optional ISO-8601 timestamp or `Date` selecting the API policy snapshot. */
-    readonly timestamp?: string | Date;
-    /** Fetch implementation used for the API call. Defaults to the global `fetch`. */
-    readonly fetch?: MidnightApiFetch;
-    /** Additional fetch options forwarded to the API request. */
-    readonly request?: MidnightApiRequestOptions;
+export interface TreeLike {
+    /** Non-padding offers in leaf order. */
+    readonly offers: readonly IOffer[];
+    /** ABI-compatible offers in leaf order, including protocol-zero padding. */
+    readonly paddedOffers: readonly OfferStruct[];
+    /** Leaf hashes for `paddedOffers`. */
+    readonly leaves: readonly Hash[];
+    /** Merkle root. */
+    readonly root: Hash;
+    /** Tree height. */
+    readonly height: number;
 }
 /**
- * Parameters for {@link TreeUtils.mempoolValidate}.
+ * Tree-like input accepted by ratifier helpers.
  *
- * Accepts either a built `Tree` or the raw entries accepted by `Tree.create`.
- * Raw entries are normalized and validated the same way `Tree.create` does
- * before the temporary validation payload is encoded and sent to the Midnight
- * API.
+ * Pass a `Tree` or {@link TreeLike} object to reuse cached hashes and proofs.
+ * Pass raw offer/group input when convenience matters more than avoiding a
+ * one-time tree materialization.
  *
  * @example
  * ```ts
- * import { Offer, TreeUtils, type TreeUtilsMempoolValidateParams } from "@morpho-org/midnight-sdk";
+ * import { Offer, type RatifierTreeInput } from "@morpho-org/midnight-sdk";
  * import { zeroAddress } from "viem";
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -268,17 +280,110 @@ export interface TreeMempoolValidateParams {
  *   ratifier: "0x0000000000000000000000000000000000004000",
  *   maxUnits: 100n,
  * });
- * const params = {
- *   chainId: 8453,
- *   tree: [offer],
- * } satisfies TreeUtilsMempoolValidateParams;
- * const validation = await TreeUtils.mempoolValidate(params);
- * console.log(validation.valid);
+ * const tree: RatifierTreeInput = [offer];
+ * console.log(tree);
+ * ```
+ */
+export type RatifierTreeInput = TreeLike | TreeCreateParams;
+/**
+ * Optional ratification inputs for {@link Tree.mempoolValidate}.
+ *
+ * Omit this when validating offer policy before the maker signs or approves a
+ * tree. Provide it when validating the final payload shape, including real
+ * `ratifierData`, after the Ecrecover signature and signer address exist or the
+ * Setter root is ready for publication.
+ *
+ * @example
+ * ```ts
+ * import { zeroHash, type Signature } from "viem";
+ * import type { TreeMempoolValidateRatification } from "@morpho-org/midnight-sdk";
+ *
+ * const ratification: TreeMempoolValidateRatification = {
+ *   type: "ecrecover",
+ *   account: "0x0000000000000000000000000000000000009000",
+ *   signature: { v: 27, r: zeroHash, s: zeroHash } satisfies Signature,
+ * };
+ * console.log(ratification.type);
  * ```
  */
-export interface TreeUtilsMempoolValidateParams extends TreeMempoolValidateParams {
-    /** Offer tree to validate before ratifier data or payload publication exists. */
-    readonly tree: TreeInput;
+export type TreeMempoolValidateRatification = {
+    /** Ecrecover ratifier route. */
+    readonly type: "ecrecover";
+    /** Viem client whose transport signs typed data built from the tree. */
+    readonly client: Client<Transport, Chain, Account | undefined>;
+    /** Account that signs the tree root. */
+    readonly account: Account | Address;
+    /** Omit when the SDK should request the signature through `client`. */
+    readonly signature?: undefined;
+} | {
+    /** Ecrecover ratifier route. */
+    readonly type: "ecrecover";
+    /** Precomputed signature for this tree root. */
+    readonly signature: EcrecoverSignatureInput;
+    /** Account that produced the signature. It may be the maker or an address authorized by each maker. */
+    readonly account: Account | Address;
+    /** Omit when a precomputed signature is supplied. */
+    readonly client?: undefined;
+} | {
+    /** Setter ratifier route. */
+    readonly type: "setter";
+};
+/**
+ * Parameters for {@link Tree.mempoolValidate}.
+ *
+ * Use this when an already-created tree should be validated by the Midnight
+ * API. By default it validates the pre-ratification tree with empty
+ * `ratifierData`; pass `ratification` to validate the final payload shape with
+ * real ratifier data.
+ *
+ * @example
+ * ```ts
+ * import { Offer, Tree, type TreeMempoolValidateParams } from "@morpho-org/midnight-sdk";
+ * import { zeroAddress } from "viem";
+ *
+ * const offer = Offer.create({
+ *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
+ *     loanToken: "0x0000000000000000000000000000000000006000",
+ *     collateralParams: [
+ *       {
+ *         token: "0x0000000000000000000000000000000000007000",
+ *         lltv: 770000000000000000n,
+ *         liquidationCursor: 250000000000000000n,
+ *         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 tree = Tree.create([offer]);
+ * const params = { chainId: 8453 } satisfies TreeMempoolValidateParams;
+ * await tree.mempoolValidate(params);
+ * ```
+ */
+export interface TreeMempoolValidateParams {
+    /** Chain id whose API policy should validate the tree. */
+    readonly chainId: number;
+    /** Midnight API URL used for the validation HTTP request. Defaults to `https://api.morpho.org/v0/midnight`. */
+    readonly apiUrl?: string | URL;
+    /** Optional ISO-8601 timestamp or `Date` selecting the API policy snapshot. */
+    readonly timestamp?: string | Date;
+    /** Fetch implementation used for the API call. Defaults to the global `fetch`. */
+    readonly fetch?: MidnightApiFetch;
+    /** Additional fetch options forwarded to the API request. */
+    readonly request?: MidnightApiRequestOptions;
+    /** Optional ratification inputs used to validate final payload bytes with real ratifier data. */
+    readonly ratification?: TreeMempoolValidateRatification;
 }
 /**
  * Object-compatible tree hashing, root, proof, and verification helpers.
@@ -299,24 +404,26 @@ export declare namespace TreeUtils {
     /**
      * Validates a tree against Midnight mempool API policy.
      *
-     * This is an API-backed convenience: it encodes each tree leaf with empty
-     * `ratifierData`, then sends the temporary payload to the Midnight API
-     * `POST /mempool/validate` endpoint. API policy only inspects offer contents,
-     * so use this after `Tree.create` and before wallet signature or Setter root
-     * approval.
+     * This is an API-backed convenience: by default it encodes each tree leaf
+     * with empty `ratifierData`, then sends the temporary payload to the Midnight
+     * API `POST /mempool/validate` endpoint. Pass `ratification` after signing or
+     * Setter root preparation to validate final payload bytes with real
+     * `ratifierData`.
      *
      * @param params.chainId - Chain id whose API policy should validate the tree.
-     * @param params.tree - Offer tree to validate before ratifier data or payload publication exists.
+     * @param params.tree - Offer tree to validate.
      * @param params.apiUrl - Optional Midnight API URL override used for the validation HTTP request.
      * @param params.timestamp - Optional ISO-8601 timestamp or `Date` selecting the API policy snapshot.
      * @param params.fetch - Optional fetch implementation override used for the API call.
      * @param params.request - Optional fetch options forwarded to the API request.
-     * @returns API issues and `valid` summary.
+     * @param params.ratification - Optional ratification inputs used to validate final payload bytes with real ratifier data.
+     * @returns Successful API validation result with `valid: true`.
      * @throws {InvalidTreeError} when the tree is empty, all padding, or duplicated.
      * @throws {InvalidTreeHeightError} when the resulting height is unsupported.
-     * @throws {Payload.DecodeError} when validation payload encoding fails.
+     * @throws {PayloadDecodeError} when validation payload encoding fails.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API returns malformed success JSON.
+     * @throws {MidnightMempoolValidationError} when the API returns validation issues.
      * @example
      * ```ts
      * import { Offer, TreeUtils } from "@morpho-org/midnight-sdk";
@@ -324,12 +431,14 @@ export declare namespace TreeUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -345,14 +454,16 @@ export declare namespace TreeUtils {
      *   ratifier: "0x0000000000000000000000000000000000004000",
      *   maxUnits: 100n,
      * });
-     * const validation = await TreeUtils.mempoolValidate({
+     * await TreeUtils.mempoolValidate({
      *   chainId: 8453,
      *   tree: [offer],
      * });
-     * console.log(validation.valid);
      * ```
      */
-    function mempoolValidate(params: TreeUtilsMempoolValidateParams): Promise<MempoolPayloadValidationResult>;
+    function mempoolValidate(params: Pick<TreeMempoolValidateParams, "chainId" | "apiUrl" | "timestamp" | "fetch" | "request"> & {
+        readonly tree: TreeInput;
+        readonly ratification?: TreeMempoolValidateRatification;
+    }): Promise<MempoolPayloadValidationSuccess>;
     /**
      * Computes HashLib node hash from left and right child hashes.
      *
@@ -393,12 +504,14 @@ export declare namespace TreeUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -437,12 +550,14 @@ export declare namespace TreeUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -470,7 +585,7 @@ export declare namespace TreeUtils {
      * built-in Ecrecover and Setter helpers call this while generating
      * `ratifierData`.
      *
-     * @param params.tree - Tree that contains the leaf.
+     * @param params.tree - Tree-like data with the root and leaves that contain the leaf.
      * @param params.leafIndex - Leaf index to prove.
      * @returns Proof descriptor.
      * @throws {InvalidTreeError} when leaf index is out of range.
@@ -481,12 +596,14 @@ export declare namespace TreeUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -510,7 +627,7 @@ export declare namespace TreeUtils {
      * ```
      */
     function buildProof(params: {
-        readonly tree: Tree;
+        readonly tree: Pick<TreeLike, "leaves" | "root">;
         readonly leafIndex: BigIntish;
     }): TreeProof;
     /**
@@ -532,12 +649,14 @@ export declare namespace TreeUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],