-
Notifications
You must be signed in to change notification settings - Fork 5.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into sprice/creator-provenance
- Loading branch information
Showing
59 changed files
with
4,360 additions
and
1,783 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,108 +1,74 @@ | ||
| --- | ||
| eip: 2015 | ||
| title: Wallet Update Ethereum Chain RPC Method (`wallet_updateEthereumChain`) | ||
| author: Pedro Gomes (@pedrouid), Erik Marks (@rekmarks) | ||
| title: wallet_updateEthereumChain RPC Method | ||
| description: Adds an RPC method to switch betweeen EVM-compatible chains | ||
| author: Pedro Gomes (@pedrouid), Erik Marks (@rekmarks), Pandapip1 (@Pandapip1) | ||
| discussions-to: https://ethereum-magicians.org/t/eip-2015-wallet-update-chain-json-rpc-method-wallet-updatechain/3274 | ||
| status: Stagnant | ||
| status: Review | ||
| type: Standards Track | ||
| category: Interface | ||
| created: 2019-05-12 | ||
| requires: 155, 1474 | ||
| requires: 155 | ||
| --- | ||
|
|
||
| ## Simple Summary | ||
| Wallets can update the active chain when connected to a Dapp but not vice-versa, with `wallet_updateEthereumChain` the Dapp will be able to request this change from the Wallet. | ||
|
|
||
| ## Abstract | ||
| Dapp can request the Wallet to switch chains by providing the minimal parameters of `chainId`, `chainName`, `rpcUrl`, `nativeCurrency` and `blockExplorerUrl`. The Wallet will display a UI element to inform the user of this change. | ||
|
|
||
| ## Motivation | ||
| Wallet and Dapp communication rely on the present provider that acts as middleware between the two. Using JSON-RPC methods, the Dapp is able to access not only the active accounts but also the active chain. With [EIP-1102](./eip-1102.md) we introduced the ability for Dapps to request access to the active accounts and the Wallet is able to provide a simple UI to inform the user of this action however the same is not currently possible for switching chains. The current pattern is to display some UI to request the user to switch chains within the Dapp, however this could be easily improved by triggering a UI from the Wallet side that can be approved or rejected by the user instead. | ||
| 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 JSON RPC method will be part of `wallet_` namespaced methods which aim to improve the UX and interoperability between Dapps and Wallets. | ||
|
|
||
| ### Required Parameters | ||
| - chainId (string): the id of the chain compliant with EIP-155 | ||
| - chainName (string): the name of the chain to update | ||
| - rpcUrl (string): the url endpoint for RPC requests for this chain | ||
| - nativeCurrency (Object): includes three fields for `name` (string), `symbol` (string) and `decimals` (number) | ||
| - blockExplorerUrl (string): the url endpoint for a block explorer web site for the chain. | ||
|
|
||
| ### Best Practices | ||
| - The Wallet should display a UI view similar to a [EIP-1102](./eip-1102.md) informing the user that the currently connected Dapp wants to switch to the specified chain. | ||
| - the Wallet should default the rpcUrl to any existing endpoints matching a chainId known previously to the wallet, otherwise it will use the provided rpcUrl as a fallback. | ||
| - the Wallet should call the rpcUrl with `net_version` and `eth_chainId` to verify the provided chainId and networkId match the responses from the rpcUrl | ||
| - the Wallet should change all nativeCurrency symbols to the provided parameter | ||
|
|
||
| ### Example 1 | ||
| A JSON-RPC request from a Dapp to switch the Ethereum Goerli chain would be as follows: | ||
| ```json | ||
| { | ||
| "id":1, | ||
| "jsonrpc": "2.0", | ||
| "method": "wallet_updateChain", | ||
| "params": [ | ||
| { | ||
| "chainId": 0x5, | ||
| "chainName": "Goerli", | ||
| "rpcUrl": "https://goerli.infura.io/v3/406405f9c65348f99d0d5c27104b2213", | ||
| "nativeCurrency": { | ||
| "name": "Goerli ETH", | ||
| "symbol": "gorETH" | ||
| }, | ||
| "blockExplorerUrl": "https://goerli.etherscan.io" | ||
| } | ||
| ] | ||
|
|
||
| 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: | ||
|
|
||
| ```typescript | ||
| interface NativeCurrencyData { | ||
| name: string; | ||
| symbol: string; | ||
| decimals: number; | ||
| } | ||
| ``` | ||
|
|
||
| ### Example 2 | ||
| A JSON-RPC request from a Dapp to switch the POA Network's xDAI chain would be as follows: | ||
| ```json | ||
| { | ||
| "id":1, | ||
| "jsonrpc": "2.0", | ||
| "method": "wallet_updateChain", | ||
| "params": [ | ||
| { | ||
| "chainId": "0x5", | ||
| "chainName": "Goerli", | ||
| "rpcUrl": "https://goerli.infura.io/v3/406405f9c65348f99d0d5c27104b2213", | ||
| "nativeCurrency": { | ||
| "name": "Goerli ETH", | ||
| "symbol": "gorETH" | ||
| }, | ||
| "blockExplorerUrl": "https://goerli.etherscan.io" | ||
| } | ||
| ] | ||
| interface EthereumChainSwitchRequest { | ||
| chainId: string; | ||
| chainName?: string; | ||
| rpcUrls?: string[]; | ||
| nativeCurrency?: NativeCurrencyData; | ||
| blockExplorerUrl?: string; | ||
| } | ||
| ``` | ||
|
|
||
| ### Responses | ||
| The `chainId` is the `0x`-prefixed [EIP-155](./eip-155.md)-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](./eip-20.md). Finally, the `blockExplorerUrl` should link to a block explorer compatible with the given `chainId`. | ||
|
|
||
| A success response: | ||
| 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. | ||
|
|
||
| ```json | ||
| { | ||
| "id": 1, | ||
| "jsonrpc": "2.0", | ||
| "result": true | ||
| } | ||
| ``` | ||
| The `wallet_updateEthereumChain` method returns `true` if the chain was successfully added or switched to, and an error with code `4001` if the user rejected the request. | ||
|
|
||
| A failure response: | ||
| ## Rationale | ||
|
|
||
| ```json | ||
| { | ||
| "id": 1, | ||
| "jsonrpc": "2.0", | ||
| "error": { | ||
| "code": 4001, | ||
| "message": "The user rejected the request." | ||
| } | ||
| } | ||
| ``` | ||
| 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](../LICENSE.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.