damm-sdk 1.4.30 → 1.4.32

package/src/integrations/cctp/cctp.message.decoder.ts

@@ -0,0 +1,189 @@
+/**
+ * Pure byte-level decoder for CCTP V2 cross-chain messages.
+ *
+ * Use when you need to verify or inspect the contents of a CCTP V2 message
+ * without trusting the pre-decoded fields from iris-api (defense in depth),
+ * or when working with a raw message blob produced by a source-chain tx.
+ *
+ * Message format reference:
+ *   https://developers.circle.com/stablecoins/message-format
+ *
+ * The outer header (148 bytes) wraps a variable-length body. For USDC burn
+ * transfers the body is a `BurnMessage` V2 — the only body shape this
+ * module supports (other body shapes are non-USDC payloads that cli-damm
+ * does not currently finalize).
+ */
+
+import { getAddress, isHex, size as hexSize, sliceHex, hexToBigInt, hexToNumber } from "viem";
+import type { Address } from "viem";
+import type { HexString } from "../../types";
+
+/** Version byte at the start of a CCTP V2 header. */
+export const CCTP_V2_HEADER_VERSION = 1 as const;
+
+/** Version byte at the start of a CCTP V2 BurnMessage body. */
+export const CCTP_V2_BURN_BODY_VERSION = 1 as const;
+
+/** Total byte length of the fixed-size CCTP V2 header. */
+const HEADER_BYTE_LENGTH = 148;
+
+/** Byte length of the fixed-size portion of a BurnMessage V2 body (before `hookData`). */
+const BURN_BODY_FIXED_BYTE_LENGTH = 228;
+
+// ─── Byte offsets within the header ──────────────────────────────────────
+const OFF_VERSION = 0;
+const OFF_SOURCE_DOMAIN = 4;
+const OFF_DEST_DOMAIN = 8;
+const OFF_NONCE = 12;
+const OFF_SENDER = 44;
+const OFF_RECIPIENT = 76;
+const OFF_DESTINATION_CALLER = 108;
+const OFF_MIN_FINALITY = 140;
+const OFF_FINALITY_EXECUTED = 144;
+const OFF_BODY = 148;
+
+// ─── Byte offsets within a BurnMessage V2 body ───────────────────────────
+const BODY_OFF_VERSION = 0;
+const BODY_OFF_BURN_TOKEN = 4;
+const BODY_OFF_MINT_RECIPIENT = 36;
+const BODY_OFF_AMOUNT = 68;
+const BODY_OFF_MESSAGE_SENDER = 100;
+const BODY_OFF_MAX_FEE = 132;
+const BODY_OFF_FEE_EXECUTED = 164;
+const BODY_OFF_EXPIRATION_BLOCK = 196;
+const BODY_OFF_HOOK_DATA = 228;
+
+/**
+ * Decoded CCTP V2 header. All bytes32 fields are preserved as 0x-prefixed
+ * hex strings (not narrowed to addresses) except `sender` and `recipient`,
+ * which Circle guarantees are address-padded bytes32 values.
+ */
+export type CctpV2Header = Readonly<{
+    version: number;
+    sourceDomain: number;
+    destinationDomain: number;
+    nonce: HexString;
+    sender: Address;
+    recipient: Address;
+    destinationCaller: HexString;
+    minFinalityThreshold: number;
+    finalityThresholdExecuted: number;
+    messageBody: HexString;
+}>;
+
+/**
+ * Decoded CCTP V2 BurnMessage body — the message-body shape used for USDC
+ * bridging. `hookData` is empty (`"0x"`) for standard transfers.
+ */
+export type CctpV2BurnMessageBody = Readonly<{
+    version: number;
+    burnToken: Address;
+    mintRecipient: Address;
+    amount: bigint;
+    messageSender: Address;
+    maxFee: bigint;
+    feeExecuted: bigint;
+    expirationBlock: bigint;
+    hookData: HexString;
+}>;
+
+/** Header + burn-body decoded together in one pass. */
+export type CctpV2Message = Readonly<
+    CctpV2Header & {
+        decodedBody: CctpV2BurnMessageBody;
+    }
+>;
+
+const requireHex = (value: unknown): HexString => {
+    if (typeof value !== "string" || !isHex(value)) {
+        throw new Error(`CCTP decoder: expected a 0x-prefixed hex string, got ${typeof value}`);
+    }
+    return value as HexString;
+};
+
+/**
+ * Decode the outer CCTP V2 header and return it alongside the embedded
+ * `messageBody`. Does not inspect the body contents — use {@link decodeCctpV2BurnBody}
+ * for that.
+ *
+ * @throws if `message` is shorter than the 148-byte header
+ * @throws if the header version byte is not {@link CCTP_V2_HEADER_VERSION}
+ */
+export const decodeCctpV2Header = (message: HexString): CctpV2Header => {
+    const bytes = requireHex(message);
+    const length = hexSize(bytes);
+    if (length < HEADER_BYTE_LENGTH) {
+        throw new Error(`CCTP decoder: header requires ${HEADER_BYTE_LENGTH} bytes, got ${length}`);
+    }
+
+    const version = hexToNumber(sliceHex(bytes, OFF_VERSION, OFF_SOURCE_DOMAIN));
+    if (version !== CCTP_V2_HEADER_VERSION) {
+        throw new Error(`CCTP decoder: unknown header version ${version} (expected ${CCTP_V2_HEADER_VERSION})`);
+    }
+
+    // The sender and recipient are 32-byte slots holding left-padded 20-byte
+    // addresses. Slice the last 20 bytes (offset +12) to recover them.
+    const senderPadded = sliceHex(bytes, OFF_SENDER, OFF_RECIPIENT);
+    const recipientPadded = sliceHex(bytes, OFF_RECIPIENT, OFF_DESTINATION_CALLER);
+    const sender = getAddress(`0x${senderPadded.slice(2 + 24)}`);
+    const recipient = getAddress(`0x${recipientPadded.slice(2 + 24)}`);
+
+    return Object.freeze({
+        version,
+        sourceDomain: hexToNumber(sliceHex(bytes, OFF_SOURCE_DOMAIN, OFF_DEST_DOMAIN)),
+        destinationDomain: hexToNumber(sliceHex(bytes, OFF_DEST_DOMAIN, OFF_NONCE)),
+        nonce: sliceHex(bytes, OFF_NONCE, OFF_SENDER),
+        sender,
+        recipient,
+        destinationCaller: sliceHex(bytes, OFF_DESTINATION_CALLER, OFF_MIN_FINALITY),
+        minFinalityThreshold: hexToNumber(sliceHex(bytes, OFF_MIN_FINALITY, OFF_FINALITY_EXECUTED)),
+        finalityThresholdExecuted: hexToNumber(sliceHex(bytes, OFF_FINALITY_EXECUTED, OFF_BODY)),
+        messageBody: sliceHex(bytes, OFF_BODY),
+    });
+};
+
+/**
+ * Decode a CCTP V2 BurnMessage body.
+ *
+ * @throws if `body` is shorter than the 228-byte fixed portion
+ * @throws if the body version byte is not {@link CCTP_V2_BURN_BODY_VERSION}
+ */
+export const decodeCctpV2BurnBody = (body: HexString): CctpV2BurnMessageBody => {
+    const bytes = requireHex(body);
+    const length = hexSize(bytes);
+    if (length < BURN_BODY_FIXED_BYTE_LENGTH) {
+        throw new Error(`CCTP decoder: burn body requires ${BURN_BODY_FIXED_BYTE_LENGTH} bytes, got ${length}`);
+    }
+
+    const version = hexToNumber(sliceHex(bytes, BODY_OFF_VERSION, BODY_OFF_BURN_TOKEN));
+    if (version !== CCTP_V2_BURN_BODY_VERSION) {
+        throw new Error(`CCTP decoder: unknown burn body version ${version} (expected ${CCTP_V2_BURN_BODY_VERSION})`);
+    }
+
+    const burnTokenPadded = sliceHex(bytes, BODY_OFF_BURN_TOKEN, BODY_OFF_MINT_RECIPIENT);
+    const mintRecipientPadded = sliceHex(bytes, BODY_OFF_MINT_RECIPIENT, BODY_OFF_AMOUNT);
+    const messageSenderPadded = sliceHex(bytes, BODY_OFF_MESSAGE_SENDER, BODY_OFF_MAX_FEE);
+
+    return Object.freeze({
+        version,
+        burnToken: getAddress(`0x${burnTokenPadded.slice(2 + 24)}`),
+        mintRecipient: getAddress(`0x${mintRecipientPadded.slice(2 + 24)}`),
+        amount: hexToBigInt(sliceHex(bytes, BODY_OFF_AMOUNT, BODY_OFF_MESSAGE_SENDER)),
+        messageSender: getAddress(`0x${messageSenderPadded.slice(2 + 24)}`),
+        maxFee: hexToBigInt(sliceHex(bytes, BODY_OFF_MAX_FEE, BODY_OFF_FEE_EXECUTED)),
+        feeExecuted: hexToBigInt(sliceHex(bytes, BODY_OFF_FEE_EXECUTED, BODY_OFF_EXPIRATION_BLOCK)),
+        expirationBlock: hexToBigInt(sliceHex(bytes, BODY_OFF_EXPIRATION_BLOCK, BODY_OFF_HOOK_DATA)),
+        hookData: length > BURN_BODY_FIXED_BYTE_LENGTH ? sliceHex(bytes, BODY_OFF_HOOK_DATA) : "0x",
+    });
+};
+
+/**
+ * Convenience: decode the outer header and the embedded burn body in a
+ * single call. Throws the same errors as {@link decodeCctpV2Header} and
+ * {@link decodeCctpV2BurnBody}.
+ */
+export const decodeCctpV2Message = (message: HexString): CctpV2Message => {
+    const header = decodeCctpV2Header(message);
+    const decodedBody = decodeCctpV2BurnBody(header.messageBody);
+    return Object.freeze({ ...header, decodedBody });
+};

package/src/integrations/cctp/index.ts

@@ -1,3 +1,5 @@
 export { default as CctpTokenMessengerV2Abi } from "./token.messenger.v2.abi";
 export { default as CctpMessageTransmitterV2Abi } from "./message.transmitter.v2.abi";
 export * from "./cctp.v2";
+export * from "./cctp.message.decoder";
+export * from "./cctp.iris.api";

package/src/lib/contractsRegistry.json

@@ -370,7 +370,8 @@
             "tbtc": "0x6c84a8f1c29108F47a79964b5Fe888D4f4D0dE40",
             "op": "0x4200000000000000000000000000000000000042",
             "usde": "0x5d3a1ff2b6bab83b63cd9ad0787074081a52ef34",
-            "weeth": "0x5A7fACB970D094B6C7FF1df0eA68D99E6e73CBFF"
+            "weeth": "0x5A7fACB970D094B6C7FF1df0eA68D99E6e73CBFF",
+            "wsteth": "0x1F32b1c2345538c0c6f582fCB022739c4A194Ebb"
         },
         "gnosisSafe": {
             "v1_4_1": {