Skip to content

Decode ISM metadata#327

Open
benbenlijie wants to merge 2 commits into
hyperlane-xyz:mainfrom
benbenlijie:decode-ism-metadata
Open

Decode ISM metadata#327
benbenlijie wants to merge 2 commits into
hyperlane-xyz:mainfrom
benbenlijie:decode-ism-metadata

Conversation

@benbenlijie
Copy link
Copy Markdown

Summary

  • Decode relayer-provided mailbox.process(metadata, message) calldata for delivered messages.
  • Surface ISM metadata details for Message ID Multisig, Merkle Root Multisig, and Aggregation metadata.
  • Resolve and render the message's ISM security route, including routing/aggregation children, thresholds, validators, and child metadata where available.

Verification

  • pnpm run typecheck
  • pnpm run lint
  • pnpm run build

Closes #79

@benbenlijie benbenlijie requested a review from Xaroz as a code owner May 13, 2026 05:39
@vercel
Copy link
Copy Markdown

vercel Bot commented May 13, 2026

@benbenlijie is attempting to deploy a commit to the Abacus Works Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 13, 2026

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7365f96d-2087-49a8-b7a0-d916413f69ce

📥 Commits

Reviewing files that changed from the base of the PR and between 493d920 and d9bb3e3.

📒 Files selected for processing (3)
  • src/features/debugger/debugMessage.ts
  • src/features/debugger/types.ts
  • src/features/messages/cards/IsmDetailsCard.tsx
🚧 Files skipped from review as they are similar to previous changes (3)
  • src/features/debugger/types.ts
  • src/features/messages/cards/IsmDetailsCard.tsx
  • src/features/debugger/debugMessage.ts

📝 Walkthrough

Walkthrough

This PR decodes mailbox.process metadata, recursively describes ISM routing/modules on-chain, attaches typed metadata/route to debug results, and renders process metadata plus a nested security-route tree in the IsmDetailsCard UI.

Changes

ISM Metadata Decoding and Display

Layer / File(s) Summary
ISM Metadata Type Contracts
src/features/debugger/types.ts
MessageDebugResult.ismDetails gains optional metadata and route; adds IsmMetadataDetails, IsmMetadataRange, and IsmRouteModule exported types describing decoded metadata, ranges, proofs, and recursive route nodes.
ISM Analysis Entry Point and Orchestration
src/features/debugger/debugMessage.ts
Passes processTxHash and expectedMessageId into ISM analysis, expands imports (message-id and protocol helpers), and adds typed ISM-related constants/interfaces to support recursive description and metadata parsing.
Process Transaction Metadata Extraction and Decoding
src/features/debugger/debugMessage.ts
Adds tryFetchProcessMetadata and tryDecodeProcessCallsFromMulticall to pull mailbox.process calls from a process tx (optionally matching a computed message id) and decode multicall variants; introduces decodeIsmMetadata plus hex/byte helpers and aggregation-range parsing.
ISM Route Analysis and Emptiness Detection
src/features/debugger/debugMessage.ts
Adds tryDescribeIsmRoute to recursively probe routing/aggregation ISMs and assemble typed ismDetails.route; replaces simple multisig/threshold checks with routeHasEmptyMultisig traversal and adds tryGetModuleType and recursion depth limits.
ISM Details Card Metadata and Route Rendering
src/features/messages/cards/IsmDetailsCard.tsx
Conditionally renders a "Process Metadata" section when ismDetails.metadata exists and a recursive IsmRouteTree/IsmRouteNode showing module type, threshold, validators, and nested children; includes formatMetadataLabel helper.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 5.88% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'Decode ISM metadata' accurately captures the main change—adding ISM metadata decoding and route rendering capabilities to the debugger.
Description check ✅ Passed The description directly addresses the changeset by explaining metadata decoding, ISM details surfacing, and route resolution—all implemented in the code changes.
Linked Issues check ✅ Passed The PR fulfills issue #79's requirements by decoding mailbox.process metadata using SDK utilities and surfacing ISM metadata details and security routes in the UI.
Out of Scope Changes check ✅ Passed All changes in debugMessage.ts, types.ts, and IsmDetailsCard.tsx directly support the core objective of decoding and displaying ISM metadata without introducing unrelated functionality.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
src/features/messages/cards/IsmDetailsCard.tsx (1)

