feat: finalize tokenless HubPool CCTP messages #2270

grasphoper · 2025-05-24T04:44:09Z

Current implementation of CCTP finalizer is only tracking DepositForBurn events, and thus is not considering other types of CCTP messages. CCTP can send tokenless messages via MessageTransmitter contract, which emits MessageSent(bytes message) event.

We use HubPool events TokensRelayed and MessageRelayed to find relevant tx hashes to search for such MessageTransmitter MessageSent events in addition to all DepositForBurn events.

Signed-off-by: Ihor Farion <[email protected]>

…ng status Signed-off-by: Ihor Farion <[email protected]>

…ying on cctpMessageIndex Signed-off-by: Ihor Farion <[email protected]>

Signed-off-by: Ihor Farion <[email protected]>

src/utils/CCTPUtils.ts

Signed-off-by: Ihor Farion <[email protected]>

…or pending attestations ... Signed-off-by: Ihor Farion <[email protected]>

Signed-off-by: Ihor Farion <[email protected]>

grasphoper · 2025-05-28T20:17:35Z

Tested the following:

equality between new code and old code in finding CCTP DepositForBurn events
v1 crosschain transfer: send, finalize
v1 crosschain message relay: send, finalize
v2 crosschain transfer: send, finalize
v2 crosschain message relay: send, finalize

pxrl · 2025-05-28T19:46:24Z

src/utils/CCTPUtils.ts

