Check nonce before relaying message (#2938)

shahthepro · web-flow · commit 9e3d02b66ec1 · 2026-07-13T12:35:19.000+02:00
diff --git a/contracts/tasks/actions/crossChainRelay.ts b/contracts/tasks/actions/crossChainRelay.ts
@@ -1,4 +1,5 @@
 import { ethers } from "ethers";
+import { types } from "hardhat/config";
 import { configuration } from "../../utils/cctp";
 import { keyValueStoreLocalClient } from "../../utils/defender";
 import { getNetworkName } from "../../utils/hardhat-helpers";
@@ -9,7 +10,15 @@ action({
   name: "crossChainRelay",
   description: "Relay CCTP bridge transactions between mainnet and Base",
   chains: [1, 8453],
-  run: async ({ signer, chainId, log }) => {
+  params: (t) => {
+    t.addOptionalParam(
+      "txHash",
+      "Source-chain tx hash to relay. When set, skips the recent-events scan and relays only this transaction's message(s). Must be run on the destination chain.",
+      undefined,
+      types.string
+    );
+  },
+  run: async ({ signer, chainId, log, args }) => {
     let sourceProvider: ethers.providers.JsonRpcProvider;
 
     if (chainId === 1) {
@@ -45,6 +54,7 @@ action({
     });
 
     await processCctpBridgeTransactions({
+      txHash: args.txHash,
       destinationChainSigner: signer,
       sourceChainProvider: sourceProvider,
       store,
diff --git a/contracts/tasks/actions/crossChainRelayHyperEVM.ts b/contracts/tasks/actions/crossChainRelayHyperEVM.ts
@@ -1,4 +1,5 @@
 import { ethers } from "ethers";
+import { types } from "hardhat/config";
 import { configuration } from "../../utils/cctp";
 import { keyValueStoreLocalClient } from "../../utils/defender";
 import { getNetworkName } from "../../utils/hardhat-helpers";
@@ -9,7 +10,15 @@ action({
   name: "crossChainRelayHyperEVM",
   description: "Relay CCTP bridge transactions between mainnet and HyperEVM",
   chains: [1, 999],
-  run: async ({ signer, chainId, log }) => {
+  params: (t) => {
+    t.addOptionalParam(
+      "txHash",
+      "Source-chain tx hash to relay. When set, skips the recent-events scan and relays only this transaction's message(s). Must be run on the destination chain.",
+      undefined,
+      types.string
+    );
+  },
+  run: async ({ signer, chainId, log, args }) => {
     let sourceProvider: ethers.providers.JsonRpcProvider;
 
     if (chainId === 1) {
@@ -45,6 +54,7 @@ action({
     });
 
     await processCctpBridgeTransactions({
+      txHash: args.txHash,
       destinationChainSigner: signer,
       sourceChainProvider: sourceProvider,
       store,
diff --git a/contracts/tasks/actions/relayCCTPMessage.ts b/contracts/tasks/actions/relayCCTPMessage.ts
@@ -14,6 +14,12 @@ action({
     "Fetches CCTP attested Messages via Circle Gateway API and relays it to the integrator contract",
   chains: [1, 8453],
   params: (t) => {
+    t.addOptionalParam(
+      "txHash",
+      "Source-chain tx hash to relay. When set, skips the recent-events scan and relays only this transaction's message(s). Must be run on the destination chain.",
+      undefined,
+      types.string
+    );
     t.addOptionalParam(
       "block",
       "Override the block number at which the message emission transaction happened",
diff --git a/contracts/tasks/crossChain.js b/contracts/tasks/crossChain.js
@@ -4,6 +4,73 @@ const { logTxDetails } = require("../utils/txLogger");
 const { api: cctpApi } = require("../utils/cctp");
 const log = require("../utils/logger")("task:crossChain");
 
+// 0x-prefixed 32-byte tx hash
+const TX_HASH_REGEX = /^0x([A-Fa-f0-9]{64})$/;
+
+// Layout constants mirror the on-chain decoders so the script extracts the
+// same Origin nonce the contract would.
+// Ref: contracts/strategies/crosschain/CrossChainStrategyHelper.sol
+//      and AbstractCCTPIntegrator.sol
+const ORIGIN_MESSAGE_VERSION = 1010; // CrossChainStrategyHelper.ORIGIN_MESSAGE_VERSION
+const CCTP_MESSAGE_BODY_INDEX = 148; // CrossChainStrategyHelper.MESSAGE_BODY_INDEX
+const BURN_MESSAGE_V2_HOOK_DATA_INDEX = 228; // AbstractCCTPIntegrator.BURN_MESSAGE_V2_HOOK_DATA_INDEX
+// Origin message: 4 bytes version + 4 bytes type, then the abi-encoded payload
+const ORIGIN_PAYLOAD_INDEX = 8;
+
+// Read a big-endian uint32 from a Uint8Array at the given byte offset.
+const readUint32 = (bytes, start) =>
+  (bytes[start] << 24) |
+  (bytes[start + 1] << 16) |
+  (bytes[start + 2] << 8) |
+  bytes[start + 3];
+
+/**
+ * Decode the Origin transfer nonce from a raw CCTP message, mirroring the
+ * on-chain relay decoding. Returns the nonce as an ethers BigNumber, or null
+ * if the message is not one of our Origin messages (deposit / withdraw /
+ * balance check).
+ *
+ * The Origin message is either:
+ *  - the CCTP message body directly (plain message: withdraw / balance check), or
+ *  - the burn message hook data (deposit), located at byte 228 of the body.
+ * The nonce is the first abi-encoded word of the Origin payload.
+ */
+const decodeOriginNonce = (messageHex) => {
+  if (!messageHex) {
+    return null;
+  }
+  const bytes = ethers.utils.arrayify(messageHex);
+  if (bytes.length < CCTP_MESSAGE_BODY_INDEX + 4) {
+    return null;
+  }
+  const body = bytes.slice(CCTP_MESSAGE_BODY_INDEX);
+
+  let originMessage;
+  if (readUint32(body, 0) === ORIGIN_MESSAGE_VERSION) {
+    // Plain message (withdraw / balance check): body is the Origin message
+    originMessage = body;
+  } else if (
+    body.length >= BURN_MESSAGE_V2_HOOK_DATA_INDEX + 4 &&
+    readUint32(body, BURN_MESSAGE_V2_HOOK_DATA_INDEX) === ORIGIN_MESSAGE_VERSION
+  ) {
+    // Burn message (deposit): Origin message is the hook data
+    originMessage = body.slice(BURN_MESSAGE_V2_HOOK_DATA_INDEX);
+  } else {
+    return null;
+  }
+
+  if (originMessage.length < ORIGIN_PAYLOAD_INDEX + 32) {
+    return null;
+  }
+
+  // Nonce is the first 32-byte abi word of the payload (a left-padded uint64)
+  const nonceWord = originMessage.slice(
+    ORIGIN_PAYLOAD_INDEX,
+    ORIGIN_PAYLOAD_INDEX + 32
+  );
+  return ethers.BigNumber.from(nonceWord);
+};
+
 const cctpOperationsConfig = async ({
   destinationChainSigner,
   sourceChainProvider,
@@ -15,6 +82,7 @@ const cctpOperationsConfig = async ({
     "event TokensBridged(uint32 peerDomainID,address peerStrategy,address usdcToken,uint256 tokenAmount,uint256 maxFee,uint32 minFinalityThreshold,bytes hookData)",
     "event MessageTransmitted(uint32 peerDomainID,address peerStrategy,uint32 minFinalityThreshold,bytes message)",
     "function relay(bytes message, bytes attestation) external",
+    "function isNonceProcessed(uint64 nonce) view returns (bool)",
   ];
 
   const cctpIntegrationContractSource = new ethers.Contract(
@@ -157,6 +225,7 @@ const fetchTxHashesFromCctpTransactions = async ({
 
 const processCctpBridgeTransactions = async ({
   block = undefined,
+  txHash = undefined,
   dryrun = false,
   destinationChainSigner,
   sourceChainProvider,
@@ -168,6 +237,10 @@ const processCctpBridgeTransactions = async ({
   cctpIntegrationContractAddress,
   cctpIntegrationContractAddressDestination,
 }) => {
+  // When a tx hash is passed we relay only that transaction (skipping the
+  // recent-events scan) and bypass the local store dedup, since the operator
+  // explicitly asked for it. On-chain isNonceProcessed is the real safety net.
+  const manualRun = Boolean(txHash);
   const config = await cctpOperationsConfig({
     destinationChainSigner,
     sourceChainProvider,
@@ -181,19 +254,33 @@ const processCctpBridgeTransactions = async ({
     }`
   );
 
-  const { allTxHashes } = await fetchTxHashesFromCctpTransactions({
-    config,
-    overrideBlock: block,
-    sourceChainProvider,
-    blockLookback,
-  });
+  let allTxHashes;
+  if (manualRun) {
+    if (!TX_HASH_REGEX.test(txHash)) {
+      throw new Error(`Invalid tx hash: ${txHash}`);
+    }
+    allTxHashes = [txHash.toLowerCase()];
+    log(
+      `Relaying only tx ${allTxHashes[0]} (manual). Skipping recent-events scan.`
+    );
+  } else {
+    ({ allTxHashes } = await fetchTxHashesFromCctpTransactions({
+      config,
+      overrideBlock: block,
+      sourceChainProvider,
+      blockLookback,
+    }));
+  }
   for (const txHash of allTxHashes) {
     const txStoreKey = `cctp_message_${txHash}_${cctpDestinationDomainId}`;
     // TODO: Legacy key can be removed after a few days of code deployment
     const txStoreKey_Legacy = `cctp_message_${txHash}`;
     const txStoredValue = await store.get(txStoreKey);
     const txStoredValue_Legacy = await store.get(txStoreKey_Legacy);
-    if (txStoredValue === "processed" || txStoredValue_Legacy === "processed") {
+    if (
+      !manualRun &&
+      (txStoredValue === "processed" || txStoredValue_Legacy === "processed")
+    ) {
       log(
         `Transaction with hash ${txHash} has already been processed via tx-level key ${txStoreKey}. Skipping...`
       );
@@ -242,13 +329,33 @@ const processCctpBridgeTransactions = async ({
       }
       hasEligibleMessage = true;
 
-      if (storedValue === "processed") {
+      if (!manualRun && storedValue === "processed") {
         log(
           `Message with key ${storeKey} has already been processed. Skipping...`
         );
         continue;
       }
 
+      // Check on-chain whether this transfer nonce was already processed on the
+      // destination strategy. If so, relaying would revert, so skip it and
+      // reconcile the local store.
+      const originNonce = decodeOriginNonce(cctpMessage.message);
+      if (
+        originNonce !== null &&
+        (await config.cctpIntegrationContractDestination.isNonceProcessed(
+          originNonce
+        ))
+      ) {
+        log(
+          `Nonce ${originNonce.toString()} for message ${messageId} from tx ${txHash} is already processed on-chain. Skipping relay...`
+        );
+        if (storedValue !== "processed") {
+          await store.put(storeKey, "processed");
+          log(`Marked message with key ${storeKey} as processed in store`);
+        }
+        continue;
+      }
+
       if (!cctpMessage.message || !cctpMessage.attestation) {
         log(
           `Message ${messageId} from tx ${txHash} is missing message payload or attestation. Skipping...`
@@ -303,4 +410,6 @@ const processCctpBridgeTransactions = async ({
 
 module.exports = {
   processCctpBridgeTransactions,
+  decodeOriginNonce,
+  TX_HASH_REGEX,
 };
diff --git a/contracts/test/strategies/crosschain/decode-origin-nonce.js b/contracts/test/strategies/crosschain/decode-origin-nonce.js
@@ -0,0 +1,70 @@
+const { expect } = require("chai");
+
+const { decodeOriginNonce } = require("../../../tasks/crossChain");
+const {
+  encodeCCTPMessage,
+  encodeDepositMessageBody,
+  encodeWithdrawMessageBody,
+  encodeBurnMessageBody,
+  encodeBalanceCheckMessageBody,
+} = require("./_crosschain-helpers");
+
+// Unit test for the JS nonce decoder used by the CCTP relay actions. The
+// fixtures are built with the same encoders the on-chain contracts use, so the
+// decoder is exercised against production-shaped messages.
+describe("Unit: decodeOriginNonce (CCTP relay)", () => {
+  const sourceDomain = 6; // Base
+  const sender = "0x0000000000000000000000000000000000000001";
+  const recipient = "0x0000000000000000000000000000000000000002";
+  const usdc = "0x0000000000000000000000000000000000000003";
+  const amount = "1000000"; // 1 USDC
+
+  it("decodes nonce from a deposit (burn message with hook data)", () => {
+    const nonce = 7;
+    const hookData = encodeDepositMessageBody(nonce, amount);
+    const burnBody = encodeBurnMessageBody(
+      sender,
+      recipient,
+      usdc,
+      amount,
+      hookData
+    );
+    const message = encodeCCTPMessage(
+      sourceDomain,
+      sender,
+      recipient,
+      burnBody
+    );
+
+    expect(decodeOriginNonce(message).toNumber()).to.eq(nonce);
+  });
+
+  it("decodes nonce from a withdraw (plain message)", () => {
+    const nonce = 42;
+    const body = encodeWithdrawMessageBody(nonce, amount);
+    const message = encodeCCTPMessage(sourceDomain, sender, recipient, body);
+
+    expect(decodeOriginNonce(message).toNumber()).to.eq(nonce);
+  });
+
+  it("decodes nonce from a balance check (plain message)", () => {
+    const nonce = 123;
+    const body = encodeBalanceCheckMessageBody(nonce, amount, true, 1700000000);
+    const message = encodeCCTPMessage(sourceDomain, sender, recipient, body);
+
+    expect(decodeOriginNonce(message).toNumber()).to.eq(nonce);
+  });
+
+  it("returns null for a non-Origin message body", () => {
+    // Version != 1010 and too short to be a burn message with Origin hook data
+    const body = "0xdeadbeef00000000";
+    const message = encodeCCTPMessage(sourceDomain, sender, recipient, body);
+
+    expect(decodeOriginNonce(message)).to.eq(null);
+  });
+
+  it("returns null for empty or missing input", () => {
+    expect(decodeOriginNonce(undefined)).to.eq(null);
+    expect(decodeOriginNonce("0x")).to.eq(null);
+  });
+});
