damm-sdk 1.4.18 → 1.4.21

package/src/integrations/wormhole/executor.quote.api.ts

@@ -0,0 +1,182 @@
+/**
+ * Client for the Wormhole Executor quote API.
+ *
+ * The executor framework is a permissionless off-chain relay network that
+ * delivers cross-chain messages signed by Wormhole guardians. Integrators
+ * fetch a signed quote from a relay provider before calling any `*WithExecutor`
+ * wrapper contract — the quote binds the cost of relaying on the destination
+ * chain, and the wrapper verifies the signature on-chain.
+ *
+ * Endpoints:
+ *   - Mainnet: https://executor.labsapis.com
+ *   - Testnet: https://executor-testnet.labsapis.com
+ *
+ * API reference: https://github.com/wormholelabs-xyz/example-messaging-executor
+ */
+
+import { bytesToBigInt, bytesToNumber, bytesToString, hexToBytes, size as hexSize, sliceHex } from "viem";
+import type { HexString } from "../../types";
+
+export const WORMHOLE_EXECUTOR_API_MAINNET = "https://executor.labsapis.com" as const;
+export const WORMHOLE_EXECUTOR_API_TESTNET = "https://executor-testnet.labsapis.com" as const;
+
+export type WormholeNetwork = "Mainnet" | "Testnet";
+
+export const getExecutorApiUrl = (network: WormholeNetwork = "Mainnet"): string =>
+    network === "Mainnet" ? WORMHOLE_EXECUTOR_API_MAINNET : WORMHOLE_EXECUTOR_API_TESTNET;
+
+// ─── POST /v0/quote ──────────────────────────────────────────────────────
+
+export type FetchQuoteArgs = Readonly<{
+    /** Source Wormhole chain ID (e.g. 2 for Ethereum). */
+    srcChain: number;
+    /** Destination Wormhole chain ID (e.g. 48 for Monad). */
+    dstChain: number;
+    /**
+     * Serialized relay instructions (version 0x01 + uint128 gasLimit +
+     * uint128 msgValue). Build via `buildRelayInstructions` in the NTT helpers.
+     */
+    relayInstructions: HexString;
+}>;
+
+export type QuoteResponse = Readonly<{
+    /** Signed quote bytes — pass verbatim as `executorArgs.signedQuote`. */
+    signedQuote: HexString;
+    /** Estimated relay cost in wei (as a decimal string). */
+    estimatedCost?: string;
+}>;
+
+/**
+ * Fetch a signed executor quote.
+ *
+ * @example
+ *   const quote = await fetchExecutorQuote({
+ *     srcChain: 2,
+ *     dstChain: 48,
+ *     relayInstructions: buildRelayInstructions({ gasLimit: 250000n, msgValue: 0n }),
+ *   });
+ *   const relayFee = BigInt(quote.estimatedCost!);
+ */
+export const fetchExecutorQuote = async (
+    args: FetchQuoteArgs,
+    network: WormholeNetwork = "Mainnet",
+): Promise<QuoteResponse> => {
+    const url = `${getExecutorApiUrl(network)}/v0/quote`;
+
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            srcChain: args.srcChain,
+            dstChain: args.dstChain,
+            relayInstructions: args.relayInstructions,
+        }),
+    });
+
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Wormhole executor quote API returned ${response.status} ${response.statusText}: ${body}`);
+    }
+
+    return (await response.json()) as QuoteResponse;
+};
+
+// ─── Signed quote parsing (EQ01 layout) ──────────────────────────────────
+
+/**
+ * A decoded EQ01 signed quote.
+ *
+ * Layout (165 bytes total):
+ *   [0-4)    prefix "EQ01"
+ *   [4-24)   quoterAddress (20 bytes)
+ *   [24-56)  payeeAddress  (32 bytes)
+ *   [56-58)  srcChain      (uint16 BE)
+ *   [58-60)  dstChain      (uint16 BE)
+ *   [60-68)  expiryTime    (uint64 BE)  — unix seconds
+ *   [68-76)  baseFee       (uint64 BE)
+ *   [76-84)  dstGasPrice   (uint64 BE)
+ *   [84-92)  srcPrice      (uint64 BE)
+ *   [92-100) dstPrice      (uint64 BE)
+ *   [100-165) signature    (65 bytes)
+ */
+export type ParsedSignedQuote = Readonly<{
+    prefix: "EQ01";
+    quoterAddress: HexString;
+    payeeAddress: HexString;
+    srcChain: number;
+    dstChain: number;
+    expiryTimeSeconds: bigint;
+    baseFee: bigint;
+    dstGasPrice: bigint;
+    srcPrice: bigint;
+    dstPrice: bigint;
+}>;
+
+/**
+ * Parse an EQ01 signed quote.
+ * @throws if the prefix is not "EQ01" or the byte length is wrong.
+ */
+export const parseSignedQuote = (signedQuote: HexString): ParsedSignedQuote => {
+    if (hexSize(signedQuote) !== 165) {
+        throw new Error(`parseSignedQuote: expected 165 bytes, got ${hexSize(signedQuote)}`);
+    }
+    const prefixBytes = hexToBytes(sliceHex(signedQuote, 0, 4));
+    const prefix = bytesToString(prefixBytes);
+    if (prefix !== "EQ01") {
+        throw new Error(`parseSignedQuote: invalid prefix '${prefix}', expected 'EQ01'`);
+    }
+    return Object.freeze({
+        prefix: "EQ01",
+        quoterAddress: sliceHex(signedQuote, 4, 24),
+        payeeAddress: sliceHex(signedQuote, 24, 56),
+        srcChain: bytesToNumber(hexToBytes(sliceHex(signedQuote, 56, 58))),
+        dstChain: bytesToNumber(hexToBytes(sliceHex(signedQuote, 58, 60))),
+        expiryTimeSeconds: bytesToBigInt(hexToBytes(sliceHex(signedQuote, 60, 68))),
+        baseFee: bytesToBigInt(hexToBytes(sliceHex(signedQuote, 68, 76))),
+        dstGasPrice: bytesToBigInt(hexToBytes(sliceHex(signedQuote, 76, 84))),
+        srcPrice: bytesToBigInt(hexToBytes(sliceHex(signedQuote, 84, 92))),
+        dstPrice: bytesToBigInt(hexToBytes(sliceHex(signedQuote, 92, 100))),
+    });
+};
+
+// ─── POST /v0/status/tx ──────────────────────────────────────────────────
+
+export type StatusResponse = Readonly<{
+    txHash: HexString;
+    chainId: number;
+    status: string;
+    blockNumber?: string;
+    blockTime?: string;
+    [k: string]: unknown;
+}>;
+
+/**
+ * Fetch the executor's view of a source-chain transaction.
+ * Returns an array with one entry per relay attempt.
+ */
+export const fetchExecutorTxStatus = async (
+    {
+        txHash,
+        chainId,
+    }: {
+        txHash: HexString;
+        /** Wormhole chain ID of the source chain. */
+        chainId: number;
+    },
+    network: WormholeNetwork = "Mainnet",
+): Promise<readonly StatusResponse[]> => {
+    const url = `${getExecutorApiUrl(network)}/v0/status/tx`;
+
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ txHash, chainId }),
+    });
+
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Wormhole executor status API returned ${response.status} ${response.statusText}: ${body}`);
+    }
+
+    return (await response.json()) as readonly StatusResponse[];
+};

