--- eip: 3085 title: wallet_addEthereumChain RPC Method description: Adds an RPC method to add EVM-compatible chains author: Erik Marks (@rekmarks), Pedro Gomes (@pedrouid), Pandapip1 (@Pandapip1) discussions-to: https://ethereum-magicians.org/t/eip-3085-wallet-addethereumchain/5469 status: Stagnant type: Standards Track category: Interface created: 2020-11-01 requires: 155 --- ## Abstract This EIP adds a wallet-namespaced RPC method: `wallet_addEtherereumChain`, providing a standard interface for adding chains to Ethereum wallets. ## 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 defines a new RPC method, `wallet_addEthereumChain`. ### `wallet_addEthereumChain` The `wallet_addEthereumChain` method is used to suggest to the wallet that a new chain be added to the wallet's list of chains. It takes a single parameter and returns `null` if the chain was added successfully, or an error if the chain was not added. #### `wallet_addEthereumChain` Parameters The `wallet_addEthereumChain` method takes a single parameter, an `EthereumChainAddRequest` object, which is defined as follows: ```typescript interface AddEthereumChainParameter { chainId: string; blockExplorerUrls?: string[]; chainName?: string; iconUrls?: string[]; nativeCurrency?: { name: string; symbol: string; decimals: number; }; rpcUrls?: string[]; } ``` Only the `chainId` is required per this specification, but a wallet MAY require any other fields listed, impose additional requirements on them, or ignore them outright. If a field does not meet the requirements of this specification and the wallet does not ignore the field, the wallet MUST reject the request. The `chainId` is the integer ID of the chain as a hexadecimal string, as per [EIP-155](./eip-155.md). The `blockExplorerUrls`, `iconUrls`, and `rpcUrls` fields are arrays of strings, each of which MUST be a valid URL. The `nativeCurrency` field is an object with `name`, `symbol`, and `decimals` fields, where `decimals` is a non-negative integer, and is to be interpreted like in [EIP-20](./eip-20.md). The `chainName` field is a string that is the human-readable name of the chain. The wallet MUST reject the request if the `chainId` is not a valid hexadecimal string, or if the `chainId` is not a valid chain ID. The wallet MUST reject the request if the `rpcUrls` field is not provided, or if the `rpcUrls` field is an empty array. The wallet MUST reject the request if the `rpcUrls` contains any strings that are not valid URLs. The wallet must reject the request if the `chainId` does not match the value of the `eth_chainId` method for any of the RPC urls. The wallet MUST reject the request if the `nativeCurrency` field is provided, and any of the `name`, `symbol`, or `decimals` fields are missing. The wallet MUST reject the request if the `decimals` field is a negative integer. The wallet MUST reject the request if the `blockExplorerUrls` field is provided, and any of the URLs are not valid URLs. The wallet MUST reject the request if the `iconUrls` field is provided, and any of the URLs are not valid URLs or do not point to a valid image. The wallet MUST reject any URLs that use the `file:` or `http:` schemes. #### `wallet_addEthereumChain` Returns The method MUST return `null` if the request was successful, and an error otherwise. The wallet MAY reject the request for any reason. The chain MUST NOT be assumed to be automatically selected by the wallet, even if the wallet does not reject the request. A request to add a chain that was already added SHOULD be successful, unless the user declines the request or the validation fails. The wallet MUST NOT allow the same `chainId` to be added multiple times. See [Security Considerations](#security-considerations) for more information. ## Rationale The design of `wallet_addEthereumChain` is deliberately ignorant of what it means to "add" a chain to a wallet. The meaning of "adding" a chain to a wallet depends on the wallet implementation. When calling the method, specifying the `chainId` will always be necessary, since in the universe of Ethereum chains, the [EIP-155](./eip-155.md) chain ID is effectively the chain GUID. The remaining parameters amount to what, in the estimation of the authors, a wallet will minimally require in order to effectively support a chain and represent it to the user. The network ID (per the `net_version` RPC method) is omitted since it is effectively superseded by the chain ID. For [security reasons](#security-considerations), a wallet should always attempt to validate the chain metadata provided by the requester, and may choose to fetch the metadata elsewhere entirely. Either way, only the wallet can know which chain metadata it needs from the requester in order to "add" the chain. Therefore, all parameters except `chainId` are specified as optional, even though a wallet may require them in practice. This specification does not mandate that the wallet "switches" its "active" or "currently selected" chain after a successful request, if the wallet has a concept thereof. Just like the meaning of "adding" a chain, "switching" between chains is a wallet implementation detail, and therefore out of scope. ## Security Considerations `wallet_addEthereumChain` is a powerful method that exposes the end user to serious risks if implemented incorrectly. Many of these risks can be avoided by validating the request data in the wallet, and clearly disambiguating different chains in the wallet UI. ### Chain IDs Since the chain ID used for transaction signing determines which chain the transaction is valid for, handling the chain ID correctly is of utmost importance. The wallet should: - Ensure that a submitted chain ID is valid. - It should be a `0x`-prefixed hexadecimal string per [EIP-695](./eip-695.md), and parse to an integer number. - Prevent the same chain ID from being added multiple times. - See the next section for how to handle multiple RPC endpoints. - Only use the submitted chain ID to sign transactions, **never** a chain ID received from an RPC endpoint. - A malicious or faulty endpoint could return arbitrary chain IDs, and potentially cause the user to sign transactions for unintended chains. - Verify that the specified chain ID matches the return value of `eth_chainId` from the endpoint, as described above. ### RPC Endpoints and RPC URLs Wallets generally interact with chains via an RPC endpoint, identified by some URL. Most wallets ship with a set of chains and corresponding trusted RPC endpoints. The endpoints identified by the `rpcUrls` parameter cannot be assumed to be honest, correct, or even pointing to the same chain. Moreover, even trusted endpoints can expose users to privacy risks depending on their data collection practices. Therefore, the wallet should: - Inform users that their on-chain activity and IP address will be exposed to RPC endpoints. - If an endpoint is unknown to the wallet, inform users that the endpoint may behave in unexpected ways. - Observe good web security practices when interacting with the endpoint, such as require HTTPS. - Clearly inform the user which RPC URL is being used to communicate with a chain at any given moment, and inform the user of the risks of using multiple RPC endpoints to interact with the same chain. ### Validating Chain Data A wallet that implements `wallet_addEthereumChain` should expect to encounter requests for chains completely unknown to the wallet maintainers. That said, community resources exist that can be leveraged to verify requests for many Ethereum chains. The wallet should maintain a list of known chains, and verify requests to add chains against that list. Indeed, a wallet may even prefer its own chain metadata over anything submitted with a `wallet_addEthereumChain` request. ### UX Adding a new chain to the wallet can have significant implications for the wallet's functionality and the experience of the user. A chain should never be added without the explicit consent of the user, and different chains should be clearly differentiated in the wallet UI. In service of these goals, the wallet should: - When receiving a `wallet_addEthereumChain` request, display a confirmation informing the user that a specific requester has requested that the chain be added. - Ensure that any chain metadata, such as `nativeCurrency` and `blockExplorerUrls`, are validated and used to maximum effect in the UI. - If any images are provided via `iconUrls`, ensure that the user understands that the icons could misrepresent the actual chain added. - If the wallet UI has a concept of a "currently selected" or "currently active" chain, ensure that the user understands when a chain added using `wallet_addEthereumChain` becomes selected. ### Preserving User Privacy Although a request to add a chain that was already added should generally be considered a success, treating such requests as _automatic_ successes leaks information to requesters about the chains a user has added to their wallet. In the interest of preserving user privacy, implementers of `wallet_addEthereumChain` should consider displaying user confirmations even in these cases. If the user denies the request, the wallet should return the same user rejection error as normal so that requesters cannot learn which chains are supported by the wallet without explicit permission to do so. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).