EIP-155 and CAIP-2 Chain ID Conflict Resolution

The Ethereum ecosystem standardized chainId as a uint256 via EIP-155 to prevent cross-chain replay attacks on EVM networks. This integer is embedded in transaction signatures and used by wallets to identify the target network. However, the EIP-155 registry is a voluntary, off-chain list with no on-chain enforcement of uniqueness. As the number of EVM chains, L2s, and appchains has exploded, the probability of two distinct networks selecting the same integer has become a material operational risk. When a collision occurs, a dapp or wallet that relies solely on the integer chainId cannot distinguish between the two networks, leading to user-facing errors such as displaying the wrong token balances, signing transactions for an unintended chain, or failing to establish a WalletConnect session.

WalletConnect and the Chain-Agnostic Improvement Proposals (CAIPs) address this by defining a canonical, globally unique identifier in CAIP-2: namespace:chainId. For EVM chains, the namespace is eip155, making the canonical ID eip155:1 for Ethereum mainnet. This simple prefixing creates a unique, parseable string that prevents collisions between EVM chains and chains from other namespaces like Solana (solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ). The core integration challenge is that most chain data sources—RPC endpoints, community chainlists, and legacy SDKs—still use the bare integer as the primary key. A robust multi-chain application must build and maintain a resolution layer that maps every integer chainId it encounters to its authoritative CAIP-2 identifier before using it as a key in any internal state, session, or UI component.

The operational impact of a collision or mis-resolution is severe. A wallet that uses the integer chainId as a key for cached token balances or NFT metadata will display incorrect assets if a user switches between two colliding networks. A dapp that constructs a CAIP-25 session proposal with an ambiguous integer may cause the wallet to scope the session to the wrong chain, potentially leading to a user signing a transaction on an unintended network. For exchanges and custody providers, a failure in chain ID resolution can result in deposits being credited to the wrong network's accounting system. The fix is not technically complex but requires disciplined engineering: all chain identifiers must be normalized to CAIP-2 at the system boundary, and any legacy integer must be treated as an untrusted input that requires resolution against a curated, conflict-checked registry before use.

The core conflict in multi-chain identity stems from a naming collision. EIP-155 introduced a simple integer-based chainId to prevent cross-chain transaction replay on Ethereum, a design that was later adopted by other EVM-compatible networks. However, this flat integer namespace is not globally unique across ecosystems. A dapp or wallet relying solely on an integer chainId cannot distinguish between, for example, the C-Chain on Avalanche (43114) and an entirely different L1 or testnet that might use the same integer. WalletConnect and the Chain-Agnostic Improvement Proposals (CAIPs) resolve this by introducing a hierarchical, namespace-prefixed identifier in CAIP-2, such as eip155:1 for Ethereum mainnet, creating a globally unique and human-readable chain reference.

The operational challenge for builders is that the legacy integer ID remains deeply embedded in JSON-RPC calls, smart contract opcodes, and user interface state. A robust resolution architecture must act as a translation layer, mapping the canonical CAIP-2 identifier to the integer chainId required for RPC communication, and vice-versa. This mapping is not always one-to-one; a single CAIP-2 namespace can contain multiple chains, and a dapp must maintain a registry to resolve a wallet_switchEthereumChain request for an integer ID back to the correct CAIP-2 reference for session management. Failure to implement this mapping correctly leads to 'unknown chain' errors, broken session resumption, and a fragmented user experience where a wallet cannot correctly display the network a dapp is requesting.

For teams integrating WalletConnect's Sign v2 protocol, the resolution layer is not a static configuration file but an active component of session negotiation. During a CAIP-25 handshake, a dapp proposes required and optional namespaces using CAIP-2 identifiers, and the wallet must validate these against its internal list of supported chains. This validation logic must handle edge cases like a dapp requesting an eip155 namespace without specifying a reference integer, or a wallet needing to map a user's manually added custom network RPC to a synthetic CAIP-2 identifier. A poorly designed resolution layer becomes a persistent source of support tickets and integration failures, directly impacting user trust and dapp retention.

Chainscore Labs can audit this critical mapping logic to ensure error-free network switching. Our review covers the completeness of the chain registry, the correctness of the bidirectional mapping between CAIP-2 identifiers and integer chainId values, and the robustness of the validation logic during session proposal and switching flows. We help teams move from a fragile, hardcoded list of integers to a canonical, namespace-aware resolution architecture that is resilient to chain additions and ecosystem evolution.