+ * @returns A Set of unique transaction hashes.
+ */
+async function getRelevantCCTPTxHashes(
+  srcProvider: RetryProvider,


Do we need RetryProvider here? I'd have expected Provider should be sufficient.

Not sure what the differences are. Just used it because it was used in other places in the file

pxrl · 2025-05-28T19:47:24Z

src/utils/CCTPUtils.ts

-  const isCctpV2 = isCctpV2L2ChainId(l2ChainId);
+  senderAddresses: string[],
+  sourceEventSearchConfig: EventSearchConfig,
+  includeTokenlessHubPoolMessages: boolean


wdyt about setting a default on this? Are there scenarios where we might want to only look at tokens?

The naming might be better here probably. This flag:

enables scanning for any CCTP events in the HubPool-related txs.

in practice, this means querying MessageRelayed, TokenRelayed events on HubPool address

if HubPool address is not defined for a sourceChain, this funnction will crash. So I use includeTokenlessHubPoolMessages = false for L2 -> L1 CCTP for example

pxrl · 2025-05-28T19:48:25Z

src/utils/CCTPUtils.ts

+      const messageRelayedEvents = await paginatedEventQuery(hubPool, messageRelayedFilter, sourceEventSearchConfig);
+      messageRelayedEvents.forEach((e) => txHashesFromHubPool.push(e.transactionHash));
+
+      const tokensRelayedFilter = hubPool.filters.TokensRelayed();
+      const tokensRelayedEvents = await paginatedEventQuery(hubPool, tokensRelayedFilter, sourceEventSearchConfig);


It probably makes sense to do these in parallel via Promise.all().

Indeed. Interestingly, I tried to just create a correct combined topic filter but failed. Can tell if I did it wrong or paginatedEventQuery doesn't support that

pxrl · 2025-05-28T19:54:33Z

src/utils/CCTPUtils.ts

+    let lastMessageSentEventIdx = -1;
+    receipt.logs.forEach((log, i) => {
+      if (_isMessageSentEvent(log)) {
+        if (lastMessageSentEventIdx == -1) {
+          lastMessageSentEventIdx = i;
+        } else {
+          _addCommonMessageEventIfRelevant(receipt.logs[lastMessageSentEventIdx]);
+          lastMessageSentEventIdx = i;
+        }
+      } else {
+        const depositForBurnVersion = _getDepositForBurnVersion(log);
+        if (depositForBurnVersion == -1) {
+          // Skip non-`DepositForBurn` events
+          return;
+        }
+        if (lastMessageSentEventIdx == -1) {
+          throw new Error(
+            "DepositForBurn event found without corresponding MessageSent event. " +
+              "Each DepositForBurn event must have a preceding MessageSent event in the same transaction. " +
+              `Transaction: ${receipt.transactionHash}, DepositForBurn log index: ${i}`
+          );
+        }


Can you comment on what this loop is doing?

Sure. Here, we go one by one over a receipts that we "suspect might have CCTP messages for finalization".

It's important to understand what we're looking for in the logs. It's either of 2 things:

MessageSent + DepositForBurn == a single USDC transfer from one chain to another (1)

solo MessageSent with no DepositForBurn -> a single crosschain message (2)

Then for each receipt we traverse all logs in order, and keep the latest encountered MessageSent index in lastMessageSentEventIdx . Then if we encounter next MessageSent -> the one stored in lastMessageSentEventIdx was (2). If we encounter DepositForBurn, then we bundle stored lastMessageSentEventIdx with it to receive (1)

pxrl · 2025-05-28T20:26:00Z

src/utils/CCTPUtils.ts

 }

-function _getPendingV2AttestationStatus(attestation: string): CCTPMessageStatus {
-  return attestation === "pending_confirmation" ? "pending" : "ready";
+function _getPendingV2AttestationStatus(attestation: CCTPV2APIAttestation): CCTPMessageStatus {


This looks identical to _getPendingAttestationStatus() - should we make attestation a union of CCTPV2APIAttestation | CCTPAPIGetAttestatuibResponse and drop the 2nd implementation? Could alternatively do something like Pick<CCTPV2APIAttestation, "attestation" | "status">.

grasphoper added 6 commits May 23, 2025 19:52

~complete getCCTPMessageEvents

2f9cb20

Signed-off-by: Ihor Farion <[email protected]>

fix Log handling: produce *typed* logs

1c8a175

Signed-off-by: Ihor Farion <[email protected]>

complete implementation

835db3e

Signed-off-by: Ihor Farion <[email protected]>

refactor progress

09727cf

Signed-off-by: Ihor Farion <[email protected]>

handle edge case

38fc4d8

Signed-off-by: Ihor Farion <[email protected]>

fix nuanced L2 -> L1 behavior

d4cf83c

Signed-off-by: Ihor Farion <[email protected]>

grasphoper changed the title ~~feat: finalize *tokenless* HubPool CCTP messages in addition to all DepositForBurn messages~~ feat: finalize *tokenless* HubPool CCTP messages May 24, 2025

grasphoper and others added 8 commits May 23, 2025 21:52

add todo comments

1199e1a

Signed-off-by: Ihor Farion <[email protected]>

Merge branch 'master' into if/finalize-cctp-raw-messages2

565a571

address todos

9afda58

Signed-off-by: Ihor Farion <[email protected]>

update naming

ec02f37

Signed-off-by: Ihor Farion <[email protected]>

polish logic + update v2 indexing logic

5824574

Signed-off-by: Ihor Farion <[email protected]>

address rate-limit concern

6b9d64d

Signed-off-by: Ihor Farion <[email protected]>

fix some testing findings

499a34e

Signed-off-by: Ihor Farion <[email protected]>

Merge branch 'master' into if/finalize-cctp-raw-messages2

aa4808a

grasphoper marked this pull request as ready for review May 28, 2025 16:02

grasphoper requested review from mrice32, nicholaspai, pxrl, james-a-morris, dohaki and bmzig as code owners May 28, 2025 16:02

grasphoper added 3 commits May 28, 2025 11:51

change cctpVersion according to real API outputs, same with determini…

4f9c40b

…ng status Signed-off-by: Ihor Farion <[email protected]>

match message to attestation by comparing the message itself, not rel…

8152bd7

…ying on cctpMessageIndex Signed-off-by: Ihor Farion <[email protected]>

cleanup cctpMessageIndex logic

e7bc646

Signed-off-by: Ihor Farion <[email protected]>

pxrl reviewed May 28, 2025

View reviewed changes

src/utils/CCTPUtils.ts Outdated Show resolved Hide resolved

grasphoper added 3 commits May 28, 2025 12:48

adjust api <> event comparison function to match reality

d75dc89

Signed-off-by: Ihor Farion <[email protected]>

handle edge case where there Circle returns 0x instead of a message f…

66f1b8e

…or pending attestations ... Signed-off-by: Ihor Farion <[email protected]>

remove unused fn

636604b

Signed-off-by: Ihor Farion <[email protected]>

grasphoper requested a review from pxrl May 28, 2025 20:21

pxrl reviewed May 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: finalize tokenless HubPool CCTP messages #2270

feat: finalize tokenless HubPool CCTP messages #2270

grasphoper commented May 24, 2025 •

edited

Loading

Uh oh!

Uh oh!

grasphoper commented May 28, 2025

Uh oh!

pxrl May 28, 2025

Uh oh!

grasphoper May 28, 2025

Uh oh!

pxrl May 28, 2025

Uh oh!

grasphoper May 28, 2025 •

edited

Loading

Uh oh!

pxrl May 28, 2025

Uh oh!

grasphoper May 28, 2025

Uh oh!

pxrl May 28, 2025

Uh oh!

grasphoper May 28, 2025

Uh oh!

pxrl May 28, 2025

Uh oh!

Uh oh!

feat: finalize *tokenless* HubPool CCTP messages #2270

Are you sure you want to change the base?

feat: finalize *tokenless* HubPool CCTP messages #2270

Conversation

grasphoper commented May 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

grasphoper commented May 28, 2025

Tested the following:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grasphoper May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

feat: finalize tokenless HubPool CCTP messages #2270

feat: finalize tokenless HubPool CCTP messages #2270

grasphoper commented May 24, 2025 •

edited

Loading

grasphoper May 28, 2025 •

edited

Loading