damm-sdk 1.4.18 → 1.4.21

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

@@ -0,0 +1,259 @@
+import { ethers } from "ethers";
+import { concatHex, pad, toHex } from "viem";
+import wormholeMultiNttAbi from "./wormhole.multi.ntt.abi";
+import type { Address } from "viem";
+import type { Call, HexString, Unwrapable } from "../../types";
+import { createCall } from "../../types";
+
+const wormholeMultiNttInterface = new ethers.utils.Interface(wormholeMultiNttAbi as any);
+
+/**
+ * Wormhole uint16 chain IDs.
+ *
+ * Wormhole uses its own chain-ID space distinct from EVM chain IDs.
+ * Reference: https://wormhole.com/docs/products/reference/chain-ids/
+ */
+export const WORMHOLE_CHAIN_IDS: Readonly<Record<number, number>> = Object.freeze({
+    1: 2, // Ethereum Mainnet
+    143: 48, // Monad
+});
+
+/**
+ * Resolve the Wormhole chain ID for an EVM chain ID.
+ * @throws if the chain has no Wormhole chain ID registered.
+ */
+export const getWormholeChainId = (chainId: number): number => {
+    const whChainId = WORMHOLE_CHAIN_IDS[chainId];
+    if (whChainId === undefined) {
+        throw new Error(`Wormhole: No chain ID mapping for chainId ${chainId}`);
+    }
+    return whChainId;
+};
+
+/**
+ * Left-pad a 20-byte address to bytes32 (the standard ABI encoding used
+ * by Wormhole NTT for `recipient` / `refundAddress` fields).
+ */
+export const addressToBytes32 = (addr: Address): HexString => pad(addr, { size: 32 }).toLowerCase() as HexString;
+
+// ─── Structs ─────────────────────────────────────────────────────────────
+
+export type ExecutorArgs = Readonly<{
+    /** Relay fee paid to the executor (forwarded as msg.value). */
+    value: bigint;
+    /** Where the executor refunds unused gas on the SOURCE chain. */
+    refundAddress: Address;
+    /** Signed quote bytes from the executor API. */
+    signedQuote: HexString;
+    /** Relay instructions bytes (see buildRelayInstructions). */
+    instructions: HexString;
+}>;
+
+export type FeeArgs = Readonly<{
+    /** App-level fee in deci-basis points (10_000 = 100%). Always 0 for DAMM. */
+    dbps: number;
+    /** Fee recipient. Irrelevant when dbps = 0. */
+    payee: Address;
+}>;
+
+// ─── transfer() ──────────────────────────────────────────────────────────
+
+export type WormholeTransferArgs = Readonly<{
+    /** MultiTokenNTT manager address on the source chain. */
+    multiTokenNtt: Address;
+    /** ERC20 token to bridge (e.g. WETH). */
+    token: Address;
+    /** Amount to bridge (token smallest unit). */
+    amount: bigint;
+    /** Destination chain (Wormhole chain ID, not EVM). */
+    recipientChain: number;
+    /** Destination address (bytes32, left-padded). Use addressToBytes32(). */
+    recipient: HexString;
+    /** Top-level refund address on the DESTINATION chain (bytes32). */
+    refundAddress: HexString;
+    /** Transceiver instructions. Pass "0x" for defaults. */
+    transceiverInstructions: HexString;
+    executorArgs: ExecutorArgs;
+    feeArgs: FeeArgs;
+}>;
+
+/**
+ * Encode calldata for `MultiNTTWithExecutor.transfer(...)`.
+ */
+export const WormholeTransferCalldata = (args: WormholeTransferArgs): HexString => {
+    return wormholeMultiNttInterface.encodeFunctionData("transfer", [
+        args.multiTokenNtt,
+        args.token,
+        args.amount,
+        args.recipientChain,
+        args.recipient,
+        args.refundAddress,
+        args.transceiverInstructions,
+        {
+            value: args.executorArgs.value,
+            refundAddress: args.executorArgs.refundAddress,
+            signedQuote: args.executorArgs.signedQuote,
+            instructions: args.executorArgs.instructions,
+        },
+        {
+            dbps: args.feeArgs.dbps,
+            payee: args.feeArgs.payee,
+        },
+    ]) as HexString;
+};
+
+/**
+ * Build a Call for `MultiNTTWithExecutor.transfer(...)`.
+ *
+ * `msg.value` = `executorArgs.value` (Executor relay fee) + any per-transceiver
+ * delivery fees required by the underlying `MultiTokenNTT` (e.g. Axelar's
+ * gateway fee on the Monad ↔ Ethereum lane).
+ *
+ * Pass `transceiverFee` when the `MultiTokenNTT` uses a paid transceiver in
+ * addition to Wormhole's guardian signing. Query the exact amount via
+ * `GmpManager.quoteDeliveryPrice(recipientChain, transceiverInstructions)`
+ * (see `GmpManagerQuoteDeliveryPriceCalldata`).
+ */
+export const wormholeTransferTrx = ({
+    wrapperAddress,
+    args,
+    transceiverFee = 0n,
+}: {
+    /** MultiNTTWithExecutor address on the source chain. */
+    wrapperAddress: Address;
+    args: WormholeTransferArgs;
+    /** Extra native token required by paid transceivers (e.g. Axelar). */
+    transceiverFee?: bigint;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: wrapperAddress,
+        data: WormholeTransferCalldata(args),
+        value: args.executorArgs.value + transceiverFee,
+    });
+};
+
+// ─── Relay Instructions ──────────────────────────────────────────────────
+
+/**
+ * Default `gasLimit` for `MultiTokenNTT` redemption on the destination chain.
+ *
+ * MultiNTT redemption is expensive because it:
+ *   (a) verifies the Wormhole VAA (guardian signatures + replay protection)
+ *   (b) verifies the sibling transceiver's attestation (2/2 check)
+ *   (c) executes the token mint/transfer on the destination `MultiTokenNTT`
+ *
+ * Empirically, successful Monad ↔ Mainnet transfers use ~650_000 gas; manual
+ * `receiveMessage` calls land in ~330_000. Default is 1_000_000 to leave
+ * headroom for future protocol upgrades and any per-block variance — the
+ * extra cost is tiny (~$0.20 per Monad→Mainnet bridge at typical prices)
+ * and eliminates `evm_simulation_gas_too_low` rejections from the Executor.
+ *
+ * Note: this is gas UNITS, not gas PRICE. It does not need to track network
+ * congestion — destination-chain gas usage is deterministic. What network
+ * spikes affect is the COST of providing this budget; that's bounded
+ * separately by the `etherWithinAllowance` permission cap in the kit.
+ *
+ * Override per-call via `buildRelayInstructions({ gasLimit: N })` if you have
+ * empirical data showing a different value is appropriate for your asset/lane.
+ */
+export const DEFAULT_NTT_REDEMPTION_GAS_LIMIT = 1_000_000n;
+
+/**
+ * Encode `GasInstruction` relay instructions for the executor.
+ *
+ * Format (per Wormhole SDK): `0x01` (version) || uint128 gasLimit || uint128 msgValue
+ * - `gasLimit`: gas units the executor should provide when redeeming on the destination
+ * - `msgValue`: native token (in wei on destination) to forward with the redemption call
+ *
+ * Default `gasLimit` is `DEFAULT_NTT_REDEMPTION_GAS_LIMIT` (650k), calibrated
+ * for `MultiTokenNTT` with a 2/2 transceiver stack. Override only if you know
+ * the destination chain's redemption consumes less.
+ */
+export const buildRelayInstructions = ({
+    gasLimit = DEFAULT_NTT_REDEMPTION_GAS_LIMIT,
+    msgValue = 0n,
+}: {
+    gasLimit?: bigint;
+    msgValue?: bigint;
+} = {}): HexString => {
+    if (gasLimit < 0n) throw new Error("buildRelayInstructions: negative gasLimit");
+    if (msgValue < 0n) throw new Error("buildRelayInstructions: negative msgValue");
+    return concatHex([
+        "0x01", // version
+        toHex(gasLimit, { size: 16 }),
+        toHex(msgValue, { size: 16 }),
+    ]) as HexString;
+};
+
+// ─── calculateFee() ──────────────────────────────────────────────────────
+
+/**
+ * Encode calldata for the view function `calculateFee(amount, dbps)`.
+ * Useful to query the dbps-based fee charged by the wrapper off-chain.
+ */
+export const WormholeCalculateFeeCalldata = ({ amount, dbps }: { amount: bigint; dbps: number }): HexString => {
+    return wormholeMultiNttInterface.encodeFunctionData("calculateFee", [amount, dbps]) as HexString;
+};
+
+// ─── Helper: assemble a full transfer args object ────────────────────────
+
+/**
+ * Compose a `WormholeTransferArgs` where recipient and refund addresses
+ * default to the same avatar (the Safe on both chains share an address).
+ *
+ * This matches the permission constraint in Our-DeFi-Kit's
+ * `WormholeBridgingPermissions`, which scopes `recipient`, top-level
+ * `refundAddress`, and `executorArgs.refundAddress` all to `c.avatar`.
+ */
+export const buildWormholeTransferArgsFromAvatar = ({
+    multiTokenNtt,
+    token,
+    amount,
+    recipientChain,
+    avatar,
+    relayFee,
+    signedQuote,
+    relayInstructions,
+    transceiverInstructions = "0x" as HexString,
+    dbps = 0,
+    payee,
+}: {
+    multiTokenNtt: Address;
+    token: Address;
+    amount: bigint;
+    /** Wormhole chain ID (not EVM). */
+    recipientChain: number;
+    /** The Safe address (same on source + destination). */
+    avatar: Address;
+    /** Native relay fee to forward (from signed quote estimatedCost). */
+    relayFee: bigint;
+    signedQuote: HexString;
+    relayInstructions: HexString;
+    transceiverInstructions?: HexString;
+    /** Defaults to 0 — DAMM never charges a skim fee. */
+    dbps?: number;
+    /** Defaults to the zero address when dbps = 0 (irrelevant). */
+    payee?: Address;
+}): WormholeTransferArgs => {
+    const avatarBytes32 = addressToBytes32(avatar);
+    return Object.freeze({
+        multiTokenNtt,
+        token,
+        amount,
+        recipientChain,
+        recipient: avatarBytes32,
+        refundAddress: avatarBytes32,
+        transceiverInstructions,
+        executorArgs: Object.freeze({
+            value: relayFee,
+            refundAddress: avatar,
+            signedQuote,
+            instructions: relayInstructions,
+        }),
+        feeArgs: Object.freeze({
+            dbps,
+            payee: payee ?? ("0x0000000000000000000000000000000000000000" as Address),
+        }),
+    });
+};

