@morpho-org/midnight-sdk 0.1.0

package/lib/cjs/signatures/Payload.js

@@ -0,0 +1,570 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecodeError = exports.MAX_REQUEST_BODY_BYTES = exports.MAX_PAYLOAD_HEX_LENGTH = exports.MAX_DECOMPRESSED_ITEMS_BYTES = exports.MAX_COMPRESSED_ITEMS_BYTES = exports.MAX_PAYLOAD_BYTES = exports.MAX_ATTRIBUTION_SUFFIX_BYTES = exports.CURRENT_VERSION = void 0;
+exports.encode = encode;
+exports.decode = decode;
+const morpho_ts_1 = require("@morpho-org/morpho-ts");
+const viem_1 = require("viem");
+const constants_js_1 = require("../constants.js");
+const errors_js_1 = require("../errors.js");
+const index_js_1 = require("../market/index.js");
+const index_js_2 = require("../offers/index.js");
+/**
+ * Current Midnight mempool payload wire version.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.CURRENT_VERSION);
+ * ```
+ */
+exports.CURRENT_VERSION = 1;
+const VERSION_PREFIX_BYTES = 1;
+const LENGTH_PREFIX_BYTES = 4;
+const HEADER_BYTES = VERSION_PREFIX_BYTES + LENGTH_PREFIX_BYTES;
+/**
+ * Upper bound on opaque bytes appended after the gzip stream (e.g. an app
+ * attribution tag). The suffix is meant to be small, so `decode` rejects a
+ * larger one: this keeps the `MAX_PAYLOAD_BYTES` ceiling meaningful for the
+ * whole input. Without it a tiny declared `gzipLen` could smuggle an
+ * arbitrarily large suffix past validation and into the indexer while still
+ * forcing the API to receive and hex-decode the whole blob.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.MAX_ATTRIBUTION_SUFFIX_BYTES);
+ * ```
+ */
+exports.MAX_ATTRIBUTION_SUFFIX_BYTES = 256;
+/**
+ * Largest fully framed wire payload, in bytes, matching the router/onchain
+ * mempool cap.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.MAX_PAYLOAD_BYTES);
+ * ```
+ */
+exports.MAX_PAYLOAD_BYTES = 1_000_000;
+/**
+ * Maximum gzip-compressed item bytes accepted by the payload codec.
+ *
+ * The budget reserves room for the fixed header and the largest accepted
+ * attribution suffix so the full wire payload never exceeds
+ * {@link MAX_PAYLOAD_BYTES}.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.MAX_COMPRESSED_ITEMS_BYTES);
+ * ```
+ */
+exports.MAX_COMPRESSED_ITEMS_BYTES = exports.MAX_PAYLOAD_BYTES - HEADER_BYTES - exports.MAX_ATTRIBUTION_SUFFIX_BYTES;
+/**
+ * Maximum ABI-decoded item bytes accepted by the payload codec.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.MAX_DECOMPRESSED_ITEMS_BYTES);
+ * ```
+ */
+exports.MAX_DECOMPRESSED_ITEMS_BYTES = 6_000_000;
+const ABI_ARRAY_HEAD_BYTES = 64;
+const ABI_LENGTH_LOW_OFFSET = 60;
+const MAX_TIMESTAMP_SECONDS = 1000000000000n - 1n;
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * Largest `0x`-prefixed hex string that can encode a wire payload.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.MAX_PAYLOAD_HEX_LENGTH);
+ * ```
+ */
+exports.MAX_PAYLOAD_HEX_LENGTH = "0x".length + exports.MAX_PAYLOAD_BYTES * 2;
+/**
+ * Largest inbound HTTP request body, in bytes, accepted by the API and
+ * gatekeeper APIs.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.MAX_REQUEST_BODY_BYTES);
+ * ```
+ */
+exports.MAX_REQUEST_BODY_BYTES = exports.MAX_PAYLOAD_HEX_LENGTH + 1_024;
+const offerStructAbiComponents = [
+    {
+        name: "market",
+        type: "tuple",
+        components: [
+            { name: "loanToken", type: "address" },
+            {
+                name: "collateralParams",
+                type: "tuple[]",
+                components: [
+                    { name: "token", type: "address" },
+                    { name: "lltv", type: "uint256" },
+                    { name: "maxLif", type: "uint256" },
+                    { name: "oracle", type: "address" },
+                ],
+            },
+            { name: "maturity", type: "uint256" },
+            { name: "rcfThreshold", type: "uint256" },
+            { name: "enterGate", type: "address" },
+            { name: "liquidatorGate", type: "address" },
+        ],
+    },
+    { name: "buy", type: "bool" },
+    { name: "maker", type: "address" },
+    { name: "start", type: "uint256" },
+    { name: "expiry", type: "uint256" },
+    { name: "tick", type: "uint256" },
+    { name: "group", type: "bytes32" },
+    { name: "callback", type: "address" },
+    { name: "callbackData", type: "bytes" },
+    { name: "receiverIfMakerIsSeller", type: "address" },
+    { name: "ratifier", type: "address" },
+    { name: "reduceOnly", type: "bool" },
+    { name: "maxUnits", type: "uint256" },
+    { name: "maxAssets", type: "uint256" },
+    { name: "continuousFeeCap", type: "uint256" },
+];
+const itemsAbi = [
+    {
+        name: "items",
+        type: "tuple[]",
+        components: [
+            { name: "offer", type: "tuple", components: offerStructAbiComponents },
+            { name: "ratifierData", type: "bytes" },
+        ],
+    },
+];
+/**
+ * ABI-encode `items` as `(Offer, bytes ratifierData)[]` and gzip the result,
+ * then emit the wire payload `version || uint32(gzipLen) || gzip(...)`. The
+ * single-byte version prefix lets future formats coexist on the wire; the
+ * 4-byte big-endian length delimits the gzip stream so `decode` finds its end
+ * without scanning. That delimiter is what lets a publisher append a small
+ * opaque suffix (e.g. an attribution tag) after the gzip stream — `decode`
+ * ignores up to `MAX_ATTRIBUTION_SUFFIX_BYTES` bytes past `gzipLen` and rejects
+ * a larger suffix. Item order is preserved verbatim and is the order a consumer
+ * sees on decode.
+ *
+ * Use after ratifier utilities have produced payload-ready items and before an
+ * onchain mempool submission. Normal SDK maker flows should validate the tree
+ * with `Tree.mempoolValidate` before ratification; use
+ * `MidnightApi.validateMempoolPayload` only when validating already encoded
+ * payload bytes.
+ *
+ * @param items - Per-leaf items in the order the maker committed to. Must
+ *   contain at least one item and fit within payload byte-size limits.
+ * @returns The encoded payload as a `Hex` string, ready to include in onchain
+ *   mempool submission calldata.
+ * @throws {DecodeError} when the item list is empty, encoding or compression
+ *   exceeds SDK byte-size limits, or a non-empty offer fails payload validation
+ *   for collateral requirements, maturity timing, expiry range, tick bounds, or
+ *   `maxUnits`/`maxAssets` cap shape.
+ * @example
+ * ```ts
+ * import { Offer, Payload } 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 encoded = await Payload.encode([{ offer, ratifierData: "0x" }]);
+ * console.log(encoded);
+ * ```
+ */
+async function encode(items) {
+    if (exports.CURRENT_VERSION > 0xff) {
+        throw new DecodeError(`version overflow: ${exports.CURRENT_VERSION} exceeds 255`);
+    }
+    assertNonEmptyItemCount(items.length);
+    const payloadItems = items.map((item) => {
+        const offer = index_js_2.OfferUtils.toStruct({ offer: item.offer });
+        assertApiValidOfferStruct(offer);
+        return {
+            offer,
+            ratifierData: item.ratifierData,
+        };
+    });
+    const itemBytes = (0, viem_1.hexToBytes)((0, viem_1.encodeAbiParameters)(itemsAbi, [payloadItems]));
+    const compressed = await compressItemsPayload(itemBytes);
+    const encoded = new Uint8Array(HEADER_BYTES + compressed.length);
+    encoded[0] = exports.CURRENT_VERSION;
+    new DataView(encoded.buffer, encoded.byteOffset, encoded.byteLength).setUint32(VERSION_PREFIX_BYTES, compressed.length);
+    encoded.set(compressed, HEADER_BYTES);
+    return (0, viem_1.bytesToHex)(encoded);
+}
+/**
+ * Parse a wire payload back into its `(offer, ratifierData)` items. The version
+ * byte is validated against `CURRENT_VERSION` and not surfaced — any payload
+ * that decodes successfully is on the current wire format. The 4-byte length
+ * prefix bounds the gzip stream; up to `MAX_ATTRIBUTION_SUFFIX_BYTES` bytes
+ * after it (e.g. an attribution suffix appended by the publishing app) are
+ * ignored, so a tagged payload decodes identically to an untagged one. A larger
+ * trailing suffix is rejected so an oversized blob cannot ride a small payload
+ * past validation and into the indexer.
+ *
+ * Use on the take-side, in indexers, or in diagnostics when you need to inspect
+ * the offer structs and ratifier data that a maker published.
+ *
+ * @param payload - Hex payload bytes to decode.
+ * @param options - Optional decode bounds.
+ * @returns The decoded items in encoded order.
+ * @throws {DecodeError} when the payload is malformed or exceeds protocol limits.
+ * @example
+ * ```ts
+ * import { Offer, Payload } 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 encoded = await Payload.encode([{ offer, ratifierData: "0x" }]);
+ * const items = await Payload.decode(encoded);
+ * console.log(items.length);
+ * ```
+ */
+async function decode(payload, options) {
+    const maxItems = resolveMaxItems(options?.maxItems);
+    if (payload.length > exports.MAX_PAYLOAD_HEX_LENGTH) {
+        throw new DecodeError(`payload hex exceeds ${exports.MAX_PAYLOAD_HEX_LENGTH} characters`);
+    }
+    const bytes = (0, viem_1.hexToBytes)(payload);
+    if (bytes.length < HEADER_BYTES) {
+        throw new DecodeError("payload too short for header");
+    }
+    const version = bytes[0];
+    if (version !== (exports.CURRENT_VERSION & 0xff)) {
+        throw new DecodeError(`invalid version: expected ${exports.CURRENT_VERSION}, got ${version}`);
+    }
+    const compressedLength = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(VERSION_PREFIX_BYTES);
+    const compressedEnd = HEADER_BYTES + compressedLength;
+    if (compressedEnd > bytes.length) {
+        throw new DecodeError("payload truncated before declared gzip length");
+    }
+    const suffixLength = bytes.length - compressedEnd;
+    if (suffixLength > exports.MAX_ATTRIBUTION_SUFFIX_BYTES) {
+        throw new DecodeError(`trailing suffix exceeds ${exports.MAX_ATTRIBUTION_SUFFIX_BYTES} bytes: got ${suffixLength}`);
+    }
+    const compressed = bytes.subarray(HEADER_BYTES, compressedEnd);
+    const decoded = await decompressItemsPayload(compressed);
+    assertAbiItemCountWithinCallerLimit(decoded, maxItems);
+    const items = decodeItemsBytes(decoded);
+    assertNonEmptyItemCount(items.length);
+    assertCallerItemCountLimit(items.length, maxItems);
+    assertCanonicalItemsBytes(items, decoded);
+    return items;
+}
+function decodeItemsBytes(decoded) {
+    let raw;
+    try {
+        [raw] = (0, viem_1.decodeAbiParameters)(itemsAbi, (0, viem_1.bytesToHex)(decoded));
+    }
+    catch (error) {
+        throw new DecodeError("items abi decode failed", error instanceof Error ? error : undefined);
+    }
+    try {
+        return raw.map((entry) => {
+            assertApiValidOfferStruct(entry.offer);
+            return {
+                offer: index_js_2.Offer.from(entry.offer),
+                ratifierData: entry.ratifierData,
+            };
+        });
+    }
+    catch (error) {
+        if (error instanceof DecodeError)
+            throw error;
+        if (error instanceof Error) {
+            throw new DecodeError(`invalid offer bytes: ${error.message}`, error);
+        }
+        throw error;
+    }
+}
+function assertCanonicalItemsBytes(items, decoded) {
+    const canonical = (0, viem_1.encodeAbiParameters)(itemsAbi, [
+        items.map((item) => ({
+            offer: index_js_2.OfferUtils.toStruct({ offer: item.offer }),
+            ratifierData: item.ratifierData,
+        })),
+    ]);
+    if (canonical !== (0, viem_1.bytesToHex)(decoded)) {
+        throw new DecodeError("items payload has non-canonical ABI bytes");
+    }
+}
+function assertApiValidOfferStruct(offer) {
+    if (isEmptyOfferStruct(offer))
+        return;
+    assertCollateralParams(offer);
+    assertSafeTimestamp("market.maturity", offer.market.maturity);
+    assertMaturityAt15Utc(offer.market.maturity);
+    assertSafeTimestamp("start", offer.start);
+    assertSafeTimestamp("expiry", offer.expiry);
+    assertApiValidOfferTimeRange(offer);
+    if (offer.buy && !isZeroAddress(offer.receiverIfMakerIsSeller)) {
+        throw new DecodeError("invalid offer bytes: receiverIfMakerIsSeller must be zero for buy offers");
+    }
+    if (offer.expiry > offer.market.maturity) {
+        throw new DecodeError("invalid offer bytes: expiry must be before or equal to maturity");
+    }
+    if (offer.tick > constants_js_1.MAX_TICK) {
+        throw new DecodeError(`invalid offer bytes: tick exceeds maximum ${constants_js_1.MAX_TICK}`);
+    }
+    if ((offer.maxUnits === 0n) === (offer.maxAssets === 0n)) {
+        throw new DecodeError("invalid offer bytes: exactly one of maxUnits and maxAssets must be non-zero");
+    }
+    if (offer.continuousFeeCap < 0n) {
+        throw new DecodeError("invalid offer bytes: continuousFeeCap must be non-negative");
+    }
+}
+function assertApiValidOfferTimeRange(offer) {
+    try {
+        index_js_2.OfferUtils.validateOfferTimeRange(offer);
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.InvalidOfferParameterError) {
+            throw new DecodeError(`invalid offer bytes: ${error.message}`, error);
+        }
+        throw error;
+    }
+}
+function assertCollateralParams(offer) {
+    const collateralParams = offer.market.collateralParams;
+    if (collateralParams.length === 0) {
+        throw new DecodeError("invalid offer bytes: at least one collateral required");
+    }
+    if (collateralParams.length > Number(constants_js_1.MAX_COLLATERALS)) {
+        throw new DecodeError(`invalid offer bytes: market.collateralParams has ${collateralParams.length} collaterals, exceeding the maximum of ${constants_js_1.MAX_COLLATERALS}`);
+    }
+    let previousToken;
+    for (const params of collateralParams) {
+        if (params.lltv < 0n || params.lltv > morpho_ts_1.MathLib.WAD) {
+            throw new DecodeError(`invalid offer bytes: collateral lltv must be between 0 and WAD, got ${params.lltv}`);
+        }
+        const lowMaxLif = index_js_1.MarketUtils.getLiquidationIncentiveFactor(params, constants_js_1.LIQUIDATION_CURSOR_LOW);
+        const highMaxLif = index_js_1.MarketUtils.getLiquidationIncentiveFactor(params, constants_js_1.LIQUIDATION_CURSOR_HIGH);
+        if (params.maxLif !== lowMaxLif && params.maxLif !== highMaxLif) {
+            throw new DecodeError(`invalid offer bytes: invalid collateral maxLif ${params.maxLif}`);
+        }
+        const token = params.token.toLowerCase();
+        if (isZeroAddress(token)) {
+            throw new DecodeError("invalid offer bytes: collateral token must be non-zero");
+        }
+        if (previousToken != null && previousToken >= token) {
+            throw new DecodeError("invalid offer bytes: collaterals must be sorted and unique");
+        }
+        previousToken = token;
+    }
+}
+function assertSafeTimestamp(field, value) {
+    if (value > MAX_TIMESTAMP_SECONDS) {
+        throw new DecodeError(`invalid offer bytes: ${field} exceeds ${MAX_TIMESTAMP_SECONDS}`);
+    }
+}
+function assertMaturityAt15Utc(value) {
+    const date = new Date(Number(value) * 1000);
+    if (date.getUTCHours() !== 15 ||
+        date.getUTCMinutes() !== 0 ||
+        date.getUTCSeconds() !== 0 ||
+        date.getUTCMilliseconds() !== 0) {
+        throw new DecodeError("invalid offer bytes: maturity must be at 15:00:00 UTC");
+    }
+}
+function isEmptyOfferStruct(offer) {
+    return (isZeroAddress(offer.market.loanToken) &&
+        offer.market.collateralParams.length === 0 &&
+        offer.market.maturity === 0n &&
+        offer.market.rcfThreshold === 0n &&
+        isZeroAddress(offer.market.enterGate) &&
+        isZeroAddress(offer.market.liquidatorGate) &&
+        offer.buy === false &&
+        isZeroAddress(offer.maker) &&
+        offer.start === 0n &&
+        offer.expiry === 0n &&
+        offer.tick === 0n &&
+        offer.group === ZERO_BYTES32 &&
+        isZeroAddress(offer.callback) &&
+        offer.callbackData === "0x" &&
+        isZeroAddress(offer.receiverIfMakerIsSeller) &&
+        isZeroAddress(offer.ratifier) &&
+        offer.reduceOnly === false &&
+        offer.maxUnits === 0n &&
+        offer.maxAssets === 0n &&
+        offer.continuousFeeCap === 0n);
+}
+function isZeroAddress(value) {
+    return value.toLowerCase() === ZERO_ADDRESS;
+}
+function resolveMaxItems(maxItems) {
+    if (maxItems === undefined)
+        return undefined;
+    if (!Number.isInteger(maxItems) || maxItems < 1) {
+        throw new DecodeError(`maxItems must be a positive integer: got ${maxItems}`);
+    }
+    return maxItems;
+}
+function assertNonEmptyItemCount(count) {
+    if (count === 0)
+        throw new DecodeError("items payload is empty");
+}
+function assertCallerItemCountLimit(count, maxItems) {
+    if (maxItems === undefined)
+        return;
+    if (count > maxItems) {
+        throw new DecodeError(`items payload exceeds ${maxItems} items`);
+    }
+}
+async function compressItemsPayload(payload) {
+    if (payload.length > exports.MAX_DECOMPRESSED_ITEMS_BYTES) {
+        throw new DecodeError(`decompressed items exceed ${exports.MAX_DECOMPRESSED_ITEMS_BYTES} bytes`);
+    }
+    let compressed;
+    try {
+        const stream = singleChunkStream(payload).pipeThrough(new CompressionStream("gzip"));
+        compressed = new Uint8Array(await new Response(stream).arrayBuffer());
+    }
+    catch (error) {
+        throw new DecodeError("compression failed", error instanceof Error ? error : undefined);
+    }
+    if (compressed.length > exports.MAX_COMPRESSED_ITEMS_BYTES) {
+        throw new DecodeError(`compressed items exceed ${exports.MAX_COMPRESSED_ITEMS_BYTES} bytes`);
+    }
+    return compressed;
+}
+async function decompressItemsPayload(compressed) {
+    if (compressed.length === 0)
+        throw new DecodeError("decompression failed");
+    if (compressed.length > exports.MAX_COMPRESSED_ITEMS_BYTES) {
+        throw new DecodeError(`compressed items exceed ${exports.MAX_COMPRESSED_ITEMS_BYTES} bytes`);
+    }
+    const reader = singleChunkStream(compressed)
+        .pipeThrough(new DecompressionStream("gzip"))
+        .getReader();
+    const chunks = [];
+    let totalLength = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            totalLength += value.length;
+            if (totalLength > exports.MAX_DECOMPRESSED_ITEMS_BYTES) {
+                await reader.cancel();
+                throw new DecodeError(`decompressed items exceed ${exports.MAX_DECOMPRESSED_ITEMS_BYTES} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        if (error instanceof DecodeError)
+            throw error;
+        throw new DecodeError("decompression failed", error instanceof Error ? error : undefined);
+    }
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}
+function singleChunkStream(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(new Uint8Array(bytes));
+            controller.close();
+        },
+    });
+}
+function assertAbiItemCountWithinCallerLimit(decoded, maxItems) {
+    if (decoded.length < ABI_ARRAY_HEAD_BYTES) {
+        throw new DecodeError("items payload truncated before ABI array head");
+    }
+    if (maxItems === undefined)
+        return;
+    for (let i = 32; i < ABI_LENGTH_LOW_OFFSET; i++) {
+        if (decoded[i] !== 0) {
+            throw new DecodeError(`items payload exceeds ${maxItems} items`);
+        }
+    }
+    const length = new DataView(decoded.buffer, decoded.byteOffset, decoded.byteLength).getUint32(ABI_LENGTH_LOW_OFFSET);
+    if (length > maxItems) {
+        throw new DecodeError(`items payload exceeds ${maxItems} items`);
+    }
+}
+/**
+ * Error thrown when a Midnight mempool payload cannot be decoded.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * throw new Payload.DecodeError("payload too short for header");
+ * ```
+ */
+class DecodeError extends Error {
+    /** Machine-readable decode failure reason without the class message prefix. */
+    reason;
+    constructor(reason, cause) {
+        super(`Failed to decode payload: ${reason}`, cause ? { cause } : undefined);
+        this.name = "Payload.DecodeError";
+        this.reason = reason;
+    }
+}
+exports.DecodeError = DecodeError;

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

@@ -0,0 +1,109 @@
+import type { Address, Hex } from "viem";
+/**
+ * Parameters for {@link RatifierUtils.getRatifierInfo}.
+ *
+ * Pass the maker account bytecode read at the same block context used to build
+ * the offer. The bytecode is used only to choose the ratifier address to put on
+ * the offer.
+ *
+ * @example
+ * ```ts
+ * import type { GetRatifierInfoParams } from "@morpho-org/midnight-sdk";
+ *
+ * const params: GetRatifierInfoParams = {
+ *   bytecode: "0x",
+ *   ecrecoverRatifier: "0x0000000000000000000000000000000000000001",
+ *   setterRatifier: "0x0000000000000000000000000000000000000002",
+ * };
+ * console.log(params.bytecode);
+ * ```
+ */
+export interface GetRatifierInfoParams {
+    /** Maker account bytecode returned by viem `getBytecode`; `undefined`, `null`, and `0x` mean no deployed code. */
+    readonly bytecode?: Hex | null;
+    /** Ecrecover ratifier address. */
+    readonly ecrecoverRatifier: Address;
+    /** Setter ratifier address. */
+    readonly setterRatifier: Address;
+}
+/**
+ * Classification of the ratifier route for a maker account.
+ *
+ * Put `ratifier` on each new `Offer.create` call for this maker. Use `type` to
+ * decide whether the tree later needs an Ecrecover signature or a Setter root
+ * approval before payload encoding.
+ *
+ * @example
+ * ```ts
+ * import type { RatifierInfo } from "@morpho-org/midnight-sdk";
+ *
+ * const info: RatifierInfo = {
+ *   type: "ecrecover",
+ *   ratifier: "0x0000000000000000000000000000000000000001",
+ * };
+ * ```
+ */
+export interface RatifierInfo {
+    /** Ratifier family selected for the maker account. */
+    readonly type: "ecrecover" | "setter";
+    /** Ratifier contract address to put on the offer. */
+    readonly ratifier: Address;
+}
+/**
+ * Utilities for selecting Midnight ratifier routes.
+ *
+ * Call these during make-side preparation, before `Offer.create`, when an app
+ * must decide whether a maker can sign an Ecrecover root or must approve a
+ * Setter root onchain. Fetch helpers read bytecode for you; this namespace is
+ * the pure classification logic.
+ *
+ * @example
+ * ```ts
+ * import { RatifierUtils } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(RatifierUtils.isEip7702Designator("0xef0100"));
+ * ```
+ */
+export declare namespace RatifierUtils {
+    /**
+     * Checks whether bytecode is an EIP-7702 designator.
+     *
+     * EIP-7702 accounts have code-like bytecode but still sign as the owning EOA,
+     * so they use the Ecrecover ratifier route instead of the Setter route.
+     *
+     * @param bytecode - Account bytecode.
+     * @returns Whether the bytecode starts with `0xef0100`.
+     * @example
+     * ```ts
+     * import { RatifierUtils } from "@morpho-org/midnight-sdk";
+     *
+     * console.log(RatifierUtils.isEip7702Designator("0xef0100"));
+     * ```
+     */
+    function isEip7702Designator(bytecode: Hex): boolean;
+    /**
+     * Selects Ecrecover for EOAs/EIP-7702 accounts and Setter for deployed-code
+     * accounts.
+     *
+     * Use the returned `ratifier` address in `Offer.create`. Later, use
+     * `EcrecoverRatifierUtils.ratify` when `type` is `ecrecover`, or approve the
+     * root and call `SetterRatifierUtils.ratify` when `type` is `setter`.
+     *
+     * @param params.bytecode - Maker bytecode returned by `eth_getCode`.
+     * @param params.ecrecoverRatifier - Ratifier address used for EOAs and EIP-7702 accounts.
+     * @param params.setterRatifier - Ratifier address used for deployed-code accounts.
+     * @returns Ratifier information for the maker.
+     * @example
+     * ```ts
+     * import { RatifierUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const info = RatifierUtils.getRatifierInfo({
+     *   bytecode: "0x",
+     *   ecrecoverRatifier: "0x0000000000000000000000000000000000000001",
+     *   setterRatifier: "0x0000000000000000000000000000000000000002",
+     * });
+     * console.log(info.type);
+     * ```
+     */
+    function getRatifierInfo(params: GetRatifierInfoParams): RatifierInfo;
+}