ERC-5094: URL Format for Ethereum Network Switching
A way of representing various network configurations as URLs.
|Authors||Luc van Kampen (@lucemans), Jakob Helgesson (@svemat01), Joshua Hendrix (@thejoshuahendrix)|
Table of Contents
This standard includes all needed information for adding a network to a wallet via URL, by including parameters such as
chain_name and others, such that the network configuration is provided through the URL itself.
As observed with the use of EIP-681 and its implementation in current mobile wallets, transactions can be made, approved, viewed, and used. However, if the wallet is instructed to perform a transaction on a chain they have not yet been configured before, the operation tends to fail.
This is understandable, as the
chain_id provided makes up only one part of what is required to connect to a network. This EIP aims to introduce a new type of URL for usage with deep-linking, QR, and more, to allow users to seamlessly add new networks to their (for ex. mobile) wallet to then be able to more easily partake in
tx-, or other Ethereum URL interactions.
As an extension to EIP-831 and neighboring EIP-681 and EIP-2400, this document aims to standardize the addition of new networks and switching thereof through the means of URLs. User convenience in this case is primary.
Introduction of this EIP is meant to bridge to a safer RPC listing system to be introduced in the near future.
Network Switching URLs contain “ethereum” in their schema (protocol) part and are constructed as follows:
network_add = erc831_part "add" "@" chain_id [ "/" ] "?" parameters erc831_part = "ethereum:network-" chain_id = 1*DIGIT parameters = parameter *( "&" parameter ) parameter = key "=" value key = required_keys / optional_keys required_keys = "rpc_url" / "chain_name" optional_keys = "name" / "symbol" / "decimals" / "explorer_url" / "icon_url" value = STRING / number number = 1*DIGIT
STRING is a URL-encoded Unicode string of arbitrary length, where delimiters and the
percentage symbol (
%) are mandatorily hex-encoded with a
If the key in the parameter is
decimals the value MUST be a
chain_id is mandatory and denotes the decimal chain ID, such that we have the identifier of the network we would like to add.
rpc_url is represented as an array of RPC URLs. A minimum of 1
rpc_url MUST be present, in the format of
rpc_url=https%3A%2F%2Fpolygon-rpc.com, or when multiple present
chain_name is required to specify the name of the network to be added.
symbol if provided, SHOULD be a human-readable string representing the native token.
decimals if provided, MUST be a non-negative integer representing the decimal precision of the native token.
explorer_url if provided, MUST specify one or more URLs pointing to block explorer web sites for the chain.
icon_url if provided, MUST specify one or more URLs pointing to reasonably sized images that can be used to visually identify the chain.
An example of adding a network with RPC endpoints
https://rpc-mainnet.matic.network, the name
Polygon Mainnet, token
18, explorer at
https://polygonscan.com/, and Chain ID
137 would look as follows:
In furtherance of the Ethereum URL saga, network configuration is a needed addition to the possibility of Ethereum URLs. This would improve functionality for URLs, and offer non-mainnet users a way to connect without needing to configure their wallet by hand.
The URL follows EIP-831 with the
network and the
PAYLOAD being a composite of
add and EIP-681-like
chain_id and parameters.
The choice for
network is to allow further expansion and allow variants following the pattern
An example URL for adding the Optimism Network
ethereum:[email protected]/?chain_name=Optimistic%20Ethereum &rpc_url=https%3A%2F%2Fmainnet.optimism.io&name=Ethereum&symbol=ETH&decimals=18&explorer_url=https%3A%2F%2Foptimistic.etherscan.io
The specification allows for a multitude of
explorer_url to be specified. This is done such to overlap with parsing of the
TYPE mentioned in EIP-681.
URLs can be malformed to deceive users. Users SHOULD confirm source of URL before using any links. As well as checking source and transaction details before confirming any transactions. Applications SHOULD display network config, prior to network addition, such that users can confirm the validity of the network configuration being added.
Copyright and related rights waived via CC0.
Please cite this document as:
Luc van Kampen (@lucemans), Jakob Helgesson (@svemat01), Joshua Hendrix (@thejoshuahendrix), "ERC-5094: URL Format for Ethereum Network Switching [DRAFT]," Ethereum Improvement Proposals, no. 5094, May 2022. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-5094.