@morpho-org/midnight-sdk 0.1.0

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

@@ -0,0 +1,283 @@
+import { type Hex } from "viem";
+import { type IOffer } from "../offers/index.js";
+/**
+ * One mempool payload item: a maker-side `Offer` together with the opaque
+ * `ratifierData` blob a taker hands to `Midnight.take(..., ratifierData)`.
+ *
+ * `ratifierData` is owned by the ratifier scheme the maker used (e.g.
+ * `EcrecoverRatifierUtils.ratifierData`). The payload codec treats it as
+ * opaque bytes — simulators that only need to forward `ratifierData` can
+ * stay completely ratifier-agnostic.
+ *
+ * Build items with `EcrecoverRatifierUtils.ratify` or
+ * `SetterRatifierUtils.ratify` after the tree is signed or approved, then pass
+ * the items to `Payload.encode` for publication.
+ *
+ * @example
+ * ```ts
+ * import { Offer, type 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 item: Payload.Item = {
+ *   offer,
+ *   ratifierData: "0x",
+ * };
+ * console.log(item.ratifierData);
+ * ```
+ */
+export type Item = {
+    /** Maker-side offer carried by the payload. */
+    readonly offer: IOffer;
+    /** Opaque ratifier data passed to `Midnight.take`. */
+    readonly ratifierData: Hex;
+};
+/**
+ * Current Midnight mempool payload wire version.
+ *
+ * @example
+ * ```ts
+ * import { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(Payload.CURRENT_VERSION);
+ * ```
+ */
+export declare const CURRENT_VERSION = 1;
+/**
+ * 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);
+ * ```
+ */
+export declare const 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);
+ * ```
+ */
+export declare const MAX_PAYLOAD_BYTES = 1000000;
+/**
+ * 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);
+ * ```
+ */
+export declare const MAX_COMPRESSED_ITEMS_BYTES: number;
+/**
+ * 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);
+ * ```
+ */
+export declare const MAX_DECOMPRESSED_ITEMS_BYTES = 6000000;
+/**
+ * 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);
+ * ```
+ */
+export declare const MAX_PAYLOAD_HEX_LENGTH: number;
+/**
+ * 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);
+ * ```
+ */
+export declare const MAX_REQUEST_BODY_BYTES: number;
+/**
+ * Optional decode bounds.
+ *
+ * @example
+ * ```ts
+ * import type { Payload } from "@morpho-org/midnight-sdk";
+ *
+ * const options: Payload.DecodeOptions = { maxItems: 16 };
+ * console.log(options.maxItems);
+ * ```
+ */
+export type DecodeOptions = {
+    /** Optional caller-provided item cap. */
+    readonly maxItems?: number;
+};
+/**
+ * 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);
+ * ```
+ */
+export declare function encode(items: readonly Item[]): Promise<Hex>;
+/**
+ * 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);
+ * ```
+ */
+export declare function decode(payload: Hex, options?: DecodeOptions): Promise<Item[]>;
+/**
+ * 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");
+ * ```
+ */
+export declare class DecodeError extends Error {
+    /** Machine-readable decode failure reason without the class message prefix. */
+    readonly reason: string;
+    constructor(reason: string, cause?: Error);
+}