EIP-3085: wallet_addEthereumChain #3085

rekmarks · 2020-11-02T06:47:37Z

Rendered file: https://github.com/rekmarks/EIPs/blob/2016/EIPS/eip-3085.md

This PR adds EIP-3085, which introduces the wallet_addEthereumChain RPC method. It's basically EIP-2015, without requiring the network to be switched.

I think 2015 is a great idea, but wallets may desire an RPC method that only adds a chain, without requiring that the network is changed. For example, allowing dapps to request network changes is bound to cause UX issues, especially as we see dapps moving to different layer 2 chains.

2015 and 3085 can proceed independently of each other.

Co-author credits go to @pedrouid

danfinlay · 2020-11-02T18:26:57Z

It might be nice to include a "request to switch network" method as part of the same proposal? Seems like only with both can we eliminate the situation where dapps have to instruct users how to make network-related selections within their wallet.

rekmarks · 2020-11-02T18:40:43Z

@danfinlay, @MicahZoltu has convinced me that granularity is a virtue when it comes to EIPs, and I think the network switching should be in its own one. 2015 can then extend/bundle the two, as necessary. I noticed that the next free EIP number appears to be 2017 😉

EIPS/eip-2016.md

Co-authored-by: Dan Finlay <542863+danfinlay@users.noreply.github.com>

pedrouid · 2020-11-02T19:11:45Z

I've opened a PR to update EIP-2015 to have closer standardization with this EIP

Something that I'm reconsidering whether or not it's a reasonable parameter is blockExplorerUrl. The whole point of these EIPs or more specifically ERCs is to expand interoperability by reaching an agreement in interfaces.

Applications can permissionessly interface with each other given that standards are followed and become interoperable.

However this wouldn't be true for blockExporerUrl UNLESS we actually had blockchain explorers agree on an API.

What is the value of providing that url if you are not aware of the API for that website? How is the wallet going to simply link transactions, adresses, tokens, contracts, etc??

Examples

Blocks

Blockscout (chainId=100) -> https://blockscout.com/poa/xdai/blocks/<BLOCK_HASH_OR_HEIGHT>
Etherscan (chainId=1) -> https://etherscan.io/block/<BLOCK_HASH_OR_HEIGHT>
Etherchain (chainId=1) -> https://etherchain.org/block/<BLOCK_HASH_OR_HEIGHT>
Ethplorer (chainId=1) -> unsupported

Etherscan and Etherchain are in consensus for blocks endpoint but Blockscout uses /blocks endpoint instead and Ethplorer doesn't have a page for blocks so returns 404 not found.

Transactions

Blockscout (chainId=100) -> https://blockscout.com/poa/xdai/tx/<TX_HASH>
Etherscan (chainId=1) -> https://etherscan.io/tx/<TX_HASH>
Etherchain (chainId=1) -> https://etherchain.org/tx/<TX_HASH>
Ethplorer (chainId=1) -> https://ethplorer.io/tx/<TX_HASH>

All block explorers are in consensus for transactions endpoint.

Accounts

Blockscout (chainId=100) -> https://blockscout.com/poa/xdai/address/<ACCOUNT_ADDRESS>
Etherscan (chainId=1) -> https://etherscan.io/address/<ACCOUNT_ADDRESS>
Etherchain (chainId=1) -> https://etherchain.org/account/<ACCOUNT_ADDRESS>
Ethplorer (chainId=1) -> https://ethplorer.io/address/<ACCOUNT_ADDRESS>

All block explorers are in consensus for accounts endpoint except Etherchain which uses /account endpoint instead

ERC-20 Tokens

Blockscout (chainId=100) -> https://blockscout.com/poa/xdai/tokens/<TOKEN_ADDRESS>
Etherscan (chainId=1) -> https://etherscan.io/token/<TOKEN_ADDRESS>
Etherchain (chainId=1) -> https://etherchain.org/token/<TOKEN_ADDRESS>
Ethplorer (chainId=1) -> https://ethplorer.io/address/<TOKEN_ADDRESS>

Etherscan and Etherchain are in consensus but Blockscout uses /tokens endpoint instead and Ethplorer doesn't have a page for tokens so redirects to accounts page (/address).

CONCLUSION: Some block explorers do share the same API but there are still inconsistencies and in order to make the blockExplorerUrl suitable to be included as part of this EIP I would suggest writing an EIP for block explorer endpoints that would be required by this EIP.

EDIT: This standardization will also make future L2 solutions also have consistent endpoints

ERC-20 Tokens

