From a0585888bba064d3a36fd9a87480afa2c6c3fc9f Mon Sep 17 00:00:00 2001 From: riveign Date: Tue, 27 Jan 2026 11:21:41 +0100 Subject: [PATCH 1/9] feat: add Tron namespace with CAIP-2 specification - Add tron/ namespace directory with comprehensive documentation - Implement CAIP-2 blockchain ID specification using hexadecimal chain IDs - Implement CAIP-10 account ID specification for Base58Check addresses - Include test cases for Mainnet (0x2b6653dc), Shasta (0xcd8690dc), and Nile (0x94a9059e) - Document resolution methods using eth_chainId JSON-RPC - Follow TIP-474 standard for chain ID derivation from genesis block Co-Authored-By: Claude Sonnet 4.5 --- tron/README.md | 85 ++++++++++++++++++++++ tron/caip10.md | 189 +++++++++++++++++++++++++++++++++++++++++++++++++ tron/caip2.md | 155 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 429 insertions(+) create mode 100644 tron/README.md create mode 100644 tron/caip10.md create mode 100644 tron/caip2.md diff --git a/tron/README.md b/tron/README.md new file mode 100644 index 00000000..dc49a5be --- /dev/null +++ b/tron/README.md @@ -0,0 +1,85 @@ +--- +namespace-identifier: tron +title: Tron Ecosystem +author: WalletConnect Team +status: Draft +type: Informational +created: 2026-01-27 +--- + +# Namespace for Tron Chains + +This document describes the syntax and structure of the Tron namespace. +Tron is a decentralized blockchain platform that utilizes Delegated Proof of Stake (DPoS) consensus and features the Tron Virtual Machine (TVM), which is compatible with the Ethereum Virtual Machine (EVM). + +## Introduction + +Tron is a blockchain-based decentralized platform founded in 2017 that aims to build a free, global digital content entertainment system utilizing blockchain and distributed storage technology. +The Tron network supports smart contracts through its TVM (Tron Virtual Machine) and provides high throughput with approximately 2,000 transactions per second and 3-second block times. + +The Tron ecosystem includes: +- **Mainnet**: Production network for live applications +- **Shasta Testnet**: Testing environment compatible with mainnet parameters +- **Nile Testnet**: Bleeding-edge testing network for new features + +## Blockchain Identification + +Tron chains are identified using hexadecimal chain IDs derived from the last 4 bytes of their genesis block hashes, as specified in TIP-474. +This approach provides: +- Deterministic chain identification from genesis block +- Compatibility with EVM tooling through `eth_chainId` method +- Replay protection across networks +- Integration with existing blockchain infrastructure + +## Token Standards + +Tron supports multiple token standards: +- **TRC-20**: Fungible token standard (similar to ERC-20) +- **TRC-10**: Native token standard with lower transaction costs +- **TRC-721**: Non-fungible token (NFT) standard + +## Address Format + +Tron uses Base58Check encoding for addresses: +- All addresses start with the letter `T` +- Addresses are exactly 34 characters long +- Example: `TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL` + +## Network Information + +### Mainnet +- **RPC Endpoint**: `https://api.trongrid.io` +- **JSON-RPC Endpoint**: `https://api.trongrid.io/jsonrpc` +- **Explorer**: `https://tronscan.org` +- **Native Currency**: TRX (6 decimals, 1 TRX = 1,000,000 SUN) + +### Shasta Testnet +- **RPC Endpoint**: `https://api.shasta.trongrid.io` +- **JSON-RPC Endpoint**: `https://api.shasta.trongrid.io/jsonrpc` +- **Explorer**: `https://shasta.tronscan.org` +- **Faucet**: Available at https://www.trongrid.io/shasta + +### Nile Testnet +- **RPC Endpoint**: `https://nile.trongrid.io` +- **JSON-RPC Endpoint**: `https://nile.trongrid.io/jsonrpc` +- **Explorer**: `https://nile.tronscan.org` + +## References + +- [Tron Developer Hub][]: Official Tron development documentation +- [TIP-474][]: Tron Improvement Proposal specifying chain ID derivation +- [TronGrid][]: Official Tron API service +- [TronWeb][]: JavaScript SDK for Tron blockchain +- [Tronscan][]: Tron blockchain explorer + +[Tron Developer Hub]: https://developers.tron.network/ +[TIP-474]: https://github.com/tronprotocol/tips/blob/master/tip-474.md +[TronGrid]: https://www.trongrid.io/ +[TronWeb]: https://tronweb.network/ +[Tronscan]: https://tronscan.org/ +[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md +[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md + +## Rights + +Copyright and related rights waived via CC0. diff --git a/tron/caip10.md b/tron/caip10.md new file mode 100644 index 00000000..0ec383c0 --- /dev/null +++ b/tron/caip10.md @@ -0,0 +1,189 @@ +--- +namespace-identifier: tron-caip10 +title: Tron Namespace - Account ID Specification +author: WalletConnect Team +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/XXX +status: Draft +type: Standard +created: 2026-01-27 +requires: ["CAIP-2", "CAIP-10"] +--- + +# CAIP-10 + +*For context, see the [CAIP-10][] specification.* + +## Rationale + +Tron addresses use Base58Check encoding and are derived from ECDSA public keys using the secp256k1 curve (same as Ethereum). +All Tron addresses: +- Start with the letter `T` (due to the `0x41` address prefix) +- Are exactly 34 characters in length +- Include a 4-byte checksum for error detection +- Are case-sensitive + +The address format provides both human readability and built-in validation through the checksum mechanism. + +## Syntax + +The syntax of a Tron address follows Base58Check encoding with the following constraints: + +**Regular Expression**: `^T[1-9A-HJ-NP-Za-km-z]{33}$` + +Where: +- First character is always `T` +- Remaining 33 characters use Base58 alphabet (excluding 0, O, I, l) +- Total length is exactly 34 characters + +### Address Generation + +Tron addresses are generated through the following process: +1. Generate ECDSA key pair using secp256k1 curve +2. Extract 64-byte public key +3. Hash with Keccak256 (SHA3) +4. Take last 20 bytes of hash +5. Prepend address prefix byte `0x41` +6. Double SHA256 hash and append first 4 bytes as checksum +7. Base58 encode the result + +## Chain IDs + +*For context, see the [CAIP-2][] specification.* + +| Network | Chain ID (Hex) | Chain ID (CAIP-2) | +|----------------|----------------|--------------------| +| Mainnet | `0x2b6653dc` | `tron:0x2b6653dc` | +| Shasta Testnet | `0xcd8690dc` | `tron:0xcd8690dc` | +| Nile Testnet | `0x94a9059e` | `tron:0x94a9059e` | + +## Test Cases + +This is a list of manually composed and validated examples: + +```bash +# Tron Mainnet - Standard account address +tron:0x2b6653dc:TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL + +# Tron Mainnet - USDT TRC-20 contract address +tron:0x2b6653dc:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t + +# Tron Shasta Testnet +tron:0xcd8690dc:TQQg4EL8o1BSeKJY4MJ8TB8XK7xufxFBvK + +# Tron Nile Testnet +tron:0x94a9059e:TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH +``` + +## Address Validation + +### Valid Address Examples + +``` +TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL ✓ Valid mainnet address +TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t ✓ Valid mainnet address (USDT contract) +TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH ✓ Valid address +``` + +### Invalid Address Examples + +``` +tNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL ✗ Lowercase 't' (must be uppercase 'T') +TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYq ✗ Too short (33 characters) +TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeLL ✗ Too long (35 characters) +0x742d35Cc6634C0532925a3b844Bc9e759 ✗ Hex format (not Base58Check) +``` + +## Account Types + +Tron supports two types of accounts: + +1. **Externally Owned Account (EOA)**: + - Controlled by private key + - Can initiate transactions + - Example: `TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL` + +2. **Contract Account**: + - Smart contract address + - No private key + - Can only respond to transactions + - Example: `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` (USDT TRC-20) + +Both account types use the same address format and are indistinguishable at the address level. + +## Backwards Compatibility + +Tron's address format has remained consistent since mainnet launch. +All existing addresses are compatible with the CAIP-10 specification. + +## Additional Considerations + +### Checksum Validation + +The Base58Check encoding includes a 4-byte checksum that should be validated when accepting addresses. +Invalid checksums indicate: +- Typographical errors in address entry +- Data corruption +- Invalid address generation + +### Address Activation + +Tron addresses must be activated by receiving TRX or TRC-10 tokens before they appear on-chain. +Unactivated addresses: +- Are valid addresses (correct format and checksum) +- Do not appear in blockchain state queries +- Will be created upon receiving first transaction + +### Multi-signature Addresses + +Tron supports multi-signature accounts with the same address format. +Multi-sig addresses cannot be distinguished from regular addresses without querying account permissions on-chain. + +## Resolution Method + +To verify an address exists on-chain, make a JSON-RPC request using Tron's native RPC methods: + +```jsonc +// Request - Get account balance +{ + "jsonrpc": "2.0", + "method": "tron_getBalance", + "params": { + "address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL" + }, + "id": 1 +} + +// Response +{ + "jsonrpc": "2.0", + "result": { + "balance": "1000000000" + }, + "id": 1 +} +``` + +Alternatively, using Tron's native HTTP API: + +```bash +curl -X POST https://api.trongrid.io/wallet/getaccount \ + -d '{"address":"TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL","visible":true}' +``` + +## References + +- [CAIP-10][]: Account ID Specification +- [CAIP-2][]: Chain ID Specification +- [Tron Developer Hub - Accounts][]: Official account documentation +- [Tron Address Format][]: Technical specification for address generation +- [Base58Check Encoding][]: Bitcoin Base58Check encoding specification + +[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md +[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md +[Tron Developer Hub - Accounts]: https://developers.tron.network/docs/account +[Tron Address Format]: https://tronprotocol.github.io/documentation-en/mechanism-algorithm/account/ +[Base58Check Encoding]: https://en.bitcoin.it/wiki/Base58Check_encoding + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/tron/caip2.md b/tron/caip2.md new file mode 100644 index 00000000..e471b8c7 --- /dev/null +++ b/tron/caip2.md @@ -0,0 +1,155 @@ +--- +namespace-identifier: tron-caip2 +title: Tron Namespace - Blockchain ID Specification +author: WalletConnect Team +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/XXX +status: Draft +type: Standard +created: 2026-01-27 +requires: CAIP-2 +--- + +# CAIP-2 + +*For context, see the [CAIP-2][] specification.* + +## Rationale + +Tron uses hexadecimal chain IDs derived from the last 4 bytes of the genesis block hash, as specified in [TIP-474][]. +This approach provides several benefits: +- Deterministic derivation from the immutable genesis block +- Compatibility with EVM tooling and infrastructure +- Replay protection across different Tron networks +- Integration with existing blockchain registries like ChainList + +The chain ID mechanism was introduced to enable cross-chain compatibility and provide unique, verifiable identifiers for each Tron network. + +## Syntax + +The namespace "tron" refers to the Tron blockchain platform and its associated networks. + +### Reference Definition + +The reference format for Tron chains uses the hexadecimal representation of the chain ID, prefixed with `0x`. +This chain ID is derived from the last 4 bytes of the genesis block hash. + +**Format**: `tron:0x{chainId}` where `chainId` is an 8-character hexadecimal string (4 bytes) + +### Semantics + +The chain ID derivation follows this algorithm: +1. Query the genesis block (block height 0) +2. Extract the block hash +3. Take the last 4 bytes (8 hexadecimal characters) of the genesis block hash +4. Use this as the chain ID with `0x` prefix + +### Resolution Method + +Tron chain IDs are derived from the last 4 bytes of the genesis block hash and are static for each network. +Applications should use the following pre-determined chain IDs: + +| Network | Chain ID | Genesis Hash (last 4 bytes) | +|---------|----------|----------------------------| +| Mainnet | `0x2b6653dc` | `...2b6653dc` | +| Shasta | `0xcd8690dc` | `...cd8690dc` | +| Nile | `0x94a9059e` | `...94a9059e` | + +These chain IDs are deterministically derived and do not change. For verification purposes, you can query the genesis block to confirm the derivation, but the chain IDs themselves are constants that should be used for network identification. + +**Note**: Applications should use Tron-native RPC methods with the `tron_` prefix (e.g., `tron_getBalance`, `tron_signTransaction`). While Tron implements some EVM-compatible JSON-RPC endpoints (including `eth_chainId`) for tooling compatibility, these are secondary interfaces. The chain ID values remain the same regardless of which RPC interface is used. + +## Test Cases + +This is a list of manually composed and validated examples: + +```bash +# Tron Mainnet +tron:0x2b6653dc + +# Tron Shasta Testnet (mainnet-compatible testing) +tron:0xcd8690dc + +# Tron Nile Testnet (bleeding-edge features) +tron:0x94a9059e +``` + +### Chain ID Verification + +| Network | Chain ID (Hex) | Chain ID (Decimal) | Genesis Hash (last 4 bytes) | +|---------|----------------|--------------------|-----------------------------| +| Mainnet | `0x2b6653dc` | `728126428` | `...2b6653dc` | +| Shasta | `0xcd8690dc` | `3448148188` | `...cd8690dc` | +| Nile | `0x94a9059e` | `2494104990` | `...94a9059e` | + +### RPC Endpoints for Resolution + +- **Mainnet**: `https://api.trongrid.io/jsonrpc` +- **Shasta**: `https://api.shasta.trongrid.io/jsonrpc` +- **Nile**: `https://nile.trongrid.io/jsonrpc` + +## Backwards Compatibility + +Prior to TIP-474, Tron did not have a standardized chain ID mechanism for cross-chain identification. +The introduction of hexadecimal chain IDs maintains compatibility with: +- Existing EVM tooling and wallets (MetaMask, etc.) +- Blockchain registries (ChainList, ChainID.network) +- Cross-chain protocols and bridges + +Legacy integrations that predate TIP-474 should migrate to using the standardized hexadecimal chain IDs. + +## Additional Considerations + +### Genesis Block Hash Format + +The full genesis block hashes for reference: + +**Mainnet**: +``` +0x00000000000000001ebf88508a03865c71d452e25f4d51194196a1d22b6653dc +``` + +**Shasta Testnet**: +``` +0x0000000000000000d698d4192c56cb6be724a558448e2684802de4d6cd8690dc +``` + +**Nile Testnet**: +``` +0x0000000000000000de1aa88295e1fcf982742f773e0419c5a9c134c994a9059e +``` + +### Registry Information + +Tron chain IDs are registered in: +- [ChainList][]: Public registry of EVM and EVM-compatible chains +- [ChainID.network][]: Community-maintained chain ID database + +### Network Selection + +Applications should use: +- **Mainnet** for production deployments +- **Shasta** for testing with mainnet-compatible parameters +- **Nile** for testing bleeding-edge features before mainnet deployment + +## References + +- [CAIP-2][]: Chain ID Specification +- [TIP-474][]: Tron Improvement Proposal for chain ID optimization +- [Tron Developer Hub - Networks][]: Official network documentation +- [Tron Developer Hub - eth_chainId][]: Chain ID RPC method documentation +- [ChainList][]: Tron chain listings +- [TronGrid][]: Official Tron API service +- [Tronscan][]: Tron blockchain explorer + +[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md +[TIP-474]: https://github.com/tronprotocol/tips/blob/master/tip-474.md +[Tron Developer Hub - Networks]: https://developers.tron.network/docs/networks +[Tron Developer Hub - eth_chainId]: https://developers.tron.network/reference/eth_chainid +[ChainList]: https://chainlist.org/ +[ChainID.network]: https://chainid.network/ +[TronGrid]: https://www.trongrid.io/ +[Tronscan]: https://tronscan.org/ + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 07ecd655368ef10cc13b544e6d764d5a41887339 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Tue, 3 Feb 2026 16:37:56 +0100 Subject: [PATCH 2/9] Apply suggestion from @bumblefudge --- tron/caip10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tron/caip10.md b/tron/caip10.md index 0ec383c0..5eac05a1 100644 --- a/tron/caip10.md +++ b/tron/caip10.md @@ -1,7 +1,7 @@ --- namespace-identifier: tron-caip10 title: Tron Namespace - Account ID Specification -author: WalletConnect Team +author: Ignacio Rivera (@riveign), Daniel Rocha (@danroc) discussions-to: https://github.com/ChainAgnostic/namespaces/pull/XXX status: Draft type: Standard From 8f255d04f0425330d16e9d88b9365059045e636f Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Tue, 3 Feb 2026 16:38:26 +0100 Subject: [PATCH 3/9] Apply suggestion from @bumblefudge --- tron/caip2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tron/caip2.md b/tron/caip2.md index e471b8c7..f3a4dbbb 100644 --- a/tron/caip2.md +++ b/tron/caip2.md @@ -1,7 +1,7 @@ --- namespace-identifier: tron-caip2 title: Tron Namespace - Blockchain ID Specification -author: WalletConnect Team +author: Ignacio Rivera (@riveign), Daniel Rocha (@danroc) discussions-to: https://github.com/ChainAgnostic/namespaces/pull/XXX status: Draft type: Standard From 8063236cddc1005666fc4dde7a6ffc6d770ad1ab Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Tue, 3 Feb 2026 16:38:49 +0100 Subject: [PATCH 4/9] Apply suggestion from @bumblefudge --- tron/caip2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tron/caip2.md b/tron/caip2.md index f3a4dbbb..b30ad009 100644 --- a/tron/caip2.md +++ b/tron/caip2.md @@ -89,7 +89,7 @@ tron:0x94a9059e ## Backwards Compatibility -Prior to TIP-474, Tron did not have a standardized chain ID mechanism for cross-chain identification. +Prior to [TIP-474], Tron did not have a standardized chain ID mechanism for cross-chain identification. The introduction of hexadecimal chain IDs maintains compatibility with: - Existing EVM tooling and wallets (MetaMask, etc.) - Blockchain registries (ChainList, ChainID.network) From 2ce53550dee404d4af8c0194b13067efd5601bf6 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Tue, 3 Feb 2026 16:39:28 +0100 Subject: [PATCH 5/9] Apply suggestion from @bumblefudge --- tron/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tron/README.md b/tron/README.md index dc49a5be..c366bdf3 100644 --- a/tron/README.md +++ b/tron/README.md @@ -1,7 +1,7 @@ --- namespace-identifier: tron title: Tron Ecosystem -author: WalletConnect Team +author: Ignacio Rivera (@riveign), Daniel Rocha (@danroc) status: Draft type: Informational created: 2026-01-27 From 66f3d693156604bb1577012dd89c7024001981b8 Mon Sep 17 00:00:00 2001 From: riveign Date: Mon, 24 Aug 2026 17:35:26 +0200 Subject: [PATCH 6/9] feat(tron): use decimal chain IDs as canonical CAIP-2 reference Switches the tron namespace reference from the 0x-prefixed hexadecimal form to decimal, per the consensus reached in TRON Wallet Dev Community Call #5 (2026-08-19, tronprotocol/pm#229): tron:0x2b6653dc -> tron:728126428 (Mainnet) tron:0xcd8690dc -> tron:3448148188 (Shasta) tron:0x94a9059e -> tron:2494104990 (Nile) The underlying value is unchanged; only its rendering differs. Decimal matches the eth_chainId return type, Tron's existing ethereum-lists/chains registration, MetaMask and tronwallet-adapter, and the eip155 namespace. Backwards Compatibility now documents the hexadecimal form as a deprecated alias with a normalisation path rather than as the recommended target. Also addresses outstanding review feedback: - discussions-to points at PR #170 instead of the XXX placeholder - RPC endpoint list defers to the Tron Foundation networks doc as the authoritative source, since inlined URLs go stale Co-Authored-By: Claude Opus 5 (1M context) --- tron/README.md | 10 ++++----- tron/caip10.md | 20 ++++++++--------- tron/caip2.md | 58 +++++++++++++++++++++++++++++++------------------- 3 files changed, 51 insertions(+), 37 deletions(-) diff --git a/tron/README.md b/tron/README.md index c366bdf3..35140789 100644 --- a/tron/README.md +++ b/tron/README.md @@ -18,16 +18,16 @@ Tron is a blockchain-based decentralized platform founded in 2017 that aims to b The Tron network supports smart contracts through its TVM (Tron Virtual Machine) and provides high throughput with approximately 2,000 transactions per second and 3-second block times. The Tron ecosystem includes: -- **Mainnet**: Production network for live applications -- **Shasta Testnet**: Testing environment compatible with mainnet parameters -- **Nile Testnet**: Bleeding-edge testing network for new features +- **Mainnet** (`tron:728126428`): Production network for live applications +- **Shasta Testnet** (`tron:3448148188`): Testing environment compatible with mainnet parameters +- **Nile Testnet** (`tron:2494104990`): Bleeding-edge testing network for new features ## Blockchain Identification -Tron chains are identified using hexadecimal chain IDs derived from the last 4 bytes of their genesis block hashes, as specified in TIP-474. +Tron chains are identified using decimal chain IDs, the unsigned 32-bit integer value of the last 4 bytes of their genesis block hashes, as specified in TIP-474. This approach provides: - Deterministic chain identification from genesis block -- Compatibility with EVM tooling through `eth_chainId` method +- Compatibility with EVM tooling through the `eth_chainId` method, which returns the same integer - Replay protection across networks - Integration with existing blockchain infrastructure diff --git a/tron/caip10.md b/tron/caip10.md index 5eac05a1..c33ae0fd 100644 --- a/tron/caip10.md +++ b/tron/caip10.md @@ -2,7 +2,7 @@ namespace-identifier: tron-caip10 title: Tron Namespace - Account ID Specification author: Ignacio Rivera (@riveign), Daniel Rocha (@danroc) -discussions-to: https://github.com/ChainAgnostic/namespaces/pull/XXX +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/170 status: Draft type: Standard created: 2026-01-27 @@ -50,11 +50,11 @@ Tron addresses are generated through the following process: *For context, see the [CAIP-2][] specification.* -| Network | Chain ID (Hex) | Chain ID (CAIP-2) | -|----------------|----------------|--------------------| -| Mainnet | `0x2b6653dc` | `tron:0x2b6653dc` | -| Shasta Testnet | `0xcd8690dc` | `tron:0xcd8690dc` | -| Nile Testnet | `0x94a9059e` | `tron:0x94a9059e` | +| Network | Chain ID | Chain ID (CAIP-2) | +|----------------|--------------|-------------------| +| Mainnet | `728126428` | `tron:728126428` | +| Shasta Testnet | `3448148188` | `tron:3448148188` | +| Nile Testnet | `2494104990` | `tron:2494104990` | ## Test Cases @@ -62,16 +62,16 @@ This is a list of manually composed and validated examples: ```bash # Tron Mainnet - Standard account address -tron:0x2b6653dc:TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL +tron:728126428:TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL # Tron Mainnet - USDT TRC-20 contract address -tron:0x2b6653dc:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +tron:728126428:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t # Tron Shasta Testnet -tron:0xcd8690dc:TQQg4EL8o1BSeKJY4MJ8TB8XK7xufxFBvK +tron:3448148188:TQQg4EL8o1BSeKJY4MJ8TB8XK7xufxFBvK # Tron Nile Testnet -tron:0x94a9059e:TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH +tron:2494104990:TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH ``` ## Address Validation diff --git a/tron/caip2.md b/tron/caip2.md index b30ad009..c34adb7f 100644 --- a/tron/caip2.md +++ b/tron/caip2.md @@ -2,7 +2,7 @@ namespace-identifier: tron-caip2 title: Tron Namespace - Blockchain ID Specification author: Ignacio Rivera (@riveign), Daniel Rocha (@danroc) -discussions-to: https://github.com/ChainAgnostic/namespaces/pull/XXX +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/170 status: Draft type: Standard created: 2026-01-27 @@ -15,7 +15,7 @@ requires: CAIP-2 ## Rationale -Tron uses hexadecimal chain IDs derived from the last 4 bytes of the genesis block hash, as specified in [TIP-474][]. +Tron chain IDs are derived from the last 4 bytes of the genesis block hash, as specified in [TIP-474][], and are expressed in decimal — the same form returned by `eth_chainId` and used by the `eip155` namespace. This approach provides several benefits: - Deterministic derivation from the immutable genesis block - Compatibility with EVM tooling and infrastructure @@ -30,10 +30,10 @@ The namespace "tron" refers to the Tron blockchain platform and its associated n ### Reference Definition -The reference format for Tron chains uses the hexadecimal representation of the chain ID, prefixed with `0x`. -This chain ID is derived from the last 4 bytes of the genesis block hash. +The reference format for Tron chains is the decimal representation of the chain ID, an unsigned 32-bit integer. +This chain ID is the numeric value of the last 4 bytes of the genesis block hash. -**Format**: `tron:0x{chainId}` where `chainId` is an 8-character hexadecimal string (4 bytes) +**Format**: `tron:{chainId}` where `chainId` is the chain ID rendered in decimal, without leading zeroes ### Semantics @@ -41,7 +41,8 @@ The chain ID derivation follows this algorithm: 1. Query the genesis block (block height 0) 2. Extract the block hash 3. Take the last 4 bytes (8 hexadecimal characters) of the genesis block hash -4. Use this as the chain ID with `0x` prefix +4. Interpret those 4 bytes as a big-endian unsigned 32-bit integer +5. Render that integer in decimal ### Resolution Method @@ -50,9 +51,9 @@ Applications should use the following pre-determined chain IDs: | Network | Chain ID | Genesis Hash (last 4 bytes) | |---------|----------|----------------------------| -| Mainnet | `0x2b6653dc` | `...2b6653dc` | -| Shasta | `0xcd8690dc` | `...cd8690dc` | -| Nile | `0x94a9059e` | `...94a9059e` | +| Mainnet | `728126428` | `...2b6653dc` | +| Shasta | `3448148188` | `...cd8690dc` | +| Nile | `2494104990` | `...94a9059e` | These chain IDs are deterministically derived and do not change. For verification purposes, you can query the genesis block to confirm the derivation, but the chain IDs themselves are constants that should be used for network identification. @@ -64,25 +65,30 @@ This is a list of manually composed and validated examples: ```bash # Tron Mainnet -tron:0x2b6653dc +tron:728126428 # Tron Shasta Testnet (mainnet-compatible testing) -tron:0xcd8690dc +tron:3448148188 # Tron Nile Testnet (bleeding-edge features) -tron:0x94a9059e +tron:2494104990 ``` ### Chain ID Verification -| Network | Chain ID (Hex) | Chain ID (Decimal) | Genesis Hash (last 4 bytes) | -|---------|----------------|--------------------|-----------------------------| -| Mainnet | `0x2b6653dc` | `728126428` | `...2b6653dc` | -| Shasta | `0xcd8690dc` | `3448148188` | `...cd8690dc` | -| Nile | `0x94a9059e` | `2494104990` | `...94a9059e` | +| Network | Chain ID (Decimal) | Genesis Hash (last 4 bytes) | Hexadecimal Equivalent | +|---------|--------------------|-----------------------------|------------------------| +| Mainnet | `728126428` | `...2b6653dc` | `0x2b6653dc` | +| Shasta | `3448148188` | `...cd8690dc` | `0xcd8690dc` | +| Nile | `2494104990` | `...94a9059e` | `0x94a9059e` | + +The hexadecimal column is informative only; it shows the derivation from the genesis hash and is not a valid CAIP-2 reference. ### RPC Endpoints for Resolution +Endpoint URLs change over time. +The authoritative list is maintained by the Tron Foundation in [Tron Developer Hub - Networks][]; the values below are current at the time of writing. + - **Mainnet**: `https://api.trongrid.io/jsonrpc` - **Shasta**: `https://api.shasta.trongrid.io/jsonrpc` - **Nile**: `https://nile.trongrid.io/jsonrpc` @@ -90,12 +96,18 @@ tron:0x94a9059e ## Backwards Compatibility Prior to [TIP-474], Tron did not have a standardized chain ID mechanism for cross-chain identification. -The introduction of hexadecimal chain IDs maintains compatibility with: -- Existing EVM tooling and wallets (MetaMask, etc.) -- Blockchain registries (ChainList, ChainID.network) -- Cross-chain protocols and bridges -Legacy integrations that predate TIP-474 should migrate to using the standardized hexadecimal chain IDs. +Both a decimal and a `0x`-prefixed hexadecimal rendering of the same 4-byte value have circulated in the ecosystem. +This specification designates the decimal form as canonical, which keeps the namespace consistent with: +- The `eth_chainId` JSON-RPC method, whose return value is an integer +- Tron's existing registrations in [ethereum-lists/chains][] and [ChainList][] (`728126428` for Mainnet) +- Existing wallet implementations, including MetaMask and `tronwallet-adapter` +- The `eip155` namespace, which uses decimal references + +The decimal form was agreed as the canonical CAIP-2 representation for Tron in TRON Wallet Dev Community Call #5 on 2026-08-19; see [tronprotocol/pm#229][]. + +Implementations that previously emitted the hexadecimal form should treat it as a deprecated alias: accept `tron:0x2b6653dc` on input, normalise it to `tron:728126428`, and emit only the decimal form. +The underlying chain ID value is unchanged, so no address-level or on-chain migration is required. ## Additional Considerations @@ -147,6 +159,8 @@ Applications should use: [Tron Developer Hub - eth_chainId]: https://developers.tron.network/reference/eth_chainid [ChainList]: https://chainlist.org/ [ChainID.network]: https://chainid.network/ +[ethereum-lists/chains]: https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-728126428.json +[tronprotocol/pm#229]: https://github.com/tronprotocol/pm/issues/229 [TronGrid]: https://www.trongrid.io/ [Tronscan]: https://tronscan.org/ From 6bc4ee90f5c5e331042994f17c52d768167f8dd9 Mon Sep 17 00:00:00 2001 From: riveign Date: Mon, 24 Aug 2026 17:45:45 +0200 Subject: [PATCH 7/9] fix(tron): describe eth_chainId encoding accurately eth_chainId returns a base-16-encoded QUANTITY, not a decimal integer, so the previous wording ("the same form returned by eth_chainId") was wrong. The chain ID's underlying type is an integer; only its rendering differs per interface. Resolution Method now states the base-16 -> base-10 conversion explicitly, matching the equivalent sentence in eip155/caip2.md. Co-Authored-By: Claude Opus 5 (1M context) --- tron/README.md | 2 +- tron/caip2.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/tron/README.md b/tron/README.md index 35140789..40244994 100644 --- a/tron/README.md +++ b/tron/README.md @@ -27,7 +27,7 @@ The Tron ecosystem includes: Tron chains are identified using decimal chain IDs, the unsigned 32-bit integer value of the last 4 bytes of their genesis block hashes, as specified in TIP-474. This approach provides: - Deterministic chain identification from genesis block -- Compatibility with EVM tooling through the `eth_chainId` method, which returns the same integer +- Compatibility with EVM tooling through the `eth_chainId` method, which returns the same value base-16-encoded - Replay protection across networks - Integration with existing blockchain infrastructure diff --git a/tron/caip2.md b/tron/caip2.md index c34adb7f..d43193b7 100644 --- a/tron/caip2.md +++ b/tron/caip2.md @@ -15,7 +15,7 @@ requires: CAIP-2 ## Rationale -Tron chain IDs are derived from the last 4 bytes of the genesis block hash, as specified in [TIP-474][], and are expressed in decimal — the same form returned by `eth_chainId` and used by the `eip155` namespace. +Tron chain IDs are derived from the last 4 bytes of the genesis block hash, as specified in [TIP-474][], and are expressed in decimal, following the same convention as the `eip155` namespace. This approach provides several benefits: - Deterministic derivation from the immutable genesis block - Compatibility with EVM tooling and infrastructure @@ -59,6 +59,8 @@ These chain IDs are deterministically derived and do not change. For verificatio **Note**: Applications should use Tron-native RPC methods with the `tron_` prefix (e.g., `tron_getBalance`, `tron_signTransaction`). While Tron implements some EVM-compatible JSON-RPC endpoints (including `eth_chainId`) for tooling compatibility, these are secondary interfaces. The chain ID values remain the same regardless of which RPC interface is used. +When resolving via `eth_chainId`, the response is a base-16-encoded integer (e.g. `0x2b6653dc`) and must be converted to base 10 to form a CAIP-2 reference, as in the `eip155` namespace. + ## Test Cases This is a list of manually composed and validated examples: @@ -99,7 +101,7 @@ Prior to [TIP-474], Tron did not have a standardized chain ID mechanism for cros Both a decimal and a `0x`-prefixed hexadecimal rendering of the same 4-byte value have circulated in the ecosystem. This specification designates the decimal form as canonical, which keeps the namespace consistent with: -- The `eth_chainId` JSON-RPC method, whose return value is an integer +- The underlying type of the chain ID, which [TIP-474][] and the `CHAINID` opcode treat as an integer rather than a byte string - Tron's existing registrations in [ethereum-lists/chains][] and [ChainList][] (`728126428` for Mainnet) - Existing wallet implementations, including MetaMask and `tronwallet-adapter` - The `eip155` namespace, which uses decimal references From bc6c067b63d6adfb581a2eedabc8b414e56e32af Mon Sep 17 00:00:00 2001 From: riveign Date: Mon, 24 Aug 2026 17:48:38 +0200 Subject: [PATCH 8/9] fix(tron): correct swapped Shasta and Nile chain IDs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Shasta and Nile chain IDs — and their genesis block hashes — were attached to the wrong networks. Verified against three independent sources: - live eth_chainId on each network's JSON-RPC endpoint - live eth_getBlockByNumber("0x0") genesis hash on each network - the Tron Foundation's eth_chainId reference documentation Correct values: Shasta 0x94a9059e 2494104990 genesis ...94a9059e Nile 0xcd8690dc 3448148188 genesis ...cd8690dc Mainnet was already correct. Resolution Method now cites the Foundation's eth_chainId reference as the authoritative source for these values, addressing review feedback that inlined tables go stale. Co-Authored-By: Claude Opus 5 (1M context) --- tron/README.md | 4 ++-- tron/caip10.md | 8 ++++---- tron/caip2.md | 18 ++++++++++-------- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/tron/README.md b/tron/README.md index 40244994..1f59c30d 100644 --- a/tron/README.md +++ b/tron/README.md @@ -19,8 +19,8 @@ The Tron network supports smart contracts through its TVM (Tron Virtual Machine) The Tron ecosystem includes: - **Mainnet** (`tron:728126428`): Production network for live applications -- **Shasta Testnet** (`tron:3448148188`): Testing environment compatible with mainnet parameters -- **Nile Testnet** (`tron:2494104990`): Bleeding-edge testing network for new features +- **Shasta Testnet** (`tron:2494104990`): Testing environment compatible with mainnet parameters +- **Nile Testnet** (`tron:3448148188`): Bleeding-edge testing network for new features ## Blockchain Identification diff --git a/tron/caip10.md b/tron/caip10.md index c33ae0fd..660e01f8 100644 --- a/tron/caip10.md +++ b/tron/caip10.md @@ -53,8 +53,8 @@ Tron addresses are generated through the following process: | Network | Chain ID | Chain ID (CAIP-2) | |----------------|--------------|-------------------| | Mainnet | `728126428` | `tron:728126428` | -| Shasta Testnet | `3448148188` | `tron:3448148188` | -| Nile Testnet | `2494104990` | `tron:2494104990` | +| Shasta Testnet | `2494104990` | `tron:2494104990` | +| Nile Testnet | `3448148188` | `tron:3448148188` | ## Test Cases @@ -68,10 +68,10 @@ tron:728126428:TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL tron:728126428:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t # Tron Shasta Testnet -tron:3448148188:TQQg4EL8o1BSeKJY4MJ8TB8XK7xufxFBvK +tron:2494104990:TQQg4EL8o1BSeKJY4MJ8TB8XK7xufxFBvK # Tron Nile Testnet -tron:2494104990:TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH +tron:3448148188:TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH ``` ## Address Validation diff --git a/tron/caip2.md b/tron/caip2.md index d43193b7..38aff9c8 100644 --- a/tron/caip2.md +++ b/tron/caip2.md @@ -52,11 +52,13 @@ Applications should use the following pre-determined chain IDs: | Network | Chain ID | Genesis Hash (last 4 bytes) | |---------|----------|----------------------------| | Mainnet | `728126428` | `...2b6653dc` | -| Shasta | `3448148188` | `...cd8690dc` | -| Nile | `2494104990` | `...94a9059e` | +| Shasta | `2494104990` | `...94a9059e` | +| Nile | `3448148188` | `...cd8690dc` | These chain IDs are deterministically derived and do not change. For verification purposes, you can query the genesis block to confirm the derivation, but the chain IDs themselves are constants that should be used for network identification. +These values are published by the Tron Foundation in [Tron Developer Hub - eth_chainId][], which is the authoritative source should the table above fall out of date. They can also be confirmed at any time by calling `eth_chainId` or reading the genesis block on each network. + **Note**: Applications should use Tron-native RPC methods with the `tron_` prefix (e.g., `tron_getBalance`, `tron_signTransaction`). While Tron implements some EVM-compatible JSON-RPC endpoints (including `eth_chainId`) for tooling compatibility, these are secondary interfaces. The chain ID values remain the same regardless of which RPC interface is used. When resolving via `eth_chainId`, the response is a base-16-encoded integer (e.g. `0x2b6653dc`) and must be converted to base 10 to form a CAIP-2 reference, as in the `eip155` namespace. @@ -70,10 +72,10 @@ This is a list of manually composed and validated examples: tron:728126428 # Tron Shasta Testnet (mainnet-compatible testing) -tron:3448148188 +tron:2494104990 # Tron Nile Testnet (bleeding-edge features) -tron:2494104990 +tron:3448148188 ``` ### Chain ID Verification @@ -81,8 +83,8 @@ tron:2494104990 | Network | Chain ID (Decimal) | Genesis Hash (last 4 bytes) | Hexadecimal Equivalent | |---------|--------------------|-----------------------------|------------------------| | Mainnet | `728126428` | `...2b6653dc` | `0x2b6653dc` | -| Shasta | `3448148188` | `...cd8690dc` | `0xcd8690dc` | -| Nile | `2494104990` | `...94a9059e` | `0x94a9059e` | +| Shasta | `2494104990` | `...94a9059e` | `0x94a9059e` | +| Nile | `3448148188` | `...cd8690dc` | `0xcd8690dc` | The hexadecimal column is informative only; it shows the derivation from the genesis hash and is not a valid CAIP-2 reference. @@ -124,12 +126,12 @@ The full genesis block hashes for reference: **Shasta Testnet**: ``` -0x0000000000000000d698d4192c56cb6be724a558448e2684802de4d6cd8690dc +0x0000000000000000de1aa88295e1fcf982742f773e0419c5a9c134c994a9059e ``` **Nile Testnet**: ``` -0x0000000000000000de1aa88295e1fcf982742f773e0419c5a9c134c994a9059e +0x0000000000000000d698d4192c56cb6be724a558448e2684802de4d6cd8690dc ``` ### Registry Information From 3dd7eb92841763e55b1a6f5c0fa30f7194bf12d4 Mon Sep 17 00:00:00 2001 From: riveign Date: Wed, 26 Aug 2026 11:13:22 +0200 Subject: [PATCH 9/9] docs(tron): cite TronGrid documentation for RPC endpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses review feedback that the inlined endpoint list will go stale. The RPC section now points at both official pages — the TronGrid service docs and the per-network endpoint list — and frames the inlined values as non-normative rather than as the source of truth. Also notes TronGrid's rate limits and production API key expectation, which implementers resolving chain IDs over JSON-RPC will hit. Co-Authored-By: Claude Opus 5 (1M context) --- tron/caip2.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tron/caip2.md b/tron/caip2.md index 38aff9c8..a632a109 100644 --- a/tron/caip2.md +++ b/tron/caip2.md @@ -90,13 +90,15 @@ The hexadecimal column is informative only; it shows the derivation from the gen ### RPC Endpoints for Resolution -Endpoint URLs change over time. -The authoritative list is maintained by the Tron Foundation in [Tron Developer Hub - Networks][]; the values below are current at the time of writing. +The endpoints below are operated as part of [TronGrid][], the TRON network's hosted node service, which exposes JSON-RPC alongside its FullNode, SolidityNode and gRPC interfaces. +Rather than treating this list as normative, implementers should consult the official documentation, which is the authoritative and maintained source: [TronGrid][TronGrid Docs] for the service itself, and [Networks][Tron Developer Hub - Networks] for the per-network endpoints. - **Mainnet**: `https://api.trongrid.io/jsonrpc` - **Shasta**: `https://api.shasta.trongrid.io/jsonrpc` - **Nile**: `https://nile.trongrid.io/jsonrpc` +Note that TronGrid applies rate limits and expects an API key for production use; see the TronGrid documentation for current terms. + ## Backwards Compatibility Prior to [TIP-474], Tron did not have a standardized chain ID mechanism for cross-chain identification. @@ -153,6 +155,7 @@ Applications should use: - [TIP-474][]: Tron Improvement Proposal for chain ID optimization - [Tron Developer Hub - Networks][]: Official network documentation - [Tron Developer Hub - eth_chainId][]: Chain ID RPC method documentation +- [TronGrid Docs][]: Documentation for the TronGrid hosted node service - [ChainList][]: Tron chain listings - [TronGrid][]: Official Tron API service - [Tronscan][]: Tron blockchain explorer @@ -161,6 +164,7 @@ Applications should use: [TIP-474]: https://github.com/tronprotocol/tips/blob/master/tip-474.md [Tron Developer Hub - Networks]: https://developers.tron.network/docs/networks [Tron Developer Hub - eth_chainId]: https://developers.tron.network/reference/eth_chainid +[TronGrid Docs]: https://developers.tron.network/docs/trongrid [ChainList]: https://chainlist.org/ [ChainID.network]: https://chainid.network/ [ethereum-lists/chains]: https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-728126428.json