@morpho-org/midnight-sdk 1.7.0 → 2.0.0

package/lib/esm/signatures/Tree.js

@@ -1,13 +1,17 @@
-import { Offer } from "../offers/index.js";
-import { Group } from "./Group.js";
-import { GroupUtils } from "./GroupUtils.js";
+import { deepFreeze } from "@morpho-org/morpho-ts";
+import { InvalidTreeError } from "../errors.js";
+import { Offer, OfferUtils } from "../offers/index.js";
+import { PriceRatifierV1 } from "./PriceRatifierV1.js";
+import { RateRatifierV1 } from "./RateRatifierV1.js";
+import { Ratifier } from "./Ratifier.js";
 import { TreeUtils, } from "./TreeUtils.js";
 /**
  * Maker-side Merkle tree used by Midnight ratifiers.
  *
  * Build a tree after offers have been created and related offers have been
  * grouped. The tree root is what Ecrecover makers sign, Setter makers approve,
- * and payload items later prove with per-leaf ratifier data.
+ * and payload items later prove with per-leaf ratifier data. Price/Rate V1
+ * trees carry their additional leaf commitments and use onchain root approval.
  *
  * @example
  * ```ts
@@ -39,135 +43,144 @@ import { TreeUtils, } from "./TreeUtils.js";
  *   ratifier: "0x0000000000000000000000000000000000004000",
  *   maxUnits: 100n,
  * });
- * const tree = Tree.create([offer]);
+ * const tree = Tree.create({ type: "ecrecover", entries: [offer] });
  * console.log(tree.root);
  * ```
  */
 export class Tree {
+    /** Explicit route, or undefined for a legacy standard tree. */
+    type;
+    /** Complete padded leaf commitments for this route. */
+    entries;
     /** Non-padding offers in leaf order. */
     offers;
     /** ABI-compatible offers in leaf order, including protocol-zero padding. */
     paddedOffers;
-    /** Leaf hashes for `paddedOffers`. */
+    /** Leaf hashes for the complete padded `entries`. */
     leaves;
     /** Merkle root. */
     root;
     /** Tree height. */
     height;
-    constructor(params) {
-        this.offers = params.flatMap((entry) => GroupUtils.isGroupInput(entry)
-            ? Group.from(entry).offers
-            : [
-                new Offer({
-                    ...Offer.from(entry),
-                    group: GroupUtils.hash([entry]),
-                }),
-            ]);
-        const descriptor = TreeUtils.buildDescriptor(params);
-        this.paddedOffers = descriptor.offers;
-        this.leaves = descriptor.leaves;
+    constructor(type, descriptor) {
+        this.type = type;
+        this.offers = Object.freeze(descriptor.offers.map((offer) => Offer.from(offer)));
+        this.entries = deepFreeze(structuredClone(descriptor.entries));
+        const entries = this.entries;
+        this.paddedOffers = Object.freeze(entries.map((entry) => ("offer" in entry ? entry.offer : entry)));
+        this.leaves = Object.freeze([...descriptor.leaves]);
         this.root = descriptor.root;
         this.height = descriptor.height;
     }
-    /**
-     * Returns a tree instance from class or plain input.
-     *
-     * Use at boundaries that accept either a prebuilt tree or raw group/offer
-     * inputs, such as API validation helpers. Existing `Tree` instances are
-     * returned as-is.
-     *
-     * @param tree - Tree class or creation input.
-     * @returns Tree instance.
-     * @throws {InvalidTreeError} when the tree is empty, all padding, or duplicated.
-     * @throws {InvalidTreeHeightError} when the resulting height is unsupported.
-     * @example
-     * ```ts
-     * import { Offer, Tree } 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.from([offer]);
-     * console.log(tree.root);
-     * ```
-     */
     static from(tree) {
         if (tree instanceof Tree)
             return tree;
+        // Portable snapshots resume through descriptor validation instead of rebuilding.
+        if (!Array.isArray(tree) &&
+            "entries" in tree &&
+            "leaves" in tree &&
+            "root" in tree) {
+            return "type" in tree && tree.type != null
+                ? Tree.fromDescriptor(tree)
+                : Tree.fromDescriptor(tree);
+        }
+        if ("type" in tree && tree.type != null)
+            return Tree.create(tree);
         return Tree.create(Array.isArray(tree) ? tree : [tree]);
     }
+    static create(params) {
+        if ("type" in params) {
+            const descriptor = TreeUtils.buildDescriptor(params);
+            switch (descriptor.type) {
+                case "ecrecover":
+                    return new Tree("ecrecover", descriptor);
+                case "setter":
+                    return new Tree("setter", descriptor);
+                case "priceV1":
+                    return new Tree("priceV1", descriptor);
+                case "rateV1":
+                    return new Tree("rateV1", descriptor);
+            }
+        }
+        const offers = TreeUtils.normalizeEntries(params);
+        const descriptor = TreeUtils.buildDescriptor(params);
+        return new Tree(undefined, {
+            ...descriptor,
+            offers,
+            entries: descriptor.offers,
+        });
+    }
     /**
-     * Creates a tree from groups or standalone offers.
-     *
-     * Use after `Offer.create` and optional `Group.create`, before
-     * `Tree.mempoolValidate`, `EcrecoverRatifierUtils.ratify`, or
-     * `SetterRatifierUtils.ratify`. Groups are flattened, and every standalone
-     * offer is normalized as a singleton group using the router-compatible group
-     * id algorithm.
-     *
-     * @param params - Groups or standalone offers in leaf order.
-     * @returns Tree instance.
-     * @throws {InvalidTreeError} when the tree is empty, all padding, or duplicated.
-     * @throws {InvalidTreeHeightError} when the resulting height is unsupported.
+     * Exports plain normalized data for transport; does not claim root authorization.
+     * @returns Descriptor with the same route and padded commitments.
      * @example
      * ```ts
-     * import { Offer, Tree } 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]);
-     * console.log(tree.height);
+     * import { Tree, type IOffer } from "@morpho-org/midnight-sdk";
+     * function prepare(offers: readonly IOffer[]) {
+     *   return Tree.create({ type: "setter", entries: offers }).toDescriptor();
+     * }
      * ```
      */
-    static create(params) {
-        return new Tree(params);
+    toDescriptor() {
+        return deepFreeze({
+            type: this.type,
+            entries: [...this.entries],
+            offers: this.paddedOffers.slice(0, this.offers.length),
+            leaves: [...this.leaves],
+            root: this.root,
+            height: this.height,
+        });
+    }
+    static fromDescriptor(descriptor) {
+        switch (descriptor.type) {
+            case "priceV1":
+                // Validate caller-controlled hashes, offers and padding before constructing an instance.
+                PriceRatifierV1.buildProof({ tree: descriptor, leafIndex: 0n });
+                return new Tree("priceV1", {
+                    ...descriptor,
+                    entries: descriptor.entries.map((entry, index) => ({
+                        allowedTaker: entry.allowedTaker,
+                        offer: index < descriptor.offers.length
+                            ? OfferUtils.toStruct({ offer: entry.offer })
+                            : entry.offer,
+                    })),
+                });
+            case "rateV1":
+                // Validate caller-controlled hashes, offers and padding before constructing an instance.
+                RateRatifierV1.buildProof({ tree: descriptor, leafIndex: 0n });
+                return new Tree("rateV1", {
+                    ...descriptor,
+                    entries: descriptor.entries.map((entry, index) => ({
+                        rate: entry.rate,
+                        allowedTaker: entry.allowedTaker,
+                        offer: index < descriptor.offers.length
+                            ? OfferUtils.toStruct({ offer: entry.offer })
+                            : entry.offer,
+                    })),
+                });
+            case "ecrecover":
+            case "setter":
+            case undefined: {
+                // Validate the complete standard offer commitment without reassigning groups.
+                Ratifier.normalizeRatifierTree({
+                    tree: { ...descriptor, paddedOffers: descriptor.entries },
+                    label: descriptor.type === "setter" ? "Setter" : "Ecrecover",
+                });
+                const normalized = {
+                    ...descriptor,
+                    entries: descriptor.entries.map((offer, index) => index < descriptor.offers.length
+                        ? OfferUtils.toStruct({ offer })
+                        : offer),
+                };
+                if (descriptor.type === "ecrecover")
+                    return new Tree("ecrecover", normalized);
+                if (descriptor.type === "setter")
+                    return new Tree("setter", normalized);
+                return new Tree(undefined, normalized);
+            }
+            default:
+                throw new InvalidTreeError("Unsupported tree ratifier route.");
+        }
     }
     /**
      * Validates this tree against Midnight mempool API policy.
@@ -176,15 +189,18 @@ export class Tree {
      * 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`.
+     * `ratifierData`. Price/Rate V1 routes always post their real ratifier data
+     * because the router decodes it to identify each offer; their
+     * `ratification` only asserts the route.
      *
      * @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.
-     * @param params.ratification - Optional ratification inputs used to validate final payload bytes with real ratifier data.
+     * @param params.ratification - Optional route-matching authorization inputs; Price/Rate routes require their root to have been approved onchain.
      * @returns Successful API validation result with `valid: true`.
+     * @throws {InvalidTreeError} when the ratification route differs from the tree route.
      * @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.
@@ -219,15 +235,34 @@ export class Tree {
      *   ratifier: "0x0000000000000000000000000000000000004000",
      *   maxUnits: 100n,
      * });
-     * await Tree.create([offer]).mempoolValidate({
+     * await Tree.create({ type: "ecrecover", entries: [offer] }).mempoolValidate({
      *   chainId: 8453,
      * });
      * ```
      */
-    mempoolValidate(params) {
+    async mempoolValidate(params) {
+        const descriptor = this.toDescriptor();
+        if (params.ratification != null &&
+            (this.type == null
+                ? params.ratification.type !== "ecrecover" &&
+                    params.ratification.type !== "setter"
+                : params.ratification.type !== this.type)) {
+            throw new InvalidTreeError("Ratification route does not match the tree route.");
+        }
+        if (this.type === "priceV1" || this.type === "rateV1") {
+            return TreeUtils.mempoolValidate({
+                ...params,
+                tree: descriptor,
+            });
+        }
         return TreeUtils.mempoolValidate({
             ...params,
-            tree: this,
+            ratification: params.ratification,
+            tree: Tree.fromDescriptor({
+                ...descriptor,
+                type: undefined,
+                entries: this.paddedOffers,
+            }),
         });
     }
     /**

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

@@ -1,10 +1,11 @@
 import { type BigIntish } from "@morpho-org/morpho-ts";
 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 IOffer, Offer, type OfferStruct } from "../offers/index.js";
+import { type EcrecoverSignatureInput } from "./EcrecoverRatifier.js";
 import { type GroupInput } from "./GroupUtils.js";
-import type { Tree } from "./Tree.js";
+import { Tree } from "./Tree.js";
+import type { AnyTreeSnapshot, EcrecoverTreeCreateRequest, TreeCreateRequest, TreeSnapshot } from "./treeTypes.js";
 /**
  * Fully materialized tree descriptor.
  *
@@ -105,7 +106,9 @@ export interface TreeProof {
     readonly proof: readonly Hash[];
 }
 /**
- * Entries accepted by {@link Tree.create}.
+ * Legacy untagged entries accepted by {@link Tree.create}.
+ *
+ * @deprecated Use EcrecoverTreeCreateRequest or SetterTreeCreateRequest with an explicit type and entries.
  *
  * Entries are either explicit groups or standalone offers. Explicit groups are
  * flattened, and standalone offers are hashed with their own group ids.
@@ -146,7 +149,7 @@ export interface TreeProof {
  * console.log(tree.root);
  * ```
  */
-export type TreeCreateParams = readonly GroupInput[];
+export type TreeCreateParams = EcrecoverTreeCreateRequest["entries"];
 /**
  * Plain creation input or class tree accepted by {@link Tree.from}.
  *
@@ -291,7 +294,9 @@ export type RatifierTreeInput = TreeLike | TreeInput;
  * 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.
+ * Setter root is ready for publication. Price/Rate V1 routes always post real
+ * ratifier data because the router identifies each offer from its decoded
+ * leaf fields; their `ratification` is only a route assertion.
  *
  * @example
  * ```ts
@@ -327,14 +332,23 @@ export type TreeMempoolValidateRatification = {
 } | {
     /** Setter ratifier route. */
     readonly type: "setter";
+} | {
+    /** PriceRatifierV1 route assertion; validation always encodes its ratifier data. */
+    readonly type: "priceV1";
+} | {
+    /** RateRatifierV1 route assertion; validation always encodes its ratifier data. */
+    readonly type: "rateV1";
 };
 /**
  * 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.
+ * API. Standard routes validate the pre-ratification tree with empty
+ * `ratifierData` by default; pass `ratification` to validate the final
+ * payload shape with real ratifier data. Price/Rate V1 routes always encode
+ * real ratifier data (root, leaf index, proof, allowed taker, and the rate for
+ * RateRatifierV1) because the router identifies each offer by decoding it; their
+ * `ratification` only asserts the route.
  *
  * @example
  * ```ts
@@ -401,6 +415,27 @@ export interface TreeMempoolValidateParams {
  * ```
  */
 export declare namespace TreeUtils {
+    /**
+     * Normalizes legacy standard tree entries into grouped offers.
+     *
+     * Explicit groups are flattened into their member offers, and every
+     * standalone offer is normalized as a singleton group using the
+     * router-compatible `GroupUtils.hash` group id. Use this when you need the
+     * exact offer list a standard Ecrecover/Setter tree commits to.
+     *
+     * @param entries - Groups or standalone offers in leaf order.
+     * @returns Offers in leaf order with their committed group ids.
+     * @throws {InvalidOfferGroupError} when an explicit group entry violates group mechanics.
+     * @example
+     * ```ts
+     * import { TreeUtils, type TreeCreateParams } from "@morpho-org/midnight-sdk";
+     *
+     * function normalize(entries: TreeCreateParams) {
+     *   return TreeUtils.normalizeEntries(entries);
+     * }
+     * ```
+     */
+    function normalizeEntries(entries: TreeCreateParams): readonly Offer[];
     /**
      * Validates a tree against Midnight mempool API policy.
      *
@@ -408,17 +443,20 @@ export declare namespace TreeUtils {
      * 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`.
+     * `ratifierData`. Price/Rate V1 tree snapshots are supported directly and
+     * always post the corresponding V1 `ratify` output — there is no empty
+     * ratifier-data shape because the router decodes the leaf fields to identify
+     * each offer. A V1 `ratification` only asserts the matching route.
      *
      * @param params.chainId - Chain id whose API policy should validate the tree.
-     * @param params.tree - Offer tree to validate.
+     * @param params.tree - Offer tree or route-typed tree snapshot to validate. Serialized standard snapshots resume without rewriting committed groups.
      * @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.
-     * @param params.ratification - Optional ratification inputs used to validate final payload bytes with real ratifier data.
+     * @param params.ratification - Optional route-matching 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 {InvalidTreeError} when the tree is empty, all padding, or duplicated, or when `ratification` does not match the tree route.
      * @throws {InvalidTreeHeightError} when the resulting height is unsupported.
      * @throws {PayloadDecodeError} when validation payload encoding fails.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
@@ -461,7 +499,7 @@ export declare namespace TreeUtils {
      * ```
      */
     function mempoolValidate(params: Pick<TreeMempoolValidateParams, "chainId" | "apiUrl" | "timestamp" | "fetch" | "request"> & {
-        readonly tree: TreeInput;
+        readonly tree: TreeInput | TreeSnapshot<"ecrecover"> | TreeSnapshot<"setter"> | TreeSnapshot<"priceV1"> | TreeSnapshot<"rateV1">;
         readonly ratification?: TreeMempoolValidateRatification;
     }): Promise<MempoolPayloadValidationSuccess>;
     /**
@@ -493,10 +531,12 @@ export declare namespace TreeUtils {
      * `Tree.create` calls this internally and is the simpler API for most
      * make-side code.
      *
-     * @param entries - Groups or standalone offers in leaf order.
+     * @param entries - Tagged route and leaf inputs in leaf order.
      * @returns Tree descriptor.
      * @throws {InvalidTreeError} when the offer count is empty, all padding, or duplicated.
      * @throws {InvalidTreeHeightError} when the padded tree exceeds supported ratifier typehashes.
+     * @throws {InvalidRateRatifierV1RateError} when a Rate leaf has a negative rate.
+     * @throws {InvalidRateRatifierV1TickError} when a Rate leaf offer tick is below `RateRatifierV1.MIN_TICK`.
      * @example
      * ```ts
      * import { Offer, TreeUtils } from "@morpho-org/midnight-sdk";
@@ -527,10 +567,28 @@ export declare namespace TreeUtils {
      *   ratifier: "0x0000000000000000000000000000000000004000",
      *   maxUnits: 100n,
      * });
-     * const tree = TreeUtils.buildDescriptor([offer]);
+     * const tree = TreeUtils.buildDescriptor({ type: "ecrecover", entries: [offer] });
      * console.log(tree.root);
      * ```
      */
+    function buildDescriptor<R extends TreeCreateRequest>(entries: R): Extract<AnyTreeSnapshot, {
+        readonly type: R["type"];
+    }>;
+    /**
+     * Builds a descriptor using the legacy standard-offer input.
+     * @deprecated Pass a TreeCreateRequest with an explicit ratifier type instead.
+     * @param entries - Untagged offers or groups in leaf order.
+     * @returns Legacy padded standard-offer descriptor.
+     * @throws {InvalidTreeError} When entries are empty, all padding, or duplicated.
+     * @throws {InvalidTreeHeightError} When the tree height is unsupported.
+     * @example
+     * ```ts
+     * import { TreeUtils, type TreeCreateParams } from "@morpho-org/midnight-sdk";
+     * function legacyDescriptor(entries: TreeCreateParams) {
+     *   return TreeUtils.buildDescriptor(entries);
+     * }
+     * ```
+     */
     function buildDescriptor(entries: TreeCreateParams): TreeDescriptor;
     /**
      * Builds only the tree root.
@@ -577,18 +635,43 @@ export declare namespace TreeUtils {
      * console.log(root);
      * ```
      */
-    function buildRoot(entries: TreeCreateParams): `0x${string}`;
+    function buildRoot(entries: TreeCreateParams): Hash;
+    /**
+     * Builds a Merkle root from already-hashed leaves.
+     *
+     * Use this leaf-hash-agnostic form when a ratifier's leaves are not plain
+     * offer hashes, for example `RateRatifierV1.hashLeaf` outputs. The leaf
+     * count must be a power of two; pad non-power-of-two lists beforehand.
+     *
+     * @param leaves - Leaf hashes in leaf order; length must be a power of two.
+     * @returns Merkle root and tree height.
+     * @throws {InvalidTreeError} when the leaf count is not a power of two.
+     * @throws {InvalidTreeHeightError} when the tree exceeds supported ratifier typehashes.
+     * @example
+     * ```ts
+     * import { TreeUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroHash } from "viem";
+     *
+     * const { root, height } = TreeUtils.buildRootFromLeaves([zeroHash]);
+     * console.log(height);
+     * ```
+     */
+    function buildRootFromLeaves(leaves: readonly Hash[]): {
+        readonly root: Hash;
+        readonly height: number;
+    };
     /**
      * Builds a Merkle proof for one offer.
      *
-     * Use after tree construction when a custom ratifier needs one proof. The
-     * built-in Ecrecover and Setter helpers call this while generating
-     * `ratifierData`.
+     * Use after tree construction when a custom ratifier needs one proof; the
+     * built-in ratify helpers use {@link TreeUtils.buildProofs} to generate
+     * `ratifierData` in bulk.
      *
      * @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.
+     * @throws {InvalidTreeError} when leaf index is out of range or when the leaf count is not a power of two.
+     * @throws {InvalidTreeHeightError} when the tree height (log2 of the leaf count) exceeds 20.
      * @example
      * ```ts
      * import { Offer, Tree, TreeUtils } from "@morpho-org/midnight-sdk";
@@ -630,6 +713,60 @@ export declare namespace TreeUtils {
         readonly tree: Pick<TreeLike, "leaves" | "root">;
         readonly leafIndex: BigIntish;
     }): TreeProof;
+    /**
+     * Builds Merkle proofs for a range of leaves from one tree-layer pass.
+     *
+     * Use instead of calling {@link TreeUtils.buildProof} per leaf when many
+     * proofs are needed at once, for example inside `ratify` helpers: the
+     * parent layers are computed once instead of once per leaf. Each returned
+     * proof is byte-identical to `buildProof` on the same tree and leaf index.
+     *
+     * @param params.tree - Tree leaves and root to prove against.
+     * @param params.count - Number of leading leaf indices to prove; defaults to `tree.leaves.length`.
+     * @returns Frozen proofs for leaf indices `0` through `count - 1`.
+     * @throws {InvalidTreeError} when `count` is negative, non-integer, or exceeds the leaf count, or when the leaf count is not a power of two.
+     * @throws {InvalidTreeHeightError} when the tree height (log2 of the leaf count) exceeds 20.
+     * @example
+     * ```ts
+     * import { Offer, Tree, TreeUtils } 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 proofs = TreeUtils.buildProofs({
+     *   tree: Tree.create([offer]),
+     *   count: 1,
+     * });
+     * console.log(proofs[0]!.proof.length);
+     * ```
+     */
+    function buildProofs(params: {
+        readonly tree: Pick<TreeLike, "leaves" | "root">;
+        readonly count?: number;
+    }): readonly TreeProof[];
     /**
      * Verifies a local Merkle proof against a root.
      *
@@ -689,4 +826,37 @@ export declare namespace TreeUtils {
         readonly leafIndex: BigIntish;
         readonly proof: readonly Hash[];
     }): boolean;
+    /**
+     * Verifies a local Merkle proof for an already-hashed leaf against a root.
+     *
+     * Use this leaf-hash-agnostic form when a ratifier's leaves are not plain
+     * offer hashes, for example `RateRatifierV1.hashLeaf` outputs. The leaf
+     * index determines each sibling's left/right position, matching
+     * `HashLib.isLeaf` onchain.
+     *
+     * @param params.leaf - Leaf hash that starts proof reconstruction.
+     * @param params.root - Expected Merkle root.
+     * @param params.leafIndex - Leaf index proven by `params.proof`.
+     * @param params.proof - Merkle proof siblings for the leaf.
+     * @returns Whether the proof reconstructs the supplied root.
+     * @example
+     * ```ts
+     * import { TreeUtils } from "@morpho-org/midnight-sdk";
+     * import { zeroHash } from "viem";
+     *
+     * const valid = TreeUtils.verifyLeafProof({
+     *   leaf: zeroHash,
+     *   root: zeroHash,
+     *   leafIndex: 0n,
+     *   proof: [],
+     * });
+     * console.log(valid);
+     * ```
+     */
+    function verifyLeafProof(params: {
+        readonly leaf: Hash;
+        readonly root: Hash;
+        readonly leafIndex: BigIntish;
+        readonly proof: readonly Hash[];
+    }): boolean;
 }