package/src/integrations/wormhole/wormhole.scan.api.ts

@@ -0,0 +1,95 @@
+/**
+ * Client for the WormholeScan public API — used to fetch the signed VAA
+ * emitted by a source-chain transceiver for a given cross-chain message.
+ *
+ * Endpoints:
+ *   - Mainnet: https://api.wormholescan.io
+ *   - Testnet: https://api.testnet.wormholescan.io
+ *
+ * API reference: https://docs.wormhole.com/wormhole/reference/api-docs/wormholescan
+ */
+
+import { bytesToHex, pad, size as hexSize } from "viem";
+import type { HexString } from "../../types";
+
+export const WORMHOLESCAN_API_MAINNET = "https://api.wormholescan.io" as const;
+export const WORMHOLESCAN_API_TESTNET = "https://api.testnet.wormholescan.io" as const;
+
+export type WormholeNetworkEnv = "Mainnet" | "Testnet";
+
+export const getWormholeScanApiUrl = (network: WormholeNetworkEnv = "Mainnet"): string =>
+    network === "Mainnet" ? WORMHOLESCAN_API_MAINNET : WORMHOLESCAN_API_TESTNET;
+
+// ─── VAA lookup by (chain, emitter, sequence) ────────────────────────────
+
+/**
+ * Convert a 20-byte address to the 64-char (32-byte) padded lowercase hex
+ * format WormholeScan expects for the `emitter` URL segment.
+ */
+export const normalizeEmitterForVaaLookup = (emitter: HexString): string => {
+    const byteLen = hexSize(emitter);
+    if (byteLen !== 20 && byteLen !== 32) {
+        throw new Error(`normalizeEmitterForVaaLookup: expected 20- or 32-byte hex, got ${byteLen} bytes`);
+    }
+    // 0x-prefixed, left-padded to 32 bytes, lowercase, no 0x in return value
+    return pad(emitter, { size: 32 }).slice(2).toLowerCase();
+};
+
+export type VaaLookupArgs = Readonly<{
+    /** Wormhole chain ID of the source chain (NOT EVM chainId). */
+    emitterChain: number;
+    /** Source-chain transceiver address — 20 or 32 byte hex. */
+    emitterAddress: HexString;
+    /** Sequence number emitted by the Wormhole core bridge. */
+    sequence: number | bigint;
+}>;
+
+export type VaaLookupResponse = Readonly<{
+    sequence: number;
+    id: string;
+    emitterChain: number;
+    emitterAddr: string;
+    emitterNativeAddr: string;
+    /** Base64-encoded signed VAA bytes. */
+    vaa: string;
+    timestamp?: string;
+    txHash?: string;
+    digest?: string;
+}>;
+
+/**
+ * Fetch the signed VAA for a given (chain, emitter, sequence).
+ *
+ * Throws if WormholeScan returns any non-2xx response (including 404, which
+ * happens during the brief window after the source tx confirms but before
+ * guardians have signed). Callers that want to poll should wrap this in a
+ * retry loop — letting the caller decide whether a 404 is a transient
+ * "not-yet-signed" or a permanent "wrong inputs" condition.
+ */
+export const fetchWormholeVAA = async (
+    args: VaaLookupArgs,
+    network: WormholeNetworkEnv = "Mainnet",
+): Promise<VaaLookupResponse> => {
+    const emitterPadded = normalizeEmitterForVaaLookup(args.emitterAddress);
+    const url = `${getWormholeScanApiUrl(network)}/api/v1/vaas/${args.emitterChain}/${emitterPadded}/${args.sequence.toString()}`;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`WormholeScan VAA lookup returned ${response.status} ${response.statusText}: ${body}`);
+    }
+    const parsed = (await response.json()) as { data?: VaaLookupResponse };
+    if (!parsed.data) {
+        throw new Error(
+            `WormholeScan VAA lookup returned 200 but no data for chain=${args.emitterChain} emitter=${args.emitterAddress} sequence=${args.sequence}`,
+        );
+    }
+    return parsed.data;
+};
+
+/**
+ * Decode a base64 VAA string into 0x-prefixed hex bytes, ready for
+ * `WormholeReceiveMessageCalldata`.
+ */
+export const decodeVaaBase64 = (base64: string): HexString =>
+    bytesToHex(Uint8Array.from(atob(base64), (c) => c.charCodeAt(0))) as HexString;

