fix: improve cctp v2 offchain lookup service

[yorhodes]

Description

• Pipe delay reason from CCTP API through to relayer

Drive-by changes

Related issues

Fixes opaque error

CCIP-read metadata fetch failed for http://localhost:3000/cctp/getCctpAttestation: TypeError: Cannot read properties of undefined (reading 'startsWith')

Backward compatibility

Testing

Manual

$ yarn hyperlane status --private-key $(hypkey) --origin base --relay --dispatchTx 0xf78db32e5c77317a25b94608016ea19e4f22aaf337b1ab39ae6052d0d967c9a1
Hyperlane CLI
Checking status of message 0x6a1e2bbf3e46e356157f7568500429e2f789300fa309add0afc746fe7216fec9 on hyperevm
Message 0x6a1e2bbf3e46e356157f7568500429e2f789300fa309add0afc746fe7216fec9 was not yet delivered
Preparing to relay message 0x6a1e2bbf3e46e356157f7568500429e2f789300fa309add0afc746fe7216fec9
Server http://localhost:3000/cctp/getCctpAttestation responded with error: CCTP attestation is pending due to insufficient_fee
Failed to relay message 0x6a1e2bbf3e46e356157f7568500429e2f789300fa309add0afc746fe7216fec9, Error: Could not fetch CCIP-read metadata

Summary by CodeRabbit

• Bug Fixes

  • Improved attestation handling to detect/report pending/delayed states, fail gracefully, and handle malformed JSON more robustly.
  • More resilient metadata fetch: continues to next source on failures and safer JSON parsing.

• New Features

  • Attestation responses now expose additional fields for message version, status, and delay reasons.

• Refactor

  • Streamlined response handling into a two-step fetch-and-parse flow for reliability.

• Chores

  • Added monitoring hooks for attestation parse and pending errors.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

---

Note

Enhances CCTP attestation error handling (pending/JSON-parse with metrics) and hardens CCIP-read metadata fetch with safe JSON/0x handling and retries across URLs.

• ccip-server:
  • Improve CCTPAttestationService handling of CCTP v2 responses: parse JSON safely, detect PENDING attestations, and log delay reasons; emit new Prometheus error metrics (cctp_attestation_service_json_parse_error, cctp_attestation_service_pending).
  • Extend CCTP message schema with eventNonce, optional cctpVersion, status, and delayReason.
• sdk:
  • Make CCIP-read metadata fetching more robust: separate fetch from JSON parsing, continue on failures, and ensure hex via ensure0x before returning.

^{Written by Cursor Bugbot for commit e57b5b1. This will update automatically on new commits. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: e57b5b1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
@hyperlane-xyz/ccip-server	Patch
@hyperlane-xyz/sdk	Patch
@hyperlane-xyz/cli	Patch
@hyperlane-xyz/helloworld	Patch
@hyperlane-xyz/http-registry-server	Patch
@hyperlane-xyz/infra	Patch
@hyperlane-xyz/widgets	Patch
solhint-plugin-hyperlane	Patch
@hyperlane-xyz/cosmos-sdk	Patch
@hyperlane-xyz/cosmos-types	Patch
@hyperlane-xyz/eslint-config	Patch
@hyperlane-xyz/github-proxy	Patch
@hyperlane-xyz/radix-sdk	Patch
@hyperlane-xyz/tsconfig	Patch
@hyperlane-xyz/utils	Patch
@hyperlane-xyz/starknet-core	Patch
@hyperlane-xyz/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cursor]

This PR is being reviewed by Cursor Bugbot

Details

You are on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 92872d1 and 0ec4364.

📒 Files selected for processing (4)

• .changeset/fuzzy-yaks-pull.md (1 hunks)
• typescript/ccip-server/src/services/CCTPAttestationService.ts (2 hunks)
• typescript/ccip-server/src/utils/prometheus.ts (1 hunks)
• typescript/sdk/src/ism/metadata/ccipread.ts (3 hunks)

✅ Files skipped from review due to trivial changes (1)

• .changeset/fuzzy-yaks-pull.md

🚧 Files skipped from review as they are similar to previous changes (1)

• typescript/sdk/src/ism/metadata/ccipread.ts

🧰 Additional context used

🧬 Code graph analysis (1)

typescript/ccip-server/src/services/CCTPAttestationService.ts (1)

typescript/ccip-server/src/utils/prometheus.ts (1)

• PrometheusMetrics (47-57)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: build-and-push-to-gcr
• GitHub Check: lint-rs
• GitHub Check: lander-coverage
• GitHub Check: test-rs
• GitHub Check: Cursor Bugbot

🔇 Additional comments (3)

typescript/ccip-server/src/utils/prometheus.ts (1)

30-31: Clean addition for CCTP v2 error tracking.

These new enum members follow the existing naming pattern and will help classify JSON parse failures and pending-state scenarios. Good stuff.

typescript/ccip-server/src/services/CCTPAttestationService.ts (2)

9-14: Type definitions align with CCTP v2 API spec.

The DelayReason and Status types correctly model the v2 response structure. Nice reference to the docs, too.

---

16-24: Let me dig deeper into the codebase to see how v1 and v2 responses are handled:

Let me search the codebase for how v1 and v2 responses are actually handled:

Let me search the codebase to understand how responses are parsed and where eventNonce comes from:

Perfect. I found the official API documentation. Let me verify the V2 structure as well:

No action needed — eventNonce is present in CCTP V1 API responses.

The Circle API documentation for V1 messages confirms eventNonce is returned in the response alongside message and attestation fields, making it a required field across both protocol versions. The interface is correctly structured with eventNonce required and the v2-specific fields (cctpVersion, status, delayReason) marked optional.

Likely an incorrect or invalid review comment.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 0.00%. Comparing base (5ed3e33) to head (e57b5b1).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files

@@     Coverage Diff      @@
##   main   #7334   +/-   ##
============================
============================

Components	Coverage Δ
core	∅ <ø> (∅)
hooks	∅ <ø> (∅)
isms	∅ <ø> (∅)
token	∅ <ø> (∅)
middlewares	∅ <ø> (∅)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.