EIP-695 Addition of the eth_chainId JSON-RPC method (Create `eth_chainId` method for JSON-RPC)

Final · Networking & nodes · EIP status Final · created 2017-08-21

Adds eth_chainId to JSON-RPC, a standard query method that lets wallets or apps ask an Ethereum node "which chain am I connected to right now?"

Why it is needed

Wallets or apps do not connect to the blockchain directly; instead they communicate with a chain through a node's query interface (JSON-RPC). Before this EIP, only net_version existed, which asks for the network ID, and there was no way to ask for the chain ID actually used in signing. The chain ID is a value introduced by EIP-155, and it is the key ingredient that prevents a signature made on one chain from being reused on another (a replay attack). Without a way to check this value, an app meant for Ethereum (ETH) could be mistakenly connected to an Ethereum Classic (ETC) node without anyone noticing until a transaction was actually signed. Wallets such as MetaMask actually ran into this problem while adding support for multiple chains. So a dedicated method to immediately check the connected chain was needed.

What changes

Today

After EIP-695

Who is affected

In depth

Method definition and guarantee of being up to date with the latest block

eth_chainId returns the currently configured chain ID. This value is the CHAIN_ID used in the replay-protected transaction signatures introduced by EIP-155. The specification requires that the returned chain ID always match the information of the currently known head block. This is to guarantee that the caller can use the returned value as is to sign a transaction built on top of the head. If the current head block has no chain ID specified, the client must treat this method as unsupported and return an appropriate error.

Parameters and return format

There are no parameters. The return value is of type QUANTITY, representing the current chain ID as a single hexadecimal string. The encoding follows Ethereum JSON-RPC's standard hexadecimal value encoding rules. In the original example, a request of {"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":83} returns "0x3d" (decimal 61) as the result.

Why net_version is not enough

net_version only returns the network ID and does not tell you the chain ID. So a client meant for ETH could be mistakenly connected to an ETC RPC endpoint, or vice versa, and there would be no way to know until a transaction was actually signed or a transaction known to be signed with a specific chain ID was fetched. The original text states that this problem actually caused difficulty for application developers such as those building MetaMask when adding multi-chain support.

Security considerations

The original text recommends using eth_chainId over net_version so that consumers can reliably identify the chain they are communicating with. Since the chain ID is a value critical to preventing replay attacks as described in EIP-155, and consumers will come to rely on it for chain identification, implementers must implement eth_chainId correctly and actively publicize its use.

Status and implementation status

This EIP is a Standards Track proposal in the Interface category, with status Final. The specification is finalized and will not change further. The original text links implementation PRs for three clients: Parity, Geth, and Geth Classic. The Backwards Compatibility section is marked Not relevant.

Original EIP · ← EIPs