EIP-6963 Multi Injected Provider Discovery standard (Multi Injected Provider Discovery)
Final · Other · EIP status Final · created 2023-05-01
Instead of having browser wallet extensions compete over a single window.ethereum slot, it lets each wallet announce itself via window events, so dapps can discover every installed wallet and let the user choose.
Why it is needed
Until now, browser extension wallets have had to inject their Ethereum provider, the connection object linking the dapp and the wallet, into the same single slot on the webpage, window.ethereum. When a user installs two or more wallets, they overwrite each other in this slot, and since the order in which extensions load is unpredictable, the last wallet to load usually wins. Users have no control over which wallet gets connected, and a different wallet can end up winning each time they visit. Some wallets responded by deliberately injecting late to overwrite others, which made competition between wallets unfair and destroyed interoperability. Users were effectively forced to install only one wallet at a time, which also raised the barrier to entry for new wallets. This proposal solves the problem by having wallets announce themselves through two-way event communication instead of fighting over a single shared slot.
What changes
Today
- Every wallet extension competes by overwriting the single window.ethereum slot
- Because of load order competition, the wallet that loads last usually wins the connection
- Even if a user installs multiple wallets, they cannot choose which one connects
After EIP-6963
- Each wallet announces itself via an eip6963:announceProvider event, including its name, icon, and identifier
- Dapps can discover every installed wallet and show a selection screen
- Discovery is guaranteed regardless of whether the wallet's or the dapp's code runs first
- window.ethereum remains in place for backward compatibility
Who is affected
- Users: Multiple wallet extensions can be installed together without conflict, and dapps can let users pick the wallet they want directly.
- Wallet developers: Discovery happens fairly, without load order competition, lowering the barrier to entry for new wallets. Announcement events and a re-announcement listener need to be implemented.
- Dapp and library developers: Connection libraries like Web3Modal and RainbowKit can build wallet selection screens using standardized information (name, icon, rdns). window.ethereum is recommended only as a fallback when discovery fails.
In depth
EIP6963ProviderInfo: four wallet metadata fields
Each wallet announces itself with an EIP6963ProviderInfo containing four fields: uuid, name, icon, and rdns. The uuid MUST comply with UUIDv4 (RFC-4122) and is used to distinguish between EIP-1193 provider sessions with the same properties during the page's lifetime. name is a human readable name to display to the dapp, and icon is a URI pointing to an image. If unknown additional properties are included, dapps SHOULD ignore them. At the time of actual announcement, info is delivered bundled with the EIP-1193 provider as an EIP6963ProviderDetail. The existing EIP-1193 provider interface was left untouched for backward compatibility.
rdns: a reverse domain name identifier stable across sessions
rdns is an identifier written as a domain name in reverse, such as com.example.MyBrowserWallet, used to identify a wallet consistently even as sessions change. It MUST be a valid RFC-1034 domain name, and the DNS portion SHOULD be an active domain actually controlled by the provider. Dapps MAY reject providers that do not follow these rules. However, since this value is self-asserted by the wallet and can be spoofed, dapps SHOULD NOT use rdns for feature detection, and should handle incorrect or forged values in a way that minimizes degraded functionality. Verification mechanisms are out of scope for this specification.
Icons: data URI required, SVG rendered only via img tags
The icon string MUST be a data URI as defined in RFC-2397. The image SHOULD be at least 96x96px and square, and a lossless or vector format that is easy to render, such as PNG, WebP, or SVG, is RECOMMENDED. Since SVG can execute JavaScript, applications and libraries MUST render SVG images only via img tags to prevent untrusted script execution. This measure prevents a malicious wallet from tampering with the page or other wallets' information through its icon.
Event orchestration: guaranteeing discovery regardless of execution order
Wallets MUST dispatch a CustomEvent named eip6963:announceProvider via window.dispatchEvent(), and the EIP6963ProviderDetail object in the detail property SHOULD be frozen with Object.freeze(). At the same time, wallets MUST register a listener for the eip6963:requestProvider event and re-dispatch the announce event whenever a request arrives. Dapps MUST register the announce listener before dispatching the request event, and MUST NOT remove the listener for the lifetime of the page. This mutual re-announcement structure guarantees discovery regardless of whether the wallet code or the dapp code executes first. Dapps MAY store the received ProviderDetails or restart the discovery process by dispatching a new request event.
Backwards compatibility: window.ethereum stays, but as a fallback
This EIP does not require replacing window.ethereum, so it does not directly break existing applications. Still, dapps are recommended to implement this EIP and keep window.ethereum usage only as a fallback for when discovery fails, and wallets SHOULD also maintain window.ethereum compatibility for dapps that have not implemented this EIP. To avoid namespace collisions, it is RECOMMENDED that wallets inject the provider object into a wallet-specific namespace and then proxy it to window.ethereum. In environments where multiple legacy wallets are installed, even a dapp that follows this specification cannot guarantee that the correct wallet gets selected.
Security: object freezing, impersonation detection, fingerprinting prevention
Because the wallet provider object is a highly trusted interface that handles transaction data, freezing the EIP1193Provider object with Object.freeze() before dispatch is best practice. However, because some pages need to monkey-patch the object for web compatibility reasons, the tradeoff between security and compatibility is left to wallet implementers. Dapps MUST actively detect attempts to impersonate or tamper with other wallets, for example by checking that the uuid values of two EIP6963ProviderInfo objects match. Also, since this design allows discovery to be initiated from the dapp side, wallets have the option to reduce fingerprinting caused by window.ethereum injection by deferring injection until a requestProvider is received and gating it behind a 'private connection' feature with a user consent UI.