DCIPs/EIPS/eip-2015.md

---
eip: 2015
title: Wallet Update Ethereum Chain RPC Method (`wallet_updateEthereumChain`)
author: Pedro Gomes (@pedrouid), Erik Marks (@rekmarks)
discussions-to: https://ethereum-magicians.org/t/eip-2015-wallet-update-chain-json-rpc-method-wallet-updatechain/3274
status: Stagnant
type: Standards Track
category: Interface
created: 2019-05-12
requires: 155, 1474
---

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

## 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"
    }
  ]
}
```

### 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"
    }
  ]
}
```

### Responses

A success response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": true
}
```

A failure response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "error": {
    "code": 4001,
    "message": "The user rejected the request."
  }
}
```

## Copyright
Copyright and related rights waived via [CC0](../LICENSE.md).