package/src/integrations/wormhole/wormhole.transceiver.abi.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal ABI for Wormhole's `GenericWormholeTransceiver` — the destination-side
+ * contract that verifies a Wormhole VAA and forwards it as an attestation to
+ * the `GmpManager` so a pending cross-chain message can be executed.
+ *
+ * Mainnet: 0x9D0eADF3fc10380C4D2F5ba79499C6194549C7D2
+ * Monad:   0x1a0f31492Ca69DF6A82906Ce88613AeCD9245C44
+ *
+ * Only the one function we need for manual recovery: `receiveMessage`.
+ * The call is permissionless — any EOA with enough gas can deliver a VAA.
+ */
+export default [
+    {
+        inputs: [{ name: "encodedMessage", type: "bytes" }],
+        name: "receiveMessage",
+        outputs: [],
+        stateMutability: "nonpayable",
+        type: "function",
+    },
+] as const;

package/src/integrations/wormhole/wormhole.transceiver.ts

@@ -0,0 +1,46 @@
+import { ethers } from "ethers";
+import wormholeTransceiverAbi from "./wormhole.transceiver.abi";
+import type { Address } from "viem";
+import type { Call, HexString, Unwrapable } from "../../types";
+import { createCall } from "../../types";
+
+const transceiverInterface = new ethers.utils.Interface(wormholeTransceiverAbi as any);
+
+// ─── receiveMessage(bytes encodedMessage) ────────────────────────────────
+
+/**
+ * Encode calldata for `GenericWormholeTransceiver.receiveMessage(bytes vaa)`.
+ *
+ * Use this to manually deliver a Wormhole VAA to the destination transceiver
+ * when auto-relay has failed (e.g. Executor pre-flight sim rejected the gas
+ * quote and aborted). The transceiver verifies the VAA's guardian signatures
+ * and forwards the attestation to the `GmpManager`; once the 2/2 threshold is
+ * met with the sibling transceiver (e.g. Axelar), `executeMsg` fires
+ * automatically in the same transaction.
+ */
+export const WormholeReceiveMessageCalldata = ({ vaa }: { vaa: HexString }): HexString => {
+    return transceiverInterface.encodeFunctionData("receiveMessage", [vaa]) as HexString;
+};
+
+/**
+ * Build a Call for manually delivering a VAA to the Wormhole transceiver.
+ *
+ * The call is permissionless (any EOA works), takes no value, and is safe to
+ * retry — the transceiver rejects duplicates.
+ */
+export const wormholeReceiveMessageTrx = ({
+    transceiverAddress,
+    vaa,
+}: {
+    /** `GenericWormholeTransceiver` address on the destination chain. */
+    transceiverAddress: Address;
+    /** The signed VAA bytes, as fetched from WormholeScan. */
+    vaa: HexString;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: transceiverAddress,
+        data: WormholeReceiveMessageCalldata({ vaa }),
+        value: 0n,
+    });
+};

