ERC-1328 WalletConnect URI format
Final · Accounts & wallets · created 2018-08-15
Defines how to put the information needed to connect an app and a wallet into a single URI line starting with wc:. This URI can be shown as a QR code or a link.
Why it is needed
To use a wallet from a website or app, the two must first find each other and establish a connection. If there is no defined format for the connection information, for example which topic the conversation uses, which key encrypts messages, and which server relays them, each wallet has to read it in a different way, and it is hard to decode the meaning even after scanning a QR code. According to the original, the alpha version of the WalletConnect protocol put JSON inside the QR code, and the processing needed to read out its intent was very inefficient. This standard specifies that connection information be written as a single URI line starting with wc:, which makes it easier for wallets to build QR code parsers and lets links be passed to the wallet app through Android's Intent system.
In depth
Basic structure of the URI
A request URI starts with wc, followed by a colon and the topic. The grammar is request = "wc" ":" topic [ "@" version ][ "?" parameters ]. The topic is a string (STRING), and @ and a version number can follow it. The version is 1*DIGIT, that is, one or more digits. Finally, ? is appended and the parameters are written. The parameters are one or more key=value pairs joined by &, and both key and value are strings. The bracketed version part and parameters part are written as optional in the grammar.
Version 1.0 parameters (version=1)
A URI using the WalletConnect 1.0 protocol is marked with @1 and carries two parameters. key is the symmetric key used for encryption. bridge is the URL of the bridge server that relays messages. In the example in the original, the bridge value is https://bridge.walletconnect.org URL-encoded, and the key value is a hexadecimal string. Which parameters are required depends on the protocol version, so a wallet must read the version first and then look for the matching parameters.
Version 2.0 parameters (version=2)
A URI using the WalletConnect 2.0 protocol is marked with @2 and defines five parameters. symKey is the symmetric key that encrypts messages passing through the relay. methods is the list of JSON-RPC methods supported by the pairing topic. relay-protocol is the transport protocol that relays messages. relay-data is the transport data used for relaying and may be omitted. expiryTimestamp is the time at which the pairing expires, written as a Unix timestamp in seconds, and it may also be omitted. The names and composition differ from the 1.0 parameters (key, bridge).
Reading the examples in the original
The 1.0 example starts with wc:8a5e5bdc-a0e4-4702-ba63-8f1a5655744f@1. A UUID-style string appears in the topic position, and the two parameters bridge and key follow @1. The 2.0 example starts with wc:7f6e504bfad60b485450578e05678ed3e8e8c4751d3c6160be17160d63ec90f9@2, with a long hexadecimal string in the topic position. The parameters include relay-protocol=irn, symKey (a hexadecimal string), methods=[wc_sessionPropose],[wc_authRequest,wc_authBatchRequest], and expiryTimestamp=1705934757. The methods value is written as groups of method names wrapped in brackets and joined by commas.
Why a URI is used instead of JSON
The alpha version of the WalletConnect protocol put JSON inside the QR code. The original explains that this was very inefficient for reading out the intent of the QR code. So this proposal dropped JSON and moved to a URI format. A simpler format lets wallets build a better QR code parsing API. Also, putting a URI rather than JSON inside the QR code makes it possible to use Android's Intent system.
Version notation and compatibility
To let the WalletConnect protocol keep evolving, a version notation (@version) was added to the URI grammar. Even when a new version comes out, the version number in the URI tells which rules to read it by, so compatibility with older versions can be maintained. In fact, this document defines different parameter sets for version 1 and version 2. A wallet interprets the parameters according to the version number. The status of this standard is Final.
Things to watch out for
- Scope of URI sharing and sensitive information: The URI is meant to be shared between a user's devices or between apps. It must not contain sensitive information that could compromise communication or let someone control the user's private key.