@morpho-org/midnight-sdk 0.1.0 → 1.0.0

package/lib/esm/signatures/RatifierUtils.d.ts

@@ -1,4 +1,5 @@
 import type { Address, Hex } from "viem";
+import type { RatifierTreeInput, TreeLike } from "./TreeUtils.js";
 /**
  * Parameters for {@link RatifierUtils.getRatifierInfo}.
  *
@@ -65,6 +66,62 @@ export interface RatifierInfo {
  * ```
  */
 export declare namespace RatifierUtils {
+    /**
+     * Normalizes a ratifier tree input and asserts it uses one ratifier address.
+     *
+     * Pass an existing `Tree` or `TreeLike` object to reuse cached offers,
+     * leaves, root, and height. Pass raw offer/group input when the caller has
+     * not materialized a tree yet.
+     *
+     * @param params.tree - Tree-like object or raw offer/group input.
+     * @param params.label - Ratifier label used in validation errors.
+     * @returns Normalized tree-like data and its shared ratifier.
+     * @throws {InvalidTreeError} when the tree is empty or contains multiple ratifiers.
+     * @throws {InvalidTreeHeightError} when normalized raw input exceeds the supported tree height.
+     * @example
+     * ```ts
+     * import { Offer, RatifierUtils } 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, ratifier } = RatifierUtils.normalizeRatifierTree({
+     *   tree: [offer],
+     *   label: "Ecrecover",
+     * });
+     * console.log(tree.root, ratifier);
+     * ```
+     */
+    function normalizeRatifierTree(params: {
+        readonly tree: RatifierTreeInput;
+        readonly label: "Ecrecover" | "Setter";
+    }): {
+        readonly tree: TreeLike;
+        readonly ratifier: Address;
+    };
     /**
      * Checks whether bytecode is an EIP-7702 designator.
      *

package/lib/esm/signatures/RatifierUtils.js

@@ -1,3 +1,42 @@
+import { InvalidTreeError } from "../errors.js";
+import { Offer } from "../offers/index.js";
+import { Group } from "./Group.js";
+import { TreeUtils } from "./TreeUtils.js";
+function isTreeLike(tree) {
+    return (!Array.isArray(tree) &&
+        "offers" in tree &&
+        "paddedOffers" in tree &&
+        "leaves" in tree &&
+        "root" in tree &&
+        "height" in tree);
+}
+function normalizeTree(tree) {
+    if (isTreeLike(tree))
+        return tree;
+    const offers = tree.flatMap((entry) => "offers" in entry ? Group.from(entry).offers : [Offer.from(entry)]);
+    const descriptor = TreeUtils.buildDescriptor(offers);
+    return {
+        offers,
+        paddedOffers: descriptor.offers,
+        leaves: descriptor.leaves,
+        root: descriptor.root,
+        height: descriptor.height,
+    };
+}
+function assertRatifierTree(params) {
+    const firstOffer = params.tree.offers[0];
+    if (firstOffer == null) {
+        throw new InvalidTreeError("Tree must contain at least one offer.");
+    }
+    const ratifier = firstOffer.ratifier;
+    const comparableRatifier = ratifier.toLowerCase();
+    for (const offer of params.tree.offers.slice(1)) {
+        if (offer.ratifier.toLowerCase() !== comparableRatifier) {
+            throw new InvalidTreeError(`All offers in a ${params.label} tree must use one ratifier; expected "${ratifier}", got "${offer.ratifier}". Build separate trees per ratifier.`);
+        }
+    }
+    return ratifier;
+}
 /**
  * Utilities for selecting Midnight ratifier routes.
  *
@@ -15,6 +54,61 @@
  */
 export var RatifierUtils;
 (function (RatifierUtils) {
+    /**
+     * Normalizes a ratifier tree input and asserts it uses one ratifier address.
+     *
+     * Pass an existing `Tree` or `TreeLike` object to reuse cached offers,
+     * leaves, root, and height. Pass raw offer/group input when the caller has
+     * not materialized a tree yet.
+     *
+     * @param params.tree - Tree-like object or raw offer/group input.
+     * @param params.label - Ratifier label used in validation errors.
+     * @returns Normalized tree-like data and its shared ratifier.
+     * @throws {InvalidTreeError} when the tree is empty or contains multiple ratifiers.
+     * @throws {InvalidTreeHeightError} when normalized raw input exceeds the supported tree height.
+     * @example
+     * ```ts
+     * import { Offer, RatifierUtils } 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, ratifier } = RatifierUtils.normalizeRatifierTree({
+     *   tree: [offer],
+     *   label: "Ecrecover",
+     * });
+     * console.log(tree.root, ratifier);
+     * ```
+     */
+    function normalizeRatifierTree(params) {
+        const tree = normalizeTree(params.tree);
+        const ratifier = assertRatifierTree({ tree, label: params.label });
+        return { tree, ratifier };
+    }
+    RatifierUtils.normalizeRatifierTree = normalizeRatifierTree;
     /**
      * Checks whether bytecode is an EIP-7702 designator.
      *

package/lib/esm/signatures/SetterRatifierUtils.d.ts

@@ -1,8 +1,7 @@
 import { type BigIntish } from "@morpho-org/morpho-ts";
 import { type Hash, type Hex } from "viem";
-import type { Item as PayloadItem } from "./Payload.js";
-import type { Tree } from "./Tree.js";
-import type { TreeProof } from "./TreeUtils.js";
+import type { Payload } from "./Payload.js";
+import { type RatifierTreeInput, type TreeProof } from "./TreeUtils.js";
 /**
  * Decoded SetterRatifier ratifier data.
  *
@@ -39,12 +38,14 @@ export type DecodedSetterRatifierData = TreeProof;
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -68,8 +69,8 @@ export type DecodedSetterRatifierData = TreeProof;
  * ```
  */
 export interface SetterRatifierDataParams {
-    /** Tree that produced the proof. */
-    readonly tree: Tree;
+    /** Tree-like input that produced the proof. Existing `Tree` instances reuse cached hashes and proofs. */
+    readonly tree: RatifierTreeInput;
     /** Leaf index to prove. */
     readonly leafIndex: BigIntish;
 }
@@ -80,6 +81,9 @@ export interface SetterRatifierDataParams {
  * offers with the Setter ratifier address, build the group/tree, validate the
  * tree, approve the root onchain for every maker in the tree, call `ratify`,
  * then pass the returned items to `Payload.encode`.
+ * Ratifier helpers accept tree-like inputs rather than requiring the `Tree`
+ * class. Passing an existing `Tree` remains the optimal path because its
+ * cached offers, leaves, root, and height are reused when proofs are encoded.
  *
  * @example
  * ```ts
@@ -148,10 +152,10 @@ export declare namespace SetterRatifierUtils {
      * approvals are keyed by maker and root, so the maker for this leaf must have
      * approved the tree root onchain.
      *
-     * @param params.tree - Setter-ratified offer tree that produced the proof.
+     * @param params.tree - Setter-ratified offer tree-like input that produced the proof.
      * @param params.leafIndex - Leaf index to prove.
      * @returns ABI-encoded SetterRatifier data.
-     * @throws {InvalidTreeError} when the leaf index is outside the tree.
+     * @throws {InvalidTreeError} when the leaf index is outside the tree or the tree contains multiple ratifiers.
      * @example
      * ```ts
      * import { Offer, SetterRatifierUtils, Tree } from "@morpho-org/midnight-sdk";
@@ -159,12 +163,14 @@ export declare namespace SetterRatifierUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -198,7 +204,7 @@ export declare namespace SetterRatifierUtils {
      * directly to `Payload.encode`. All offers in the tree must use one ratifier
      * address; build separate trees per ratifier.
      *
-     * @param params.tree - Setter-ratified offer tree whose root has already been approved onchain.
+     * @param params.tree - Setter-ratified offer tree-like input whose root has already been approved onchain.
      * @returns Items containing each offer and its ratifier data.
      * @throws {InvalidTreeError} when the tree is invalid or contains multiple ratifiers.
      * @example
@@ -209,12 +215,14 @@ export declare namespace SetterRatifierUtils {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -238,6 +246,6 @@ export declare namespace SetterRatifierUtils {
      * ```
      */
     function ratify(params: {
-        readonly tree: Tree;
-    }): readonly PayloadItem[];
+        readonly tree: RatifierTreeInput;
+    }): readonly Payload.Item[];
 }

package/lib/esm/signatures/SetterRatifierUtils.js

@@ -1,6 +1,7 @@
 import { deepFreeze } from "@morpho-org/morpho-ts";
 import { decodeAbiParameters, encodeAbiParameters, } from "viem";
-import { InvalidTreeError } from "../errors.js";
+import { RatifierUtils } from "./RatifierUtils.js";
+import { TreeUtils, } from "./TreeUtils.js";
 const setterRatifierDataAbi = [
     { name: "root", type: "bytes32" },
     { name: "leafIndex", type: "uint256" },
@@ -13,6 +14,9 @@ const setterRatifierDataAbi = [
  * offers with the Setter ratifier address, build the group/tree, validate the
  * tree, approve the root onchain for every maker in the tree, call `ratify`,
  * then pass the returned items to `Payload.encode`.
+ * Ratifier helpers accept tree-like inputs rather than requiring the `Tree`
+ * class. Passing an existing `Tree` remains the optimal path because its
+ * cached offers, leaves, root, and height are reused when proofs are encoded.
  *
  * @example
  * ```ts
@@ -89,10 +93,10 @@ export var SetterRatifierUtils;
      * approvals are keyed by maker and root, so the maker for this leaf must have
      * approved the tree root onchain.
      *
-     * @param params.tree - Setter-ratified offer tree that produced the proof.
+     * @param params.tree - Setter-ratified offer tree-like input that produced the proof.
      * @param params.leafIndex - Leaf index to prove.
      * @returns ABI-encoded SetterRatifier data.
-     * @throws {InvalidTreeError} when the leaf index is outside the tree.
+     * @throws {InvalidTreeError} when the leaf index is outside the tree or the tree contains multiple ratifiers.
      * @example
      * ```ts
      * import { Offer, SetterRatifierUtils, Tree } from "@morpho-org/midnight-sdk";
@@ -100,12 +104,14 @@ export var SetterRatifierUtils;
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -129,7 +135,11 @@ export var SetterRatifierUtils;
      * ```
      */
     function ratifierData(params) {
-        const proof = params.tree.proof(params.leafIndex);
+        const { tree } = RatifierUtils.normalizeRatifierTree({
+            tree: params.tree,
+            label: "Setter",
+        });
+        const proof = TreeUtils.buildProof({ tree, leafIndex: params.leafIndex });
         return encodeRatifierData({
             root: proof.root,
             leafIndex: proof.leafIndex,
@@ -147,7 +157,7 @@ export var SetterRatifierUtils;
      * directly to `Payload.encode`. All offers in the tree must use one ratifier
      * address; build separate trees per ratifier.
      *
-     * @param params.tree - Setter-ratified offer tree whose root has already been approved onchain.
+     * @param params.tree - Setter-ratified offer tree-like input whose root has already been approved onchain.
      * @returns Items containing each offer and its ratifier data.
      * @throws {InvalidTreeError} when the tree is invalid or contains multiple ratifiers.
      * @example
@@ -158,12 +168,14 @@ export var SetterRatifierUtils;
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -187,23 +199,16 @@ export var SetterRatifierUtils;
      * ```
      */
     function ratify(params) {
-        const firstOffer = params.tree.offers[0];
-        if (firstOffer == null) {
-            throw new InvalidTreeError("Tree must contain at least one offer.");
-        }
-        const ratifier = firstOffer.ratifier;
-        const comparableRatifier = ratifier.toLowerCase();
-        for (const offer of params.tree.offers.slice(1)) {
-            if (offer.ratifier.toLowerCase() !== comparableRatifier) {
-                throw new InvalidTreeError(`All offers in a Setter tree must use one ratifier; expected "${ratifier}", got "${offer.ratifier}". Build separate trees per ratifier.`);
-            }
-        }
+        const { tree } = RatifierUtils.normalizeRatifierTree({
+            tree: params.tree,
+            label: "Setter",
+        });
         const items = [];
-        for (const offer of params.tree.offers) {
+        for (const offer of tree.offers) {
             items.push({
                 offer,
                 ratifierData: ratifierData({
-                    tree: params.tree,
+                    tree,
                     leafIndex: items.length,
                 }),
             });

package/lib/esm/signatures/Tree.d.ts

@@ -1,9 +1,9 @@
 import type { BigIntish } from "@morpho-org/morpho-ts";
 import type { Hash } from "viem";
-import type { MempoolPayloadValidationResult } from "../api/types.js";
+import type { MempoolPayloadValidationSuccess } from "../api/types.js";
 import { Offer, type OfferStruct } from "../offers/index.js";
 import { type TreeCreateParams, type TreeInput, type TreeMempoolValidateParams, type TreeProof } from "./TreeUtils.js";
-export type { TreeCreateParams, TreeDescriptor, TreeInput, TreeMempoolValidateParams, TreeProof, TreeUtilsMempoolValidateParams, } from "./TreeUtils.js";
+export type { RatifierTreeInput, TreeCreateParams, TreeDescriptor, TreeInput, TreeLike, TreeMempoolValidateParams, TreeMempoolValidateRatification, TreeProof, } from "./TreeUtils.js";
 /**
  * Maker-side Merkle tree used by Midnight ratifiers.
  *
@@ -18,12 +18,14 @@ export type { TreeCreateParams, TreeDescriptor, TreeInput, TreeMempoolValidatePa
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -73,12 +75,14 @@ export declare class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -118,12 +122,14 @@ export declare class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -147,20 +153,23 @@ export declare class Tree {
     /**
      * Validates this 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 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 this tree.
      * @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.
-     * @throws {Payload.DecodeError} when validation payload encoding fails.
+     * @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 {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, Tree } from "@morpho-org/midnight-sdk";
@@ -168,12 +177,14 @@ export declare class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -189,13 +200,12 @@ export declare class Tree {
      *   ratifier: "0x0000000000000000000000000000000000004000",
      *   maxUnits: 100n,
      * });
-     * const validation = await Tree.create([offer]).mempoolValidate({
+     * await Tree.create([offer]).mempoolValidate({
      *   chainId: 8453,
      * });
-     * console.log(validation.valid);
      * ```
      */
-    mempoolValidate(params: TreeMempoolValidateParams): Promise<MempoolPayloadValidationResult>;
+    mempoolValidate(params: TreeMempoolValidateParams): Promise<MempoolPayloadValidationSuccess>;
     /**
      * Builds a Merkle proof for one leaf.
      *
@@ -212,12 +222,14 @@ export declare class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],

package/lib/esm/signatures/Tree.js

@@ -15,12 +15,14 @@ import { TreeUtils, } from "./TreeUtils.js";
  *
  * const offer = Offer.create({
  *   market: {
+ *     chainId: 8453,
+ *     midnight: "0x0000000000000000000000000000000000001000",
  *     loanToken: "0x0000000000000000000000000000000000006000",
  *     collateralParams: [
  *       {
  *         token: "0x0000000000000000000000000000000000007000",
  *         lltv: 770000000000000000n,
- *         maxLif: 1061007957559681697n,
+ *         liquidationCursor: 250000000000000000n,
  *         oracle: "0x0000000000000000000000000000000000008000",
  *       },
  *     ],
@@ -77,12 +79,14 @@ export class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -124,12 +128,14 @@ export class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -155,20 +161,23 @@ export class Tree {
     /**
      * Validates this 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 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 this tree.
      * @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.
-     * @throws {Payload.DecodeError} when validation payload encoding fails.
+     * @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 {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, Tree } from "@morpho-org/midnight-sdk";
@@ -176,12 +185,14 @@ export class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],
@@ -197,10 +208,9 @@ export class Tree {
      *   ratifier: "0x0000000000000000000000000000000000004000",
      *   maxUnits: 100n,
      * });
-     * const validation = await Tree.create([offer]).mempoolValidate({
+     * await Tree.create([offer]).mempoolValidate({
      *   chainId: 8453,
      * });
-     * console.log(validation.valid);
      * ```
      */
     mempoolValidate(params) {
@@ -225,12 +235,14 @@ export class Tree {
      *
      * const offer = Offer.create({
      *   market: {
+     *     chainId: 8453,
+     *     midnight: "0x0000000000000000000000000000000000001000",
      *     loanToken: "0x0000000000000000000000000000000000006000",
      *     collateralParams: [
      *       {
      *         token: "0x0000000000000000000000000000000000007000",
      *         lltv: 770000000000000000n,
-     *         maxLif: 1061007957559681697n,
+     *         liquidationCursor: 250000000000000000n,
      *         oracle: "0x0000000000000000000000000000000000008000",
      *       },
      *     ],