diff --git a/EIPS/eip-3326.md b/EIPS/eip-3326.md new file mode 100644 index 00000000..800144b1 --- /dev/null +++ b/EIPS/eip-3326.md @@ -0,0 +1,130 @@ +--- +eip: 3326 +title: Wallet Switch Ethereum Chain RPC Method (`wallet_switchEthereumChain`) +author: Erik Marks (@rekmarks) +discussions-to: https://ethereum-magicians.org/t/eip-3326-wallet-switchethereumchain +status: Draft +type: Standards Track +category: Interface +created: 2021-03-04 +requires: 155, 695 +--- + +## Simple Summary + +An RPC method for switching the wallet's active Ethereum chain. + +## Abstract + +The `wallet_switchEthereumChain` RPC method allows Ethereum applications ("dapps") to request that the wallet switches its active Ethereum chain, if the wallet has a concept thereof. +The caller must specify a chain ID. +The wallet application may arbitrarily refuse or accept the request. +`null` is returned if the active chain was switched, and an error otherwise. + +Important cautions for implementers of this method are included in the [Security Considerations](#security-considerations) section. + +## Motivation + +All dapps require the user to interact with one or more Ethereum chains in order to function. +Some wallets only supports interacting with one chain at a time. +We call this the wallet's "active chain". +`wallet_switchEthereumChain` enables dapps to request that the wallet switches its active chain to whichever one is required by the dapp. +This enables UX improvements for both dapps and 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](https://www.ietf.org/rfc/rfc2119.txt). + +### `wallet_switchEthereumChain` + +The method accepts a single object parameter with a `chainId` field. +The method returns `null` if the wallet switched its active chain, and an error otherwise. + +The method presupposes that the wallet has a concept of a single "active chain". +The active chain is defined as the chain that the wallet is forwarding RPC requests to. + +#### Parameters + +`wallet_switchEthereumChain` accepts a single object parameter, specified by the following TypeScript interface: + +```typescript +interface SwitchEthereumChainParameter { + chainId: string; +} +``` + +If a field does not meet the requirements of this specification, the wallet **MUST** reject the request. + +- `chainId` + - **MUST** specify the integer ID of the chain as a hexadecimal string, per the [`eth_chainId`](./eip-695.md) Ethereum RPC method. + - The chain ID **MUST** be known to the wallet. + - The wallet **MUST** be able to switch to the specified chain and service RPC requests to it. + +#### Returns + +The method **MUST** return `null` if the request was successful, and an error otherwise. + +If the wallet does not have a concept of an active chain, the wallet **MUST** reject the request. + +### Examples + +These examples use JSON-RPC, but the method could be implemented using other RPC protocols. + +To switch to Mainnet: + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_switchEthereumChain", + "params": [ + { + "chainId": "0x1", + } + ] +} +``` + +To switch to the Goerli test chain: + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_switchEthereumChain", + "params": [ + { + "chainId": "0x5", + } + ] +} +``` + +## Rationale + +The purpose `wallet_switchEthereumChain` is to provide dapps with a way of requesting to switch the wallet's active chain, which they would otherwise have to ask the user to do manually. + +The method accepts a single object parameter to allow for future extensibility at virtually no cost to implementers and consumers. + +For related work, see [EIP-3085: `wallet_addEthereumChain`](./eip-3085.md) and [EIP-2015: `wallet_updateEthereumChain`](./eip-2015.md). +`wallet_switchEthereumChain` intentionally forgoes the chain metadata parameters included in those EIPs, since it is purely concerned with switching the active chain, regardless of RPC endpoints or any other metadata associated therewith. + +## Security Considerations + +For wallets with a concept of an active chain, switching the active chain has significant implications for pending RPC requests and the user's experience. +If the active chain switches without the user's awareness, a dapp could induce the user to take actions for unintended chains. + +In light of this, the wallet should: + +- Display a confirmation whenever a `wallet_switchEthereumChain` is received, clearly identifying the requester and the chain that will be switched to. + - The confirmation used in [EIP-1102](./eip-1102.md) may serve as a point of reference. +- When switching the active chain, cancel all pending RPC requests and chain-specific user confirmations. + +### Preserving User Privacy + +Automatically rejecting requests for chains that aren't supported or have yet to be added by the wallet allows requesters to infer which chains are supported by the wallet. +Wallet implementers should consider whether this communication channel violates any security properties of the wallet, and if so, take appropriate steps to mitigate it. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).