package/src/integrations/wormhole/gmp.manager.abi.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal ABI for Wormhole `GmpManager` — the contract that orchestrates
+ * transceivers (Wormhole + any additional providers like Axelar) for
+ * `MultiTokenNTT` deployments.
+ *
+ * Mainnet: 0xc6793a32761a11e96c97A3D18fC6545ea931F0E9
+ * Monad:   0x92957b3D0CaB3eA7110fEd1ccc4eF564981a59Fc
+ *
+ * Only the view function we need: `quoteDeliveryPrice` returns per-transceiver
+ * delivery prices and the total (in wei of the source chain's native token).
+ */
+export default [
+    {
+        inputs: [
+            { name: "recipientChain", type: "uint16" },
+            { name: "transceiverInstructions", type: "bytes" },
+        ],
+        name: "quoteDeliveryPrice",
+        outputs: [
+            { name: "", type: "uint256[]" },
+            { name: "", type: "uint256" },
+        ],
+        stateMutability: "view",
+        type: "function",
+    },
+] as const;

package/src/integrations/wormhole/gmp.manager.ts

@@ -0,0 +1,129 @@
+import { ethers } from "ethers";
+import { concatHex, size as hexSize, toHex } from "viem";
+import gmpManagerAbi from "./gmp.manager.abi";
+import type { Address } from "viem";
+import type { Call, HexString, Unwrapable } from "../../types";
+import { createCall } from "../../types";
+
+const gmpManagerInterface = new ethers.utils.Interface(gmpManagerAbi as any);
+
+// ─── quoteDeliveryPrice(uint16 recipientChain, bytes transceiverInstructions) ──
+
+export type QuoteDeliveryPriceArgs = Readonly<{
+    /** Destination Wormhole chain ID. */
+    recipientChain: number;
+    /**
+     * Serialized transceiver instructions. The GmpManager decodes these to
+     * know which transceivers will be used and what fee caps apply.
+     * For Wormhole-only deployments pass `"0x00"` (0 instructions).
+     * For Monad's 2/2 (Wormhole + Axelar) pass an Axelar-instruction-carrying
+     * buffer (see `buildMonadDefaultTransceiverInstructions`).
+     */
+    transceiverInstructions: HexString;
+}>;
+
+/**
+ * Encode calldata for the view function
+ * `GmpManager.quoteDeliveryPrice(recipientChain, transceiverInstructions)`.
+ *
+ * Use this to query per-transceiver delivery fees + total via RPC.
+ */
+export const GmpManagerQuoteDeliveryPriceCalldata = (args: QuoteDeliveryPriceArgs): HexString => {
+    return gmpManagerInterface.encodeFunctionData("quoteDeliveryPrice", [
+        args.recipientChain,
+        args.transceiverInstructions,
+    ]) as HexString;
+};
+
+/**
+ * Build a Call for `GmpManager.quoteDeliveryPrice` (view, value=0).
+ */
+export const GmpManagerQuoteDeliveryPriceTrx = ({
+    gmpManagerAddress,
+    args,
+}: {
+    gmpManagerAddress: Address;
+    args: QuoteDeliveryPriceArgs;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: gmpManagerAddress,
+        data: GmpManagerQuoteDeliveryPriceCalldata(args),
+        value: 0n,
+    });
+};
+
+/**
+ * Decode the return data from a `quoteDeliveryPrice` eth_call.
+ *
+ * @returns tuple of (per-transceiver fees in wei, total fee in wei).
+ */
+export const decodeQuoteDeliveryPriceResult = (
+    resultHex: HexString,
+): { readonly perTransceiver: readonly bigint[]; readonly total: bigint } => {
+    const decoded = gmpManagerInterface.decodeFunctionResult("quoteDeliveryPrice", resultHex);
+    const perTransceiver: bigint[] = (decoded[0] as Array<{ toString(): string }>).map((v) => BigInt(v.toString()));
+    const total = BigInt((decoded[1] as { toString(): string }).toString());
+    return { perTransceiver, total };
+};
+
+// ─── Transceiver instruction encoding ──────────────────────────────────────
+
+/**
+ * Encode a single transceiver instruction.
+ *
+ * Format used by the Monad `MultiTokenNTT` deployment (verified on-chain
+ * against a successful reference transfer — note this uses a uint8 payload
+ * length, whereas Wormhole's standard NTT spec uses uint16):
+ *   `uint8 index | uint8 payloadLength | bytes payload`
+ */
+const encodeTransceiverInstruction = (index: number, payload: HexString): HexString => {
+    if (index < 0 || index > 0xff) throw new Error(`encodeTransceiverInstruction: index out of range: ${index}`);
+    const payloadLen = hexSize(payload);
+    if (payloadLen > 0xff)
+        throw new Error(`encodeTransceiverInstruction: payload length ${payloadLen} exceeds uint8 max`);
+    return concatHex([toHex(index, { size: 1 }), toHex(payloadLen, { size: 1 }), payload]) as HexString;
+};
+
+/**
+ * Encode a list of Wormhole NTT transceiver instructions.
+ *
+ * Output format: `uint8 numInstructions || concat(encodedInstructions)`.
+ */
+export const encodeTransceiverInstructions = (
+    instructions: readonly Readonly<{ index: number; payload: HexString }>[],
+): HexString => {
+    if (instructions.length > 0xff)
+        throw new Error(`encodeTransceiverInstructions: too many instructions: ${instructions.length}`);
+    return concatHex([
+        toHex(instructions.length, { size: 1 }),
+        ...instructions.map((i) => encodeTransceiverInstruction(i.index, i.payload)),
+    ]) as HexString;
+};
+
+/**
+ * Build transceiver instructions for Monad's MultiTokenNTT deployment.
+ *
+ * Monad uses a 2-of-2 transceiver stack:
+ *   - index 0: Wormhole guardians (1-byte enable flag payload)
+ *   - index 1: Axelar GMP (32-byte uint256 max-fee payload in native token wei)
+ *
+ * The Axelar max-fee acts as the upper bound the caller is willing to pay
+ * for Axelar's side of the relay — the GmpManager will revert with
+ * `DeliveryPaymentTooLow` if the current quote exceeds this cap.
+ *
+ * Set `axelarMaxFee` generously (e.g. 50e18 wei on Monad → Mainnet) to
+ * tolerate gas-price spikes between quote time and execution time.
+ */
+export const buildMonadDefaultTransceiverInstructions = ({
+    axelarMaxFee,
+}: {
+    /** Max Axelar fee in wei of the source chain's native token. */
+    axelarMaxFee: bigint;
+}): HexString => {
+    if (axelarMaxFee < 0n) throw new Error("buildMonadDefaultTransceiverInstructions: negative axelarMaxFee");
+    return encodeTransceiverInstructions([
+        { index: 0, payload: "0x01" as HexString },
+        { index: 1, payload: toHex(axelarMaxFee, { size: 32 }) as HexString },
+    ]);
+};

