@morpho-org/midnight-sdk 1.7.0 → 1.8.0

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

@@ -0,0 +1,472 @@
+import { type BigIntish } from "@morpho-org/morpho-ts";
+import { type Address, type Hash, type Hex } from "viem";
+import { type IOffer, type OfferStruct } from "../offers/index.js";
+import type { Payload } from "./Payload.js";
+import { type TreeProof } from "./TreeUtils.js";
+import type { TreeData, TreeSnapshot } from "./treeTypes.js";
+/**
+ * One PriceRatifierV1 offer leaf.
+ *
+ * `allowedTaker` optionally restricts the offer to one taker; omit it or pass
+ * the zero address to let anyone take.
+ *
+ * @example
+ * ```ts
+ * import type { IOffer, PriceRatifierV1Leaf } from "@morpho-org/midnight-sdk";
+ *
+ * function leaf(offer: IOffer): PriceRatifierV1Leaf {
+ *   return { offer };
+ * }
+ * ```
+ */
+export interface PriceRatifierV1Leaf {
+    /** Offer carried by the leaf; the offer's `ratifier` must be the PriceRatifierV1 address. */
+    readonly offer: IOffer;
+    /** Optional taker restriction; defaults to the zero address (any taker). */
+    readonly allowedTaker?: Address;
+}
+/**
+ * ABI-compatible PriceRatifierV1 leaf.
+ *
+ * @example
+ * ```ts
+ * import type { OfferStruct, PriceRatifierV1LeafStruct } from "@morpho-org/midnight-sdk";
+ * import { zeroAddress } from "viem";
+ *
+ * function leaf(offer: OfferStruct): PriceRatifierV1LeafStruct {
+ *   return { offer, allowedTaker: zeroAddress };
+ * }
+ * ```
+ */
+export interface PriceRatifierV1LeafStruct {
+    /** ABI-compatible offer. */
+    readonly offer: OfferStruct;
+    /** Taker restriction; the zero address means any taker. */
+    readonly allowedTaker: Address;
+}
+/**
+ * Fully materialized PriceRatifierV1 tree descriptor.
+ *
+ * Use this shape when a caller needs leaf structs, leaf hashes, root, and
+ * height, for example before custom signing or proof generation.
+ *
+ * @example
+ * ```ts
+ * import { PriceRatifierV1, type IOffer, type PriceRatifierV1TreeDescriptor } from "@morpho-org/midnight-sdk";
+ *
+ * function build(offer: IOffer): PriceRatifierV1TreeDescriptor {
+ *   return PriceRatifierV1.buildDescriptor([{ offer }]);
+ * }
+ * ```
+ */
+export interface PriceRatifierV1TreeDescriptor extends TreeData<PriceRatifierV1LeafStruct> {
+}
+/**
+ * Decoded PriceRatifierV1 ratifier data.
+ *
+ * Use this on the take-side or in diagnostics after `Payload.decode` when you
+ * need to inspect the proof and allowed taker attached to a
+ * PriceRatifierV1-ratified offer.
+ *
+ * @example
+ * ```ts
+ * import { PriceRatifierV1, type DecodedPriceRatifierV1Data } from "@morpho-org/midnight-sdk";
+ * import { zeroAddress, zeroHash } from "viem";
+ *
+ * const data = PriceRatifierV1.encodeRatifierData({
+ *   root: zeroHash,
+ *   leafIndex: 0n,
+ *   proof: [],
+ *   allowedTaker: zeroAddress,
+ * });
+ * const decoded: DecodedPriceRatifierV1Data =
+ *   PriceRatifierV1.decodeRatifierData(data);
+ * console.log(decoded.allowedTaker);
+ * ```
+ */
+export interface DecodedPriceRatifierV1Data extends TreeProof {
+    /** Taker restriction proven by the leaf; the zero address means any taker. */
+    readonly allowedTaker: Address;
+}
+/**
+ * Tree-like input accepted by PriceRatifierV1 helpers.
+ *
+ * Both a {@link PriceRatifierV1TreeDescriptor} and raw leaf input are
+ * accepted; caller-provided descriptors are fully re-validated (leaf hashes
+ * and root recomputed) before use.
+ *
+ * @example
+ * ```ts
+ * import type { IOffer, PriceRatifierV1TreeInput } from "@morpho-org/midnight-sdk";
+ *
+ * function input(offer: IOffer): PriceRatifierV1TreeInput {
+ *   return [{ offer }];
+ * }
+ * ```
+ */
+export type PriceRatifierV1TreeInput = (PriceRatifierV1TreeDescriptor & {
+    readonly type?: undefined;
+}) | TreeSnapshot<"priceV1"> | readonly PriceRatifierV1Leaf[];
+/**
+ * PriceRatifierV1-specific pure utilities.
+ *
+ * Use this route when makers ratify a Merkle root of price-bounded offers
+ * onchain. The make-side sequence is: create offers with the PriceRatifierV1
+ * address, build the tree descriptor, ratify the root onchain (directly or
+ * through `setIsRootRatified`), then call `ratify` and pass the returned items
+ * to `Payload.encode`.
+ *
+ * @example
+ * ```ts
+ * import { PriceRatifierV1 } from "@morpho-org/midnight-sdk";
+ *
+ * console.log(typeof PriceRatifierV1.ratify);
+ * ```
+ */
+export declare namespace PriceRatifierV1 {
+    /**
+     * Computes the PriceRatifierV1 EIP-712 leaf hash for one leaf struct.
+     *
+     * This is the SDK port of `HashLib.hashPriceRatifierV1Offer`: the offer's
+     * `tick` is kept and `allowedTaker` is appended after it.
+     *
+     * @param leaf - ABI-compatible leaf to hash.
+     * @returns Leaf hash used in the ratified Merkle tree.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1, type OfferStruct } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * function hash(offer: OfferStruct) {
+     *   return PriceRatifierV1.hashLeaf({
+     *     offer,
+     *     allowedTaker: zeroAddress,
+     *   });
+     * }
+     * ```
+     */
+    function hashLeaf(leaf: PriceRatifierV1LeafStruct): Hash;
+    /**
+     * Zero-group member hash of one leaf, as consumed by `GroupUtils.hashMembers`.
+     *
+     * This is what the router recomputes for its `group_identity` check: the
+     * PriceRatifierV1 leaf hash with `group = 0`, so the id also commits to
+     * `allowedTaker`.
+     *
+     * @param leaf - Price-committed offer leaf.
+     * @returns Zero-group PriceRatifierV1 leaf hash.
+     * @example
+     * ```ts
+     * import { Offer, PriceRatifierV1 } 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: "0x000000000000000000000000000000000000a111",
+     *   maxUnits: 100n,
+     * });
+     *
+     * console.log(PriceRatifierV1.memberHash({ offer }));
+     * ```
+     */
+    function memberHash(leaf: PriceRatifierV1Leaf): Hash;
+    /**
+     * Content-addressed consumption group id for PriceRatifierV1 leaves.
+     *
+     * Mirrors `GroupUtils.hash` with the PriceRatifierV1 {@link memberHash}, so
+     * it matches the router-derived group. Use it to share one group across
+     * several leaves; single leaves get this id by default in
+     * {@link buildDescriptor}. Leaves sharing a group must satisfy the same
+     * constraints as `Group.create` (one maker, side, and cap mode/value); this
+     * helper only derives the id and does not check them.
+     *
+     * @param leaves - Leaves sharing one consumption group.
+     * @returns Content-addressed group id.
+     * @throws {InvalidOfferGroupError} when `leaves` is empty.
+     * @example
+     * ```ts
+     * import { Offer, PriceRatifierV1 } 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: "0x000000000000000000000000000000000000a111",
+     *   maxUnits: 100n,
+     * });
+     * const leaves = [{ offer }, { offer: Offer.from({ ...offer, tick: 5_004n }) }];
+     *
+     * const group = PriceRatifierV1.groupId(leaves);
+     * const grouped = leaves.map((leaf) => ({
+     *   ...leaf,
+     *   offer: Offer.from({ ...leaf.offer, group }),
+     * }));
+     * ```
+     */
+    function groupId(leaves: Iterable<PriceRatifierV1Leaf>): Hash;
+    /**
+     * Builds a PriceRatifierV1 tree descriptor from leaf input.
+     *
+     * Non-power-of-two leaf lists are padded with protocol-zero leaves at the
+     * highest leaf indices. A group matching the generic content id of all
+     * leaves sharing it (for example from `OfferUtils.toStruct` or
+     * `Group.create`) is re-derived with {@link groupId}; other explicit groups
+     * are committed as-is. An omitted `group` defaults to the leaf's
+     * content-addressed singleton {@link groupId}, which commits to
+     * `allowedTaker` like the router does.
+     *
+     * @param leaves - Price-bounded offer leaves in leaf order.
+     * @returns PriceRatifierV1 tree descriptor.
+     * @throws {InvalidTreeError} when the leaf list is empty, contains duplicate leaf hashes, or mixes ratifier addresses.
+     * @throws {InvalidTreeHeightError} when the padded tree exceeds supported ratifier typehashes.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1, type IOffer } from "@morpho-org/midnight-sdk";
+     *
+     * function build(offer: IOffer) {
+     *   return PriceRatifierV1.buildDescriptor([{ offer }]);
+     * }
+     * ```
+     */
+    function buildDescriptor(leaves: readonly PriceRatifierV1Leaf[]): PriceRatifierV1TreeDescriptor;
+    /**
+     * Builds a Merkle proof for one PriceRatifierV1 leaf.
+     *
+     * @param params.tree - PriceRatifierV1 tree descriptor or raw leaf input.
+     * @param params.leafIndex - Leaf index to prove.
+     * @returns Proof descriptor.
+     * @throws {InvalidTreeError} when the tree is invalid or the leaf index is out of range.
+     * @throws {InvalidTreeHeightError} when the tree exceeds the supported height.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1, type IOffer } from "@morpho-org/midnight-sdk";
+     *
+     * function build(offer: IOffer) {
+     *   return PriceRatifierV1.buildProof({
+     *     tree: PriceRatifierV1.buildDescriptor([{ offer }]),
+     *     leafIndex: 0n,
+     *   });
+     * }
+     * ```
+     */
+    function buildProof(params: {
+        readonly tree: PriceRatifierV1TreeInput;
+        readonly leafIndex: BigIntish;
+    }): TreeProof;
+    /**
+     * Encodes PriceRatifierV1 ratifier data.
+     *
+     * Use only when you already have a root, proof, and allowed taker. Most
+     * maker flows call `ratifierData` for one leaf or `ratify` for every leaf
+     * in the ratified tree.
+     *
+     * @param params.root - Merkle root ratified by the maker's PriceRatifierV1.
+     * @param params.leafIndex - Leaf index proven by `params.proof`.
+     * @param params.proof - Merkle proof siblings for the leaf.
+     * @param params.allowedTaker - Taker restriction carried by the leaf.
+     * @returns ABI-encoded ratifier data.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1 } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress, zeroHash } from "viem";
+     *
+     * const data = PriceRatifierV1.encodeRatifierData({
+     *   root: zeroHash,
+     *   leafIndex: 0n,
+     *   proof: [],
+     *   allowedTaker: zeroAddress,
+     * });
+     * console.log(data);
+     * ```
+     */
+    function encodeRatifierData(params: {
+        readonly root: Hash;
+        readonly leafIndex: BigIntish;
+        readonly proof: readonly Hash[];
+        readonly allowedTaker: Address;
+    }): `0x${string}`;
+    /**
+     * Decodes PriceRatifierV1 ratifier data.
+     *
+     * Use on the take-side or in tests after `Payload.decode` to inspect the
+     * proof and allowed taker attached to a published offer.
+     *
+     * @param data - ABI-encoded ratifier data.
+     * @returns Decoded PriceRatifierV1 ratifier data.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1 } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress, zeroHash } from "viem";
+     *
+     * const decoded = PriceRatifierV1.decodeRatifierData(
+     *   PriceRatifierV1.encodeRatifierData({
+     *     root: zeroHash,
+     *     leafIndex: 0n,
+     *     proof: [],
+     *     allowedTaker: zeroAddress,
+     *   }),
+     * );
+     * console.log(decoded.allowedTaker);
+     * ```
+     */
+    function decodeRatifierData(data: Hex): DecodedPriceRatifierV1Data;
+    /**
+     * Verifies that PriceRatifierV1 ratifier data proves one payload offer
+     * belongs to its root.
+     *
+     * This helper intentionally does not check the onchain
+     * `PriceRatifierV1.ratification` state. Consumers can query that value at
+     * their own block context after local proof verification.
+     *
+     * @param params.offer - Offer carried by the payload item.
+     * @param params.ratifierData - ABI-encoded PriceRatifierV1 ratifier data.
+     * @param params.taker - Optional taker to check against the leaf's allowed taker.
+     * @returns Decoded PriceRatifierV1 ratifier data after proof verification.
+     * @throws {InvalidTreeError} when the proof does not include `offer` in `root`.
+     * @throws {RatifierV1TakerNotAllowedError} when `taker` is not the leaf's allowed taker.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1, type IOffer } from "@morpho-org/midnight-sdk";
+     * import type { Hex } from "viem";
+     *
+     * function check(offer: IOffer, ratifierData: Hex) {
+     *   return PriceRatifierV1.verifyRatifierData({ offer, ratifierData });
+     * }
+     * ```
+     */
+    function verifyRatifierData(params: {
+        readonly offer: IOffer;
+        readonly ratifierData: Hex;
+        readonly taker?: Address;
+    }): DecodedPriceRatifierV1Data;
+    /**
+     * Builds one ratifier-data value for a tree leaf.
+     *
+     * Use after root ratification when a caller needs data for one offer leaf.
+     * Use `ratify` to produce payload-ready items for the whole tree.
+     *
+     * @param params.tree - PriceRatifierV1 tree descriptor or raw leaf input.
+     * @param params.leafIndex - Leaf index to prove.
+     * @returns ABI-encoded PriceRatifierV1 data.
+     * @throws {InvalidTreeError} when the tree is invalid, the leaf index is outside the tree, or the tree contains multiple ratifiers.
+     * @throws {InvalidTreeHeightError} when the tree exceeds the supported height.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1, type IOffer } from "@morpho-org/midnight-sdk";
+     *
+     * function build(offer: IOffer) {
+     *   return PriceRatifierV1.ratifierData({
+     *     tree: [{ offer }],
+     *     leafIndex: 0n,
+     *   });
+     * }
+     * ```
+     */
+    function ratifierData(params: {
+        readonly tree: PriceRatifierV1TreeInput;
+        readonly leafIndex: BigIntish;
+    }): Hex;
+    /**
+     * Returns payload-ready items after a PriceRatifierV1 root has been ratified.
+     *
+     * Use after the root ratification transaction has been submitted for every
+     * maker in the tree. The returned items can be passed directly to
+     * `Payload.encode`. All offers in the tree must use one ratifier address;
+     * build separate trees per ratifier.
+     *
+     * @param params.tree - PriceRatifierV1 tree descriptor or raw leaf input whose root has already been ratified onchain.
+     * @returns Items containing each non-padding offer and its ratifier data.
+     * @throws {InvalidTreeError} when the tree is invalid or contains multiple ratifiers.
+     * @throws {InvalidTreeHeightError} when the tree exceeds the supported height.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1, type IOffer } from "@morpho-org/midnight-sdk";
+     *
+     * function build(offer: IOffer) {
+     *   return PriceRatifierV1.ratify({
+     *     tree: [{ offer }],
+     *   });
+     * }
+     * ```
+     */
+    function ratify(params: {
+        readonly tree: PriceRatifierV1TreeInput;
+    }): readonly Payload.Item[];
+    /**
+     * Encodes a `setIsRootRatified` call to a PriceRatifierV1 contract.
+     *
+     * Onchain, the caller must be the maker or an address authorized by the
+     * maker on the Midnight instance. The returned descriptor is neutral and
+     * never signs or submits anything.
+     *
+     * @param params.ratifier - PriceRatifierV1 contract address.
+     * @param params.maker - Maker whose ratification entry is updated.
+     * @param params.root - Merkle root to ratify or unratify.
+     * @param params.isRatified - New ratification flag for the root.
+     * @returns Neutral call descriptor.
+     * @throws {InvalidRatifierV1AddressError} when the ratifier address is the zero address.
+     * @example
+     * ```ts
+     * import { PriceRatifierV1 } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress, zeroHash } from "viem";
+     *
+     * const call = PriceRatifierV1.encodeSetIsRootRatified({
+     *   ratifier: "0x0000000000000000000000000000000000000001",
+     *   maker: zeroAddress,
+     *   root: zeroHash,
+     *   isRatified: true,
+     * });
+     * console.log(call.to);
+     * ```
+     */
+    function encodeSetIsRootRatified(params: {
+        readonly ratifier: Address;
+        readonly maker: Address;
+        readonly root: Hash;
+        readonly isRatified: boolean;
+    }): {
+        to: `0x${string}`;
+        data: `0x${string}`;
+    };
+}
+/** @deprecated Use {@link PriceRatifierV1}. Retained for compatibility. */
+export { PriceRatifierV1 as PriceRatifierV1Utils };