diff --git a/EIPS/eip-3085.md b/EIPS/eip-3085.md index 648195bb76e42a..9293acda4e0bff 100644 --- a/EIPS/eip-3085.md +++ b/EIPS/eip-3085.md @@ -52,35 +52,40 @@ The wallet **MUST** reject the request if the wallet does not support the chain ```typescript interface AddEthereumChainParameter { chainId: string; - blockExplorerUrl?: string; + blockExplorerUrls?: string[]; chainName?: string; + iconUrl?: string; nativeCurrency?: { name: string; symbol: string; decimals: number; }; - rpcUrl?: string; + rpcUrls?: string[]; } ``` -Only the `chainId` is required per this specification, but a wallet **MAY** require any other fields listed, and impose additional requirements on them. +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. - `chainId` - **MUST** specify the integer ID of the chain as a hexadecimal string, per the [`eth_chainId`](./eip-695.md) Ethereum RPC method. - The wallet **SHOULD** compare the specified `chainId` value with the `eth_chainId` return value from the endpoint. If these values are not identical, the wallet **MUST** reject the request. -- `blockExplorerUrl` - - If provided, **MUST** specify the URL of a block explorer web site for the chain. +- `blockExplorerUrls` + - If provided, **MUST** specify one or more URLs of a block explorer web site for the chain. - The block explorer API routes **SHOULD** be compatible with [EIP-3091](./eip-3091.md). - `chainName` - If provided, **MUST** specify a human-readable name for the chain. +- `iconUrl` + - If provided, **MUST** specify a URL pointing to a reasonably sized image that can be used to visually identify the chain. - `nativeCurrency` - If provided, **MUST** describe the native currency of the chain using the `name`, `symbol`, and `decimals` fields. -- `rpcUrl` - - If provided, **MUST** specify the URL of the RPC endpoint used to communicate with the chain. + - `decimals` **MUST** be a non-negative integer. + - `name` and `symbol` **SHOULD** be human-readable strings. +- `rpcUrls` + - If provided, **MUST** specify one or more URLs of the RPC endpoint used to communicate with the chain. All URL string fields **MUST** include the protocol component of the URL. -HTTPS **SHOULD** be used. +HTTPS **SHOULD** always be used over HTTP. #### Returns @@ -106,13 +111,13 @@ To add the Goerli test chain: { "chainId": "0x5", "chainName": "Goerli", - "rpcUrl": "https://goerli.infura.io/v3/INSERT_API_KEY_HERE", + "rpcUrls": ["https://goerli.infura.io/v3/INSERT_API_KEY_HERE"], "nativeCurrency": { "name": "Goerli ETH", "symbol": "gorETH", "decimals": 18 }, - "blockExplorerUrl": "https://goerli.etherscan.io" + "blockExplorerUrls": ["https://goerli.etherscan.io"] } ] } @@ -129,7 +134,8 @@ To add POA Network's xDAI chain: { "chainId": "0x64", "chainName": "xDAI Chain", - "rpcUrl": "https://dai.poa.network", + "rpcUrls": ["https://dai.poa.network"], + "iconUrl": "https://xdaichain.com/fake/example/url/xdai.svg", "nativeCurrency": { "name": "xDAI", "symbol": "xDAI", @@ -193,16 +199,17 @@ The wallet should: - Ensure that a submitted chain ID is valid. - It should be submitted as 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, for example with different RPC URLs. +- 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 in [this specification](#parameters). -### RPC Endpoints +### 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 `rpcUrl` parameter cannot be assumed to be honest or even correct. +The endpoints identified by the `rpcUrls` parameter cannot be assumed to be honest, correct, or ultimately pointing to the same chain. Moreover, even trusted endpoints endpoints can expose users to privacy risks depending on their data collection practices. Therefore, the wallet should: @@ -210,6 +217,7 @@ Therefore, the wallet should: - Inform users that their on-chain activity and IP address will be exposed to the endpoint. - If the 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. ### UX @@ -219,7 +227,8 @@ In service of these goals, the wallet should: - When receiving a `wallet_addEthereumChain` request, display a user confirmation informing the user that a specific dapp has requested that the chain be added. - The confirmation used in [EIP-1102](./eip-1102.md) may serve as a point of reference. -- Ensure that any chain metadata, such as `nativeCurrency` and `blockExplorerUrl`, are validated and used to maximum effect in the UI. +- Ensure that any chain metadata, such as `nativeCurrency` and `blockExplorerUrls`, are validated and used to maximum effect in the UI. +- If an image is provided via `iconUrl`, ensure that the user understands that the icon 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. ### Validating Chain Data