EIP-5749 The window.evmproviders object (The 'window.evmproviders' object)
Final · Other · EIP status Final · created 2022-10-04
A standard in which, instead of browser wallets competing for the single window.ethereum slot, each wallet registers its own information in the window.evmproviders object, allowing multiple wallets to work together in one browser.
Why it is needed
Browser extension wallets connect to apps by 'injecting' themselves into the webpage. Since the Mist wallet in 2015, that slot has been a single window.ethereum, and it can only be occupied by one wallet at a time. When multiple wallets like MetaMask, Coinbase Wallet, Enkrypt, Trust Wallet, and Rainbow are installed together, a race condition arises where it is unpredictable which wallet gets connected, and connection behavior becomes inconsistent. As a result, users find it hard to try new wallets, and the market settles into a winner-take-all structure where existing wallets capture most of it. New wallets struggle to gain a foothold, and incumbent wallets face less pressure to innovate. There is also a workaround where each wallet injects into its own separate namespace, but this is impractical since it would require every app to know the name of every wallet in the world. This EIP solves the problem by creating a single registry shared among wallets.
What changes
Today
- Only one wallet can occupy the window.ethereum slot
- Installing multiple wallets makes it unpredictable which one will connect
- Users find it hard to try new wallets, cementing a winner-take-all market
After EIP-5749
- Each wallet registers itself in window.evmproviders under a unique key
- Apps can read the list of all installed wallets and display a selection screen
- The race condition between wallets disappears, and multiple wallets can be used together
Who is affected
- Users: Even with multiple wallets installed, connections no longer get tangled, and users can directly choose which wallet to use in an app.
- Wallet developers: New wallets, too, can be exposed alongside existing ones just by registering, without fighting over the window.ethereum slot.
- App and onboarding library developers: Wallet selection tools like web3modal and web3onboard can find and display all installed wallets in a standard way.
In depth
The ProviderInfo type
A type holding the information needed to render the wallet selection screen. All four fields are read-only. uuid is a UUIDv4 per wallet provider: it must stay the same across version changes and differ between channels (wallet products). For example, MetaMask 10.22.2 and 9.8.1 should share the same uuid, while MetaMask, Trust Wallet, and Enkrypt should each have a different uuid. name is the wallet's name (e.g. MetaMask, Enkrypt), icon is a base64-encoded SVG image starting with data:image/svg+xml;base64, (base64 as defined in RFC 4648), and description is the wallet's description.
ProviderWithInfo and EVMProviders
ProviderWithInfo is a type that extends EIP-1193's EIP1193Provider by adding an info: ProviderInfo field. In other words, it leaves the existing provider interface untouched and only adds display metadata on top. EVMProviders, the type of window.evmproviders, is a map holding ProviderWithInfo values keyed by strings. The key is RECOMMENDED to be the snake_case of the extension's name, and MUST contain only lowercase letters, digits, and underscores.
Injection and lookup implementation
On the injection side, window.evmproviders = window.evmproviders || {} creates the object if it doesn't exist, and window.evmproviders[name] = provider registers the wallet. A wallet that loads earlier does not overwrite or block one that loads later. On the lookup side, Object.values(window.evmproviders) gets an array of all installed providers. Thanks to this simple structure, libraries like web3modal and web3onboard can display every wallet the user has installed.
Why these name and icon formats were chosen
Standardizing the ProviderInfo type lets wallet-selection popups immediately know what information they need to populate. This is especially useful for web3 onboarding libraries like Web3Modal, Web3React, and Web3Onboard. The object is named evmproviders rather than ethereumproviders so it can cover other EVM-compatible chains as well. Icons are specified as SVG because the format is flexible, lightweight, and freely resizable.
Backward compatibility
This EIP itself does not require removing window.ethereum, so it does not directly break existing apps. Wallets can support both approaches at once. However, the recommended direction stated in the title and description, namely moving toward replacing window.ethereum in the long run, will break existing apps that depend on window.ethereum.
Security considerations
The security considerations of EIP-1193 apply as is. In addition, since SVG images can contain embedded JavaScript code, there is a cross-site scripting (XSS) risk. Apps and libraries must render wallet icon SVGs using an <img> tag so that scripts cannot execute. This EIP's specification is finalized in Final status.