Skip to content

Commit

Permalink
Update EIP-3085: Move to Review (ethereum#6457)
Browse files Browse the repository at this point in the history 
* Update EIP-3085: Add myself as an author and move back to Review

* Update to fit latest EIP-1

* Update formatting to be similar to that of 2255

* Update eip-3085.md
  • Loading branch information
@Pandapip1
Pandapip1 authored Sep 18, 2023
1 parent fe9e29a commit 9c499a5
Showing 1 changed file with 34 additions and 134 deletions.
168 changes: 34 additions & 134 deletions EIPS/eip-3085.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,33 @@
---
eip: 3085
title: Wallet Add Ethereum Chain RPC Method (`wallet_addEthereumChain`)
author: Erik Marks (@rekmarks), Pedro Gomes (@pedrouid)
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
status: Review
type: Standards Track
category: Interface
created: 2020-11-01
requires: 155, 695
requires: 155
---

## Simple Summary

An RPC method for adding Ethereum chains to wallet applications.

## Abstract

The `wallet_addEthereumChain` RPC method allows Ethereum applications ("dapps") to suggest chains to be added to the user's wallet application.
The caller must specify a chain ID and some chain metadata.
The wallet application may arbitrarily refuse or accept the request.
`null` is returned if the chain was added, and an error otherwise.

## Motivation

All dapps require the user to interact with one or more Ethereum chains in order to function.
Any given chain may or may not be supported by the user's wallet application.
`wallet_addEthereumChain` enables dapps to request chains to be added to the user's wallet.
This enables UX improvements for both dapps and wallets.
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](https://www.ietf.org/rfc/rfc2119.txt).

### `wallet_addEthereumChain`
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.

The method accepts a single object parameter, with a `chainId` and some chain metadata.
The method returns `null` if the chain was added to the wallet, and an error otherwise.
This proposal defines a new RPC method, `wallet_addEthereumChain`.

The wallet **MAY** reject the request for any reason.
### `wallet_addEthereumChain`

> Note that this method makes **no** statement about whether the wallet should change the user's currently selected chain, if the wallet has a concept thereof.
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.

#### Parameters
#### `wallet_addEthereumChain` Parameters

`wallet_addEthereumChain` accepts a single object parameter, specified by the following TypeScript interface:
The `wallet_addEthereumChain` method takes a single parameter, an `EthereumChainAddRequest` object, which is defined as follows:

```typescript
interface AddEthereumChainParameter {
Expand All @@ -60,115 +44,33 @@ interface AddEthereumChainParameter {
}
```

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.

- `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.
- `blockExplorerUrls`
- If provided, **MUST** specify one or more URLs pointing to block explorer web sites for the chain.
- `chainName`
- If provided, **MUST** specify a human-readable name for the chain.
- `iconUrls`
- If provided, **MUST** specify one or more URLs pointing to reasonably sized images 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.
- `decimals` **MUST** be a non-negative integer.
- `name` and `symbol` **SHOULD** be human-readable strings.
- `rpcUrls`
- If provided, **MUST** specify one or more URLs pointing to RPC endpoints that can be used to communicate with the chain.

All URL strings **MUST** include the protocol component of the URL.
HTTPS **SHOULD** always be used over HTTP.

#### Returns

The method **MUST** return `null` if the request was successful, and an error otherwise.

A request to add a chain that was already added **SHOULD** be considered successful.

The wallet **MUST NOT** allow the same `chainId` to be added multiple times.
See [Security Considerations](#security-considerations) for more information.

### Examples

These examples use JSON-RPC, but the method could be implemented using other RPC protocols.

To add the Goerli test chain:

```json
{
"id": 1,
"jsonrpc": "2.0",
"method": "wallet_addEthereumChain",
"params": [
{
"chainId": "0x5",
"chainName": "Goerli",
"rpcUrls": ["https://goerli.infura.io/v3/INSERT_API_KEY_HERE"],
"nativeCurrency": {
"name": "Goerli ETH",
"symbol": "gorETH",
"decimals": 18
},
"blockExplorerUrls": ["https://goerli.etherscan.io"]
}
]
}
```
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.

To add POA Network's xDAI chain:

```json
{
"id": 1,
"jsonrpc": "2.0",
"method": "wallet_addEthereumChain",
"params": [
{
"chainId": "0x64",
"chainName": "xDAI Chain",
"rpcUrls": ["https://dai.poa.network"],
"iconUrls": [
"https://xdaichain.com/fake/example/url/xdai.svg",
"https://xdaichain.com/fake/example/url/xdai.png"
],
"nativeCurrency": {
"name": "xDAI",
"symbol": "xDAI",
"decimals": 18
}
}
]
}
```
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.

In the above example, notice that the `iconUrls` array contains URLs pointing to two different image formats.
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.

A success response:
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.

```json
{
"id": 1,
"jsonrpc": "2.0",
"result": null
}
```
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.

A failure response:
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.

```json
{
"id": 1,
"jsonrpc": "2.0",
"error": {
"code": 4001,
"message": "The user rejected the request."
}
}
```
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

Expand All @@ -186,8 +88,6 @@ Therefore, all parameters except `chainId` are specified as optional, even thoug
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.

For related work, see [EIP-2015](./eip-2015.md).

## Security Considerations

`wallet_addEthereumChain` is a powerful method that exposes the end user to serious risks if implemented incorrectly.
Expand All @@ -204,7 +104,7 @@ The wallet should:
- 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](#parameters).
- Verify that the specified chain ID matches the return value of `eth_chainId` from the endpoint, as described above.

### RPC Endpoints and RPC URLs

Expand Down

0 comments on commit 9c499a5

Please sign in to comment.