wallet_updateEthereumChain RPC Method
The EIP-2015 proposal adds a new method to a wallet's web3 provider API called wallet_updateEthereumChain. This method is used to switch to a network and register it with the wallet if it isn't already recognized. It takes one parameter, an EthereumChainSwitchRequest object, which includes information about the chain being switched to. The method returns true if the chain was successfully added or switched to, and an error if the user rejected the request. The proposal also includes security considerations, such as sanitizing RPC URLs and storing a default list of commonly-used chains to avoid phishing attacks.
Video
Original
Abstract
This EIP adds a wallet-namespaced RPC endpoint, wallet_updateEthereumChain
, providing a standard interface for switching chains. The method takes the minimal parameters of chainId
, chainName
, rpcUrl
, nativeCurrency
and blockExplorerUrl
.
Specification
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
This proposal adds a method to a wallet's web3 provider API: wallet_updateEthereumChain
.
wallet_updateEthereumChain
The wallet_updateEthereumChain
method is used to switch to a network, and registering it with the wallet if it isn't already recognized.
The wallet_updateEthereumChain
method takes one parameter, an EthereumChainSwitchRequest
object, defined below:
interface NativeCurrencyData { name: string; symbol: string; decimals: number; } interface EthereumChainSwitchRequest { chainId: string; chainName?: string; rpcUrls?: string[]; nativeCurrency?: NativeCurrencyData; blockExplorerUrl?: string; }
The chainId
is the 0x
-prefixed EIP-155-compliant chain ID. The chainName
is a suggested human-readable name of the chain, to be displayed to the user. The rpcUrls
array is a list of RPC endpoints for the given chainId
. The nativeCurrency
object suggests how the native currency should be displayed. Its parameters, name
, symbol
, and decimals
, should be interpreted like in ERC-20. Finally, the blockExplorerUrl
should link to a block explorer compatible with the given chainId
.
All keys other than the chainId
are optional. All keys other than chainId
are suggestions to the wallet. Wallets can choose to ignore or display other data to users. Wallets should prompt the user before switching or adding chains. Wallets should also store a default list of data for commonly-used chains, in order to avoid phishing attacks. Wallets MUST sanitize each RPC url before using it to send other requests, including ensuring that it responds correctly to the net_version
and eth_chainId
methods.
The wallet_updateEthereumChain
method returns true
if the active chain matches the requested chain, regardless of whether the chain was already active or was added to the wallet previously. If the user rejects the request, it must return an error with code 4001
.
Rationale
The wallet_updateEthereumChain
method is designed to be as simple as possible, while still providing the necessary information for a wallet to switch to a new chain. The chainId
is the only required parameter, as it is the only parameter that is guaranteed to be unique. The chainName
is included to provide a human-readable name for the chain, and the rpcUrls
array is included to provide a list of RPC endpoints for the chain. The nativeCurrency
object is included to provide a suggestion for how the native currency should be displayed. Finally, the blockExplorerUrl
is included to provide a link to a block explorer for the chain.
The wallet_updateEthereumChain
method is namespaced under wallet_
to avoid conflicts with other methods. The wallet_
prefix is used by other methods that are wallet-specific, such as wallet_addEthereumChain
and wallet_switchEthereumChain
.
Backwards Compatibility
This EIP is fully backwards compatible.
Security Considerations
Server-Side Request Forgery (SSRF)
The rpcUrls
parameter is a list of RPC endpoints for the chain. Wallets should sanitize each RPC url before using it to send other requests, including ensuring that it responds correctly to the net_version
and eth_chainId
methods.
Phishing
Wallets should store a default list of data for commonly-used chains, in order to avoid phishing attacks.
Copyright
Copyright and related rights waived via CC0.
Adopted by projects
Not miss a beat of EIPs' update?
Subscribe EIPs Fun to receive the latest updates of EIPs Good for Buidlers to follow up.
View all