Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

3085: Update params #3190

Merged
merged 1 commit into from
Jan 5, 2021
Merged

3085: Update params #3190

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions EIPS/eip-3085.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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"]
}
]
}
Expand All @@ -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",
Expand Down Expand Up @@ -193,23 +199,25 @@ 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:

- 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

Expand All @@ -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
Expand Down