157-157: ⚡ Quick win

Use clsx for conditional className composition.

Quick cleanup: this conditional template string should use clsx() to match repo conventions and keep class handling consistent.

Proposed patch
+import clsx from 'clsx';
...
-    <div
-      className={`${depth ? 'ml-4 border-l border-gray-200 pl-3 dark:border-gray-700' : ''} space-y-2`}
-    >
+    <div
+      className={clsx(
+        'space-y-2',
+        depth && 'ml-4 border-l border-gray-200 pl-3 dark:border-gray-700',
+      )}
+    >
As per coding guidelines: "`**/*.{ts,tsx,jsx}`: Use `clsx()` for conditional classNames".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/features/messages/cards/IsmDetailsCard.tsx` at line 157, The className in
IsmDetailsCard's JSX (the template string using depth) should be replaced with
clsx() for consistent conditional class composition: import clsx from 'clsx' if
missing, then change the className expression on the element that currently uses
`${depth ? 'ml-4 border-l border-gray-200 pl-3 dark:border-gray-700' : ''}
space-y-2` to clsx('space-y-2', depth && 'ml-4 border-l border-gray-200 pl-3
dark:border-gray-700') so the conditional classes are composed via clsx.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/features/debugger/debugMessage.ts`:
- Around line 316-325: The routeHasEmptyMultisig(...) helper is falsely
classifying routes as empty when validators/threshold are simply unset due to
read failures; update it to only return true after a successful multisig read by
checking an explicit resolution flag (e.g. route.validatorsResolved or
route.multisigResolved) or by requiring both validators and threshold to be
present and marked as resolved before treating as empty; modify the logic in
routeHasEmptyMultisig (and the similar block around lines 339-393) to first
guard for a successful read flag on IsmRouteModule, then apply the existing
checks for moduleType, empty validators array, or threshold < 1, and otherwise
recurse into children.
- Around line 579-596: The function decodeAggregationRanges currently discards a
single valid parsed range by returning only when ranges.length > 1; change the
return condition to preserve a single-child result (i.e., return ranges when
ranges.length > 0 or simply return ranges if non-empty) so metadata?.ranges?.[0]
survives into tryDescribeIsmRoute; update decodeAggregationRanges (which uses
AGGREGATION_RANGE_SIZE, readUint32 and produces IsmMetadataDetails['ranges']) to
return the parsed ranges array when any ranges were found, otherwise return an
empty array.

---

Nitpick comments:
In `@src/features/messages/cards/IsmDetailsCard.tsx`:
- Line 157: The className in IsmDetailsCard's JSX (the template string using
depth) should be replaced with clsx() for consistent conditional class
composition: import clsx from 'clsx' if missing, then change the className
expression on the element that currently uses `${depth ? 'ml-4 border-l
border-gray-200 pl-3 dark:border-gray-700' : ''} space-y-2` to clsx('space-y-2',
depth && 'ml-4 border-l border-gray-200 pl-3 dark:border-gray-700') so the
conditional classes are composed via clsx.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3cea9696-c69a-45fb-8af5-e4015709c48b

📥 Commits

Reviewing files that changed from the base of the PR and between b2ce701 and e9ebaaa.

📒 Files selected for processing (3)
  • src/features/debugger/debugMessage.ts
  • src/features/debugger/types.ts
  • src/features/messages/cards/IsmDetailsCard.tsx

Comment thread src/features/debugger/debugMessage.ts
Comment thread src/features/debugger/debugMessage.ts Outdated
@benbenlijie
Copy link
Copy Markdown
Author

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 13, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@benbenlijie benbenlijie force-pushed the decode-ism-metadata branch from 493d920 to d9bb3e3 Compare May 17, 2026 01:24
@zhaog100
Copy link
Copy Markdown

Claiming this bounty. Will implement ISM metadata decoding.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Decode ISM metadata

2 participants