package/src/integrations/wormhole/index.ts

@@ -0,0 +1,68 @@
+export { default as WormholeMultiNttAbi } from "./wormhole.multi.ntt.abi";
+export { default as WormholeGmpManagerAbi } from "./gmp.manager.abi";
+export { default as WormholeTransceiverAbi } from "./wormhole.transceiver.abi";
+export {
+    GmpManagerQuoteDeliveryPriceCalldata,
+    GmpManagerQuoteDeliveryPriceTrx,
+    decodeQuoteDeliveryPriceResult,
+    encodeTransceiverInstructions,
+    buildMonadDefaultTransceiverInstructions,
+    type QuoteDeliveryPriceArgs,
+} from "./gmp.manager";
+export { WormholeReceiveMessageCalldata, wormholeReceiveMessageTrx } from "./wormhole.transceiver";
+export {
+    WORMHOLESCAN_API_MAINNET,
+    WORMHOLESCAN_API_TESTNET,
+    getWormholeScanApiUrl,
+    fetchWormholeVAA,
+    decodeVaaBase64,
+    normalizeEmitterForVaaLookup,
+    type WormholeNetworkEnv,
+    type VaaLookupArgs,
+    type VaaLookupResponse,
+} from "./wormhole.scan.api";
+export {
+    AXELAR_GMP_API_MAINNET,
+    AXELAR_GMP_API_TESTNET,
+    getAxelarGmpApiUrl,
+    fetchAxelarGmpStatus,
+    type AxelarNetwork,
+    type AxelarGmpStatus,
+} from "./axelar.gmp.api";
+export {
+    // Chain ID mapping
+    WORMHOLE_CHAIN_IDS,
+    getWormholeChainId,
+    // Byte helpers
+    addressToBytes32,
+    // Relay instructions
+    buildRelayInstructions,
+    DEFAULT_NTT_REDEMPTION_GAS_LIMIT,
+    // transfer()
+    WormholeTransferCalldata,
+    wormholeTransferTrx,
+    // calculateFee()
+    WormholeCalculateFeeCalldata,
+    // Composition helper
+    buildWormholeTransferArgsFromAvatar,
+    // Types
+    type ExecutorArgs,
+    type FeeArgs,
+    type WormholeTransferArgs,
+} from "./wormhole.multi.ntt";
+export {
+    // Executor API
+    WORMHOLE_EXECUTOR_API_MAINNET,
+    WORMHOLE_EXECUTOR_API_TESTNET,
+    getExecutorApiUrl,
+    fetchExecutorQuote,
+    fetchExecutorTxStatus,
+    // Signed quote parsing
+    parseSignedQuote,
+    // Types
+    type WormholeNetwork,
+    type FetchQuoteArgs,
+    type QuoteResponse,
+    type ParsedSignedQuote,
+    type StatusResponse,
+} from "./executor.quote.api";