package/src/lib/contractsRegistry.json

@@ -552,7 +552,9 @@
         "wormhole": {
             "executor": "0x84EEe8dBa37C36947397E1E11251cA9A06Fc6F8a",
             "multiTokenNTT": "0x556790e948b9920A8868bCAFcC87D25e82e8a075",
-            "multiNTTWithExecutor": "0x03dB430D830601DB368991eE55DAa9A708df7912"
+            "multiNTTWithExecutor": "0x03dB430D830601DB368991eE55DAa9A708df7912",
+            "gmpManager": "0xc6793a32761a11e96c97A3D18fC6545ea931F0E9",
+            "genericWormholeTransceiver": "0x9D0eADF3fc10380C4D2F5ba79499C6194549C7D2"
         },
         "1inch": {
             "aggregatorV6": "0x111111125421cA6dc452d289314280a0f8842A65"
@@ -946,7 +948,9 @@
         "wormhole": {
             "executor": "0xC04dE634982cAdF2A677310b73630B7Ac56A3f65",
             "multiTokenNTT": "0x36878C6FCa7e0E8a88F90dc410CfBBcA5B695C95",
-            "multiNTTWithExecutor": "0xFEA937F7124E19124671f1685671d3f04a9Af4E4"
+            "multiNTTWithExecutor": "0xFEA937F7124E19124671f1685671d3f04a9Af4E4",
+            "gmpManager": "0x92957b3D0CaB3eA7110fEd1ccc4eF564981a59Fc",
+            "genericWormholeTransceiver": "0x1a0f31492Ca69DF6A82906Ce88613AeCD9245C44"
         },
         "enso": {
             "routerV2": "0xCfBAa9Cfce952Ca4F4069874fF1Df8c05e37a3c7"