Matic -> https://explorer.matic.network/tokens/<TOKEN_ADDRESS>
zkScan -> unsupported (/tokens displays a list of tokens pointing to L1 explorer)
Fuel -> unsupported

pedrouid · 2020-11-02T19:37:38Z

Anyway instead of talking... I've created a draft for this issue which I believe will be very valuable for Wallet development and additionally for this EIP

#3091

MicahZoltu

I left a bunch of comments, but nothing blocking getting this merged.

I am a little concerned about the cherry picked EIP number. We have had problems with users picking EIP numbers in the past as people do bad things in order to get vanity numbers so my preference is to disallow any number picking. That being said, I don't have a specific argument against this particular selection and in the past the editors have ruled on the side of being more permissive than I about EIP number selection.

If you want this to be merged by me right away, change the EIP number to 3085 (in the frontmatter and in the file name). If you really are set on 2016, you can wait until I get more feedback from other editors.

MicahZoltu · 2020-11-05T05:54:38Z

EIPS/eip-2016.md

+
+The method takes a `chainId` and some chain metadata, returning `true` if the chain was added to the wallet, and an error otherwise.
+
+The wallet **MAY** reject the request for any reason. The wallet **MUST** reject the request if the `chainId` is improperly formatted.


Consider adding:

The wallet MUST reject the request if the wallet does not have the capacity to connect to the requested chainId.

MicahZoltu · 2020-11-05T05:57:03Z

EIPS/eip-2016.md