package/src/integrations/wormhole/wormhole.multi.ntt.abi.ts

@@ -0,0 +1,68 @@
+/**
+ * Minimal ABI for Wormhole `MultiNTTWithExecutor` — the wrapper that bundles
+ * `MultiTokenNTT.transfer(...)` with automatic Executor-based relay.
+ *
+ * Mainnet: 0x03dB430D830601DB368991eE55DAa9A708df7912
+ * Monad:   0xFEA937F7124E19124671f1685671d3f04a9Af4E4
+ *
+ * Only the functions we actually call: transfer, calculateFee, executor, chainId.
+ */
+export default [
+    {
+        inputs: [
+            { name: "multiTokenNtt", type: "address" },
+            { name: "token", type: "address" },
+            { name: "amount", type: "uint256" },
+            { name: "recipientChain", type: "uint16" },
+            { name: "recipient", type: "bytes32" },
+            { name: "refundAddress", type: "bytes32" },
+            { name: "transceiverInstructions", type: "bytes" },
+            {
+                name: "executorArgs",
+                type: "tuple",
+                components: [
+                    { name: "value", type: "uint256" },
+                    { name: "refundAddress", type: "address" },
+                    { name: "signedQuote", type: "bytes" },
+                    { name: "instructions", type: "bytes" },
+                ],
+            },
+            {
+                name: "feeArgs",
+                type: "tuple",
+                components: [
+                    { name: "dbps", type: "uint16" },
+                    { name: "payee", type: "address" },
+                ],
+            },
+        ],
+        name: "transfer",
+        outputs: [{ name: "sequence", type: "uint64" }],
+        stateMutability: "payable",
+        type: "function",
+    },
+    {
+        inputs: [
+            { name: "amount", type: "uint256" },
+            { name: "dbps", type: "uint16" },
+        ],
+        name: "calculateFee",
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        inputs: [],
+        name: "executor",
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        inputs: [],
+        name: "chainId",
+        outputs: [{ name: "", type: "uint16" }],
+        stateMutability: "view",
+        type: "function",
+    },
+] as const;