@morpho-org/midnight-sdk 0.1.0

package/lib/cjs/signatures/TreeUtils.js

@@ -0,0 +1,461 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeUtils = void 0;
+const morpho_ts_1 = require("@morpho-org/morpho-ts");
+const viem_1 = require("viem");
+const MidnightApi_js_1 = require("../api/MidnightApi.js");
+const errors_js_1 = require("../errors.js");
+const index_js_1 = require("../offers/index.js");
+const Group_js_1 = require("./Group.js");
+const GroupUtils_js_1 = require("./GroupUtils.js");
+const Payload_js_1 = require("./Payload.js");
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+const EMPTY_OFFER_STRUCT = {
+    market: {
+        loanToken: ZERO_ADDRESS,
+        collateralParams: [],
+        maturity: 0n,
+        rcfThreshold: 0n,
+        enterGate: ZERO_ADDRESS,
+        liquidatorGate: ZERO_ADDRESS,
+    },
+    buy: false,
+    maker: ZERO_ADDRESS,
+    start: 0n,
+    expiry: 0n,
+    tick: 0n,
+    group: ZERO_BYTES32,
+    callback: ZERO_ADDRESS,
+    callbackData: "0x",
+    receiverIfMakerIsSeller: ZERO_ADDRESS,
+    ratifier: ZERO_ADDRESS,
+    reduceOnly: false,
+    maxUnits: 0n,
+    maxAssets: 0n,
+    continuousFeeCap: 0n,
+};
+const EMPTY_OFFER_DEFAULT_GROUP = index_js_1.OfferUtils.hashStruct(EMPTY_OFFER_STRUCT);
+function isEmptyOfferStruct(offer) {
+    return (offer.market.loanToken === ZERO_ADDRESS &&
+        offer.market.collateralParams.length === 0 &&
+        offer.market.maturity === 0n &&
+        offer.market.rcfThreshold === 0n &&
+        offer.market.enterGate === ZERO_ADDRESS &&
+        offer.market.liquidatorGate === ZERO_ADDRESS &&
+        offer.buy === false &&
+        offer.maker === ZERO_ADDRESS &&
+        offer.start === 0n &&
+        offer.expiry === 0n &&
+        offer.tick === 0n &&
+        (offer.group === ZERO_BYTES32 ||
+            offer.group === EMPTY_OFFER_DEFAULT_GROUP) &&
+        offer.callback === ZERO_ADDRESS &&
+        offer.callbackData === "0x" &&
+        offer.receiverIfMakerIsSeller === ZERO_ADDRESS &&
+        offer.ratifier === ZERO_ADDRESS &&
+        offer.reduceOnly === false &&
+        offer.maxUnits === 0n &&
+        offer.maxAssets === 0n &&
+        offer.continuousFeeCap === 0n);
+}
+function isPowerOfTwo(value) {
+    return value > 0 && (value & (value - 1)) === 0;
+}
+function nextPowerOfTwo(value) {
+    return 2 ** Math.ceil(Math.log2(value));
+}
+function padOfferStructs(offers) {
+    if (isPowerOfTwo(offers.length))
+        return [...offers];
+    const paddedLength = nextPowerOfTwo(offers.length);
+    return [
+        ...offers,
+        ...Array.from({ length: paddedLength - offers.length }, () => EMPTY_OFFER_STRUCT),
+    ];
+}
+function assertLeafOffers(offers, leafHashes) {
+    const seen = new Set();
+    for (const [index, offer] of offers.entries()) {
+        if (isEmptyOfferStruct(offer))
+            continue;
+        const leafHash = leafHashes[index];
+        if (seen.has(leafHash)) {
+            throw new errors_js_1.InvalidTreeError(`Duplicate offer hash "${leafHash}" in tree.`);
+        }
+        seen.add(leafHash);
+    }
+    if (seen.size === 0) {
+        throw new errors_js_1.InvalidTreeError("Tree must not be empty.");
+    }
+}
+/**
+ * Object-compatible tree hashing, root, proof, and verification helpers.
+ *
+ * Use these when you need pure tree hashing, descriptor construction, or proof
+ * verification. In the normal make-side flow, `Tree.create` wraps descriptor
+ * construction; proof helpers accept the built `Tree` so cached leaves/root are
+ * reused.
+ *
+ * @example
+ * ```ts
+ * import { TreeUtils } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(typeof TreeUtils.buildRoot);
+ * ```
+ */
+var TreeUtils;
+(function (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.
+     *
+     * @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.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 {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 {MidnightApiError} when the API returns a non-2xx response.
+     * @throws {InvalidMidnightApiResponseError} when the API returns malformed success JSON.
+     * @example
+     * ```ts
+     * import { Offer, TreeUtils } 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 validation = await TreeUtils.mempoolValidate({
+     *   chainId: 8453,
+     *   tree: [offer],
+     * });
+     * console.log(validation.valid);
+     * ```
+     */
+    async function mempoolValidate(params) {
+        const offers = "offers" in params.tree
+            ? params.tree.offers
+            : params.tree.flatMap((entry) => "offers" in entry ? Group_js_1.Group.from(entry).offers : [index_js_1.Offer.from(entry)]);
+        buildDescriptor(offers);
+        const payload = await (0, Payload_js_1.encode)(offers.map((offer) => ({ offer, ratifierData: "0x" })));
+        return MidnightApi_js_1.MidnightApi.validateMempoolPayload({
+            baseUrl: params.apiUrl,
+            fetch: params.fetch,
+            request: params.request,
+            chainId: params.chainId,
+            timestamp: params.timestamp,
+            payload,
+        });
+    }
+    TreeUtils.mempoolValidate = mempoolValidate;
+    /**
+     * Computes HashLib node hash from left and right child hashes.
+     *
+     * @param left - Left child hash.
+     * @param right - Right child hash.
+     * @returns Node hash.
+     * @example
+     * ```ts
+     * import { TreeUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const root = TreeUtils.hashNode(
+     *   "0x0000000000000000000000000000000000000000000000000000000000000000",
+     *   "0x0000000000000000000000000000000000000000000000000000000000000000",
+     * );
+     * console.log(root);
+     * ```
+     */
+    function hashNode(left, right) {
+        return (0, viem_1.keccak256)((0, viem_1.concat)([left, right]));
+    }
+    TreeUtils.hashNode = hashNode;
+    /**
+     * Builds a tree descriptor and Merkle root. Non-power-of-two batches are
+     * padded with protocol-zero offers at the highest leaf indices.
+     *
+     * Use after `Group.create` or standalone `Offer.create` when you need the
+     * padded leaves for custom signing, root approval, or proof construction.
+     * Groups are encoded with their derived shared group id, and standalone
+     * offers are encoded with their own group id.
+     * `Tree.create` calls this internally and is the simpler API for most
+     * make-side code.
+     *
+     * @param entries - Groups or standalone offers 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.
+     * @example
+     * ```ts
+     * import { Offer, TreeUtils } 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 tree = TreeUtils.buildDescriptor([offer]);
+     * console.log(tree.root);
+     * ```
+     */
+    function buildDescriptor(entries) {
+        const structs = entries.flatMap((entry) => "offers" in entry
+            ? GroupUtils_js_1.GroupUtils.toStructs(entry)
+            : [index_js_1.OfferUtils.toStruct({ offer: entry })]);
+        if (structs.length === 0) {
+            throw new errors_js_1.InvalidTreeError("Tree must not be empty.");
+        }
+        const offerStructs = padOfferStructs(structs);
+        const leaves = offerStructs.map(index_js_1.OfferUtils.hashStruct);
+        assertLeafOffers(offerStructs, leaves);
+        const height = Math.log2(offerStructs.length);
+        if (height > 20)
+            throw new errors_js_1.InvalidTreeHeightError(height);
+        let level = [...leaves];
+        while (level.length > 1) {
+            const next = [];
+            for (let i = 0; i < level.length; i += 2) {
+                next.push(hashNode(level[i], level[i + 1]));
+            }
+            level = next;
+        }
+        return (0, morpho_ts_1.deepFreeze)({
+            offers: offerStructs,
+            leaves,
+            root: level[0],
+            height,
+        });
+    }
+    TreeUtils.buildDescriptor = buildDescriptor;
+    /**
+     * Builds only the tree root.
+     *
+     * Use when only the root is needed, for example to compare a locally built
+     * tree with an approved root. Use `Tree.create` or `buildDescriptor` if later
+     * proof generation is required.
+     *
+     * @param entries - Groups or standalone offers in leaf order.
+     * @returns Merkle root.
+     * @throws {InvalidTreeError} when the offer count is empty, all padding, or duplicated.
+     * @throws {InvalidTreeHeightError} when the padded tree exceeds supported ratifier typehashes.
+     * @example
+     * ```ts
+     * import { Offer, TreeUtils } 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 root = TreeUtils.buildRoot([offer]);
+     * console.log(root);
+     * ```
+     */
+    function buildRoot(entries) {
+        return buildDescriptor(entries).root;
+    }
+    TreeUtils.buildRoot = buildRoot;
+    /**
+     * 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`.
+     *
+     * @param params.tree - Tree that contains the leaf.
+     * @param params.leafIndex - Leaf index to prove.
+     * @returns Proof descriptor.
+     * @throws {InvalidTreeError} when leaf index is out of range.
+     * @example
+     * ```ts
+     * import { Offer, Tree, TreeUtils } 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 proof = TreeUtils.buildProof({
+     *   tree: Tree.create([offer]),
+     *   leafIndex: 0n,
+     * });
+     * console.log(proof.proof.length);
+     * ```
+     */
+    function buildProof(params) {
+        const leafIndex = BigInt(params.leafIndex);
+        if (leafIndex < 0n ||
+            leafIndex >= BigInt(params.tree.paddedOffers.length)) {
+            throw new errors_js_1.InvalidTreeError(`Leaf index "${leafIndex}" is outside the tree.`);
+        }
+        let index = Number(leafIndex);
+        let level = [...params.tree.leaves];
+        const proof = [];
+        while (level.length > 1) {
+            proof.push(level[index ^ 1]);
+            const next = [];
+            for (let i = 0; i < level.length; i += 2) {
+                next.push(hashNode(level[i], level[i + 1]));
+            }
+            index = Math.floor(index / 2);
+            level = next;
+        }
+        return (0, morpho_ts_1.deepFreeze)({ root: params.tree.root, leafIndex, proof });
+    }
+    TreeUtils.buildProof = buildProof;
+    /**
+     * Verifies a local Merkle proof against a root.
+     *
+     * Use on the take-side or in tests to inspect decoded payload or ratifier
+     * data before forwarding it to a transaction builder. Onchain ratifiers still
+     * perform the authoritative verification.
+     *
+     * @param params.offer - Offer whose hash 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 { Offer, Tree, TreeUtils } 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 tree = Tree.create([offer]);
+     * const proof = tree.proof(0n);
+     * const valid = TreeUtils.verifyProof({
+     *   offer: tree.offers[0]!,
+     *   root: proof.root,
+     *   leafIndex: proof.leafIndex,
+     *   proof: proof.proof,
+     * });
+     * console.log(valid);
+     * ```
+     */
+    function verifyProof(params) {
+        const offer = index_js_1.Offer.from(params.offer);
+        let node = index_js_1.OfferUtils.hash(offer);
+        const leafIndex = BigInt(params.leafIndex);
+        if (leafIndex < 0n || leafIndex >> BigInt(params.proof.length) !== 0n) {
+            return false;
+        }
+        let remainingLeafIndex = leafIndex;
+        for (const sibling of params.proof) {
+            node =
+                (remainingLeafIndex & 1n) === 0n
+                    ? hashNode(node, sibling)
+                    : hashNode(sibling, node);
+            remainingLeafIndex >>= 1n;
+        }
+        return node === params.root;
+    }
+    TreeUtils.verifyProof = verifyProof;
+})(TreeUtils || (exports.TreeUtils = TreeUtils = {}));

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

@@ -0,0 +1,7 @@
+export * from "./EcrecoverRatifierUtils.js";
+export * from "./Group.js";
+export * from "./GroupUtils.js";
+export * from "./RatifierUtils.js";
+export * from "./SetterRatifierUtils.js";
+export * from "./Tree.js";
+export * from "./TreeUtils.js";

package/lib/cjs/signatures/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./EcrecoverRatifierUtils.js"), exports);
+__exportStar(require("./Group.js"), exports);
+__exportStar(require("./GroupUtils.js"), exports);
+__exportStar(require("./RatifierUtils.js"), exports);
+__exportStar(require("./SetterRatifierUtils.js"), exports);
+__exportStar(require("./Tree.js"), exports);
+__exportStar(require("./TreeUtils.js"), exports);