+#### Parameters
+
+```typescript
+interface AddEthereumChainParams {


This is a bit confusing to read. The section is titled Parameters but then it only lists a single interface. I think what is meant is that the following function overload exists on the ethereum object: function request(method: 'wallet_addEthereumChain', options: AddEthereumChainParams): Promise<boolean> but that isn't immediately clear.

MicahZoltu · 2020-11-05T06:02:16Z

EIPS/eip-2016.md

+  - If provided, **MUST** specify the URL of the RPC endpoint used to communicate with the chain.
+
+All URL string fields **MUST** include the protocol component of the URL.
+If the protocol of the URL is HTTP, HTTPS **SHOULD** be used.


Suggested change

If the protocol of the URL is HTTP, HTTPS **SHOULD** be used.

HTTPS **SHOULD** be used.

I'm not sure if this is what you meant or not, but it definitely seems wrong to say that "if HTTP is explicitly supplied, ignore it and use HTTPS instead". If that is really what you mean, why not instead say that HTTPS **MUST** be used if available, even if the URL provided is HTTP or something?

MicahZoltu · 2020-11-05T06:22:02Z

EIPS/eip-2016.md

+    {
+      "chainId": "0x5",
+      "chainName": "Goerli",
+      "rpcUrl": "https://goerli.infura.io/v3/406405f9c65348f99d0d5c27104b2213",


This isn't a valid API key is it? If so, you should probably roll your keys. 😬

If it is, it's not mine 😅

I believe I copypasted it from @pedrouid's examples in EIP-2015.

MicahZoltu · 2020-11-05T06:22:33Z

EIPS/eip-2016.md

+      "nativeCurrency": {
+        "name": "Goerli ETH",
+        "symbol": "gorETH"
+      },


decimals isn't optional in the spec, but it is left out here so at the moment this is invalid.

MicahZoltu · 2020-11-05T06:34:46Z

EIPS/eip-2016.md

+For requests of this feature in the community, see e.g. [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/3604).
+


Suggested change

For requests of this feature in the community, see e.g. [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/3604).

This is just history, not of value to a reader 5-10 years in the future reading this specification (target audience). Also, would be more appropriate in Motivation not Rationale (though not really appropriate anywhere IMO).

MicahZoltu · 2020-11-05T06:39:08Z

EIPS/eip-2016.md

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


This should be in the Rationale, not Security Considerations.

I'll just remove it, since the definition of a valid chainId is already specified in the "Parameters" section.

MicahZoltu · 2020-11-05T06:40:23Z

EIPS/eip-2016.md

+- 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.
+  - This should be done before any other interactions with the endpoint.


It feels like this should be done before responding to wallet_addEthereumChain. Consider moving this up to the specification as a hard requirement.

MicahZoltu · 2020-11-05T06:43:20Z

EIPS/eip-2016.md

+At present, such community resources include:
+
+- [chainId.network](https://chainid.network)
+


Suggested change

At present, such community resources include:

- [chainId.network](https://chainid.network)

The chances that this website will stand the test of time are low, so it really shouldn't be included in the EIP. Content like this should be made available to users elsewhere on the internet, just not in the specification document. Keep in mind, the EIP is purely a specification, it is not a best practices, tutorial, help site, FAQ, etc. The EIP should be kept as simple as possible and focus only on the specification itself and not worry itself with assisting users in actually implementing anything (that is better suited for a blog or forum post).

MicahZoltu · 2020-11-05T06:45:08Z

EIPS/eip-2016.md

+## References
+
+- [chainId.network](https://chainid.network)
+- Related EIPs
+  - [EIP-155: Simple replay attack protection](./eip-155.md)
+  - [EIP-695: Create `eth_chainId` method for JSON-RPC](./eip-695.md)
+  - [EIP-1102: Opt-in Account Exposure](./eip-1102.md)
+  - [EIP-2015: Wallet Update Chain JSON-RPC Method (`wallet_updateChain`)](./eip-2015.md)
+


Suggested change

## References

- [chainId.network](https://chainid.network)

- Related EIPs

- [EIP-155: Simple replay attack protection](./eip-155.md)

- [EIP-695: Create `eth_chainId` method for JSON-RPC](./eip-695.md)

- [EIP-1102: Opt-in Account Exposure](./eip-1102.md)

- [EIP-2015: Wallet Update Chain JSON-RPC Method (`wallet_updateChain`)](./eip-2015.md)

This is not an official EIP section, and we tend to avoid non-standard sections whenever possible. I believe all of these are already linked inline, so this section doesn't provide any additional value to the EIP and the content probably should be removed.

pedrouid · 2020-11-06T13:45:39Z

Just got EIP-3091 merged... I will include it as requirement for EIP-2015... You should also include it for EIP-2016 @rekmarks

rekmarks · 2020-11-08T21:18:32Z

All feedback addressed, @MicahZoltu and @pedrouid.

If I didn't respond with a comment, I agree with the feedback and attempted to fix the problem directly in the EIP.

MicahZoltu · 2020-11-09T07:27:39Z

Hmm, something seems to be broken with GitHub status checks. Travis is green, yet GitHub says it is pending. Will check again later and kick it again if it doesn't self resolve.

BelfordZ · 2020-11-13T21:59:28Z

Any chance you could add an OpenRPC definition of the method? I need json schemas for this to add it. for example,

{
  "name": "wallet_addEthereumChain",
  "params": [
    {
      name: "chainId",
      schema: {  
        type: "string",
         ...
       },
      ....
    },
    returns: { ... }
  ]
}

MicahZoltu · 2020-11-14T10:18:57Z

@BelfordZ You should ask over in the discussions-to link: #3086

danfinlay · 2021-02-01T21:09:25Z

EIPS/eip-3085.md

+A wallet that implements `wallet_addEthereumChain` should expect to encounter requests for chains completely unknown to the wallet maintainers.
+That said, community resources exist that can be leveraged to verify requests for many Ethereum chains.
+The wallet should maintain a list of known chains, and verify requests add chains against that list.
+Indeed, unless there are good reasons not to, the wallet should _prefer its own chain metadata_ over anything submitted with a `wallet_addEthereumChain` request.


Possible amendment:

Suggested change

Indeed, unless there are good reasons not to, the wallet should _prefer its own chain metadata_ over anything submitted with a `wallet_addEthereumChain` request.

Indeed, unless there are good reasons not to, the wallet should _make clear to the user the existence of any previously configured chain metadata_ over anything submitted with a subsequent `wallet_addEthereumChain` request.

This

Avoids being overly zealous about wallet defaults, and leaves a friendly path to users adding new custom providers.

Extends the concern to include any pre-loaded chain metadata, not just wallet-developer provided metadata.

Rendered file: https://github.com/rekmarks/EIPs/blob/2016/EIPS/eip-3085.md This PR adds EIP-3085, which introduces the wallet_addEthereumChain RPC method. It's basically EIP-2015, without requiring the network to be switched. I think 2015 is a great idea, but wallets may desire an RPC method that only adds a chain, without requiring that the network is changed. For example, allowing dapps to request network changes is bound to cause UX issues, especially as we see dapps moving to different layer 2 chains.

rekmarks added 4 commits November 1, 2020 22:21

Add EIP-2016

28f82a8

Add Simple Summary

375eef0

Add discussions-to link stub

8b0864c

URLs must include the protocol

7f0bbd7

rekmarks mentioned this pull request Nov 2, 2020

EIP-3085 Discussion: wallet_addEthereumChain #3086

Closed

Add discussions link

634b89f

pedrouid mentioned this pull request Nov 2, 2020

Update eip-2015.md #3090

Merged

danfinlay reviewed Nov 2, 2020

View reviewed changes

EIPS/eip-2016.md Outdated Show resolved Hide resolved

Update EIPS/eip-2016.md

f90d868

Co-authored-by: Dan Finlay <542863+danfinlay@users.noreply.github.com>

MicahZoltu approved these changes Nov 5, 2020

View reviewed changes

rekmarks added 3 commits November 8, 2020 12:40

Update EIP number to 3085

4412c60

Add 3091 as prerequisite

cff8113

Address review feedback

68105e6

rekmarks requested a review from MicahZoltu November 8, 2020 21:18

rekmarks changed the title ~~EIP-2016: wallet_addEthereumChain~~ EIP-3085: wallet_addEthereumChain Nov 8, 2020

rekmarks added 4 commits November 8, 2020 13:31

fixup! Address review feedback

6a9dc30

Fix TypeScript interface name

2da3ae9

Update all return values to null

bd7da19

Edits for language, clarity

7bfdb7e

MicahZoltu approved these changes Nov 9, 2020

View reviewed changes

MicahZoltu closed this Nov 9, 2020

MicahZoltu reopened this Nov 9, 2020

MicahZoltu merged commit 81b5302 into ethereum:master Nov 9, 2020

rekmarks deleted the 2016 branch November 9, 2020 16:08

danfinlay reviewed Feb 1, 2021

View reviewed changes

axic mentioned this pull request Aug 6, 2021

Add EIP-3326: wallet_switchEthereumChain #3326

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

EIP-3085: wallet_addEthereumChain #3085

EIP-3085: wallet_addEthereumChain #3085

rekmarks commented Nov 2, 2020 •

edited

Loading

danfinlay commented Nov 2, 2020

rekmarks commented Nov 2, 2020

pedrouid commented Nov 2, 2020 •

edited

Loading

pedrouid commented Nov 2, 2020

MicahZoltu left a comment

MicahZoltu Nov 5, 2020

MicahZoltu Nov 5, 2020

MicahZoltu Nov 5, 2020

MicahZoltu Nov 5, 2020

rekmarks Nov 8, 2020

MicahZoltu Nov 5, 2020

MicahZoltu Nov 5, 2020

MicahZoltu Nov 5, 2020

rekmarks Nov 8, 2020

MicahZoltu Nov 5, 2020

MicahZoltu Nov 5, 2020

MicahZoltu Nov 5, 2020

pedrouid commented Nov 6, 2020

rekmarks commented Nov 8, 2020 •

edited

Loading

MicahZoltu commented Nov 9, 2020

BelfordZ commented Nov 13, 2020 •

edited

Loading

MicahZoltu commented Nov 14, 2020

danfinlay Feb 1, 2021


		The method takes a `chainId` and some chain metadata, returning `true` if the chain was added to the wallet, and an error otherwise.

		The wallet MAY reject the request for any reason. The wallet MUST reject the request if the `chainId` is improperly formatted.

	If the protocol of the URL is HTTP, HTTPS SHOULD be used.
	HTTPS SHOULD be used.

		For requests of this feature in the community, see e.g. [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/3604).

		At present, such community resources include:

		- [chainId.network](https://chainid.network)

	Indeed, unless there are good reasons not to, the wallet should _prefer its own chain metadata_ over anything submitted with a `wallet_addEthereumChain` request.
	Indeed, unless there are good reasons not to, the wallet should _make clear to the user the existence of any previously configured chain metadata_ over anything submitted with a subsequent `wallet_addEthereumChain` request.

EIP-3085: wallet_addEthereumChain #3085

EIP-3085: wallet_addEthereumChain #3085

Conversation

rekmarks commented Nov 2, 2020 • edited Loading

danfinlay commented Nov 2, 2020

rekmarks commented Nov 2, 2020

pedrouid commented Nov 2, 2020 • edited Loading

Examples

Blocks

Transactions

Accounts

ERC-20 Tokens

Blocks

Transactions

Accounts

ERC-20 Tokens

pedrouid commented Nov 2, 2020

MicahZoltu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pedrouid commented Nov 6, 2020

rekmarks commented Nov 8, 2020 • edited Loading

MicahZoltu commented Nov 9, 2020

BelfordZ commented Nov 13, 2020 • edited Loading

MicahZoltu commented Nov 14, 2020

Choose a reason for hiding this comment

rekmarks commented Nov 2, 2020 •

edited

Loading

pedrouid commented Nov 2, 2020 •

edited

Loading

rekmarks commented Nov 8, 2020 •

edited

Loading

BelfordZ commented Nov 13, 2020 •

edited

Loading