fix(tron): use hex chain id in CAIP-2 network identifiers by roger-gan · Pull Request #78 · BofAI/x402

roger-gan · 2026-07-06T06:25:02Z

Per upstream spec PR x402-foundation/x402#2076 review feedback, CAIP-2 network identifiers must use the hex chain id, not human-readable network names. Replaces all tron:mainnet/tron:nile/tron:shasta keys with tron:0x2b6653dc/tron:0xcd8690dc/tron:0x94a9059e across the codebase.

BREAKING CHANGE: network identifiers change from tron:mainnet/tron:nile to tron:0x2b6653dc/tron:0xcd8690dc. Clients and servers must be upgraded together — a mismatched pair will fail to interop. The tron: CAIP-2 namespace is still provisional pending CASA registration (ChainAgnostic/namespaces#170, #162).

Description

Tests

Checklist

I have formatted and linted my code
All new and existing tests pass
My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

Per upstream spec PR x402-foundation/x402#2076 review feedback, CAIP-2 network identifiers must use the hex chain id, not human-readable network names. Replaces all `tron:mainnet`/`tron:nile`/`tron:shasta` keys with `tron:0x2b6653dc`/`tron:0xcd8690dc`/`tron:0x94a9059e` across the codebase. BREAKING CHANGE: network identifiers change from `tron:mainnet`/`tron:nile` to `tron:0x2b6653dc`/`tron:0xcd8690dc`. Clients and servers must be upgraded together — a mismatched pair will fail to interop. The `tron:` CAIP-2 namespace is still provisional pending CASA registration (ChainAgnostic/namespaces#170, #162).

…king changeset Address PR review on hex CAIP-2 network id change: - README/JSDoc/CLAUDE.md: replace residual tron:nile|shasta|mainnet with hex ids (tron:0xcd8690dc/0x94a9059e/0x2b6653dc) so docs match the implementation and no longer cause Unknown TRON network errors - Export TRON_MAINNET/TRON_NILE/TRON_SHASTA from package entry so consumers can import canonical ids instead of copying opaque strings - Init BofAI changeset baseline + add major changeset for @bankofai/x402-tron documenting the breaking CAIP-2 id change - Update refund-network test mock to use the live Nile id

…ex chain ids - changeset: drop createAuthorizerTronSigner from the list of factories that throw on old network ids — it takes only a wallet (offline signing), no network param - .claude/rules/networks/tron.md: identifier is tron:<hexChainId>; update table to canonical constants + hex ids; clarify authorizer signer takes no network - .claude/rules/common/conventions.md, rules/CLAUDE.md, agents/code-reviewer.md: replace tron:<name>/tron:nile with hex ids so code-gen and review agents stop emitting the broken values - rpc.ts module doc: tron:<hexChainId>

matrix-agent116

Summary

Thanks for this — it's a clean, mechanical migration of the TRON CAIP-2 identifiers from human-readable names (tron:nile) to hex chain IDs (tron:0xcd8690dc), aligning with the upstream spec review feedback. I verified the source of truth (constants.ts, rpc.ts, utils.ts, shared/gasfree/config.ts, shared/tokens.ts, shared/batch-settlement/constants.ts) and every network-keyed map is updated consistently; all lookups are pure map lookups with no residual name-based parsing, so nothing breaks silently. The new TRON_MAINNET/TRON_NILE/TRON_SHASTA constants are defined and exported, the tron:* wildcard registration path still resolves the hex networks correctly, and a proper major changeset with a migration guide is included. Overall this looks correct and mergeable; a few minor points below.

Points

(question) Old-ID error paths / tests. The changeset promises that passing a legacy ID (tron:nile) now throws Unknown TRON network / No TRON RPC configured. That behavior follows from the map changes, but I don't see a test asserting it. Consider adding a small regression test so the "fail loud on old IDs" contract is locked in — this is the main safety net for the breaking change.
(suggestion) Cross-language / cross-repo interop. The identifiers are now hex-only in TypeScript. If any other component or downstream consumer (e.g. a Python facilitator, or the GasFree relayer proxy that keys on the network segment) still emits or expects tron:nile-style IDs, a mismatched pair will silently fail to interop — exactly the breakage called out in the PR body. Could you confirm there's no counterpart that still speaks the old identifiers? (I couldn't find a Python package in this repo, so this may be a non-issue here.)
(nit) Unrelated formatting churn. A couple of files carry formatting-only reflows that aren't part of the rename (the @bankofai/x402-core/utils import wrap in exact/server/scheme.ts and upto/server/scheme.ts, the fee-type export in index.ts, and a few multi-line arg reflows in signer.ts/tests). These are harmless but add noise to a large diff — fine to keep if they're just the formatter running, just flagging.
(note) Provisional namespace. As you note, tron: is still provisional pending CASA registration. No action needed for this PR; just worth tracking so we don't have to do a second breaking rename later if the final namespace differs.

Once the migration test is added (or you confirm it's covered elsewhere), I'm happy to approve.

matrix-agent116 · 2026-07-06T12:16:09Z

+reference (e.g. `tron:0xcd8690dc` for Nile) instead of the human-readable name
+(`tron:nile` / `tron:shasta` / `tron:mainnet`). Passing the old string IDs to the
+signer factories (`createClientTronSigner`, `createFacilitatorTronSigner`)
+or to `getTronChainId` / RPC resolution now throws


[question] The changeset states that passing old IDs to getTronChainId / RPC resolution now throws Unknown TRON network / No TRON RPC configured. This follows correctly from the map changes, but I don't see a regression test asserting it. Consider adding one so the "fail loud on legacy IDs" contract is protected against accidental future regressions.

matrix-agent116 · 2026-07-06T12:16:09Z

  MoneyParser,
 } from "@bankofai/x402-core/types";
-import { convertToTokenAmount, numberToDecimalString, parseMoneyString } from "@bankofai/x402-core/utils";
+import {


[nit] This import reflow (single-line → multi-line) is formatting-only and unrelated to the CAIP-2 rename. Same pattern appears in upto/server/scheme.ts. Harmless if it's just the formatter, but it adds noise to an already large diff.

matrix-agent116 · 2026-07-06T12:16:09Z

-  type FeeInfo,
-  type ExactTronFeeConfig,
-} from "./shared/fee";
+export { type FeeInfo, type ExactTronFeeConfig } from "./shared/fee";


[nit] This fee-type export reflow is a formatting-only change unrelated to the rename. Fine to keep, just flagging as churn.

roger-gan added 3 commits July 3, 2026 19:47

matrix-agent116 reviewed Jul 6, 2026

View reviewed changes

Will-Guan approved these changes Jul 7, 2026

View reviewed changes

roger-gan requested a review from matrix-agent116 July 7, 2026 06:03

roger-gan merged commit e158640 into main Jul 7, 2026
1 of 2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(tron): use hex chain id in CAIP-2 network identifiers#78

fix(tron): use hex chain id in CAIP-2 network identifiers#78
roger-gan merged 3 commits into
mainfrom
fix/tron-caip2-chain-id

roger-gan commented Jul 6, 2026

Uh oh!

matrix-agent116 left a comment

Uh oh!

matrix-agent116 Jul 6, 2026

Uh oh!

matrix-agent116 Jul 6, 2026

Uh oh!

matrix-agent116 Jul 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

roger-gan commented Jul 6, 2026

Description

Tests

Checklist

Uh oh!

matrix-agent116 left a comment

Choose a reason for hiding this comment

Summary

Points

Uh oh!

matrix-agent116 Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

matrix-agent116 Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

matrix-agent116 Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants