Breaking Changes to the MetaMask Inpage Provider

This article is outdated. Please see the new article and this GitHub issue for details.

In early 2020, the MetaMask inpage provider—a.k.a. window.ethereum — will:

• Always return Promises from ethereum.send(...)
• Stop reloading the page on network change
• Stop injecting the web3.js API
• Stop emitting chainIdChanged, and emit chainChanged instead
• Stop supporting some methods under ethereum._metamask (detailed below)

This post will be updated once the new API is available. The new API is detailed further down in this post.

If you are a MetaMask user, all you should notice because of this is better dapp UX over time. If you are a dapp developer, some of these changes may be breaking, and we encourage you to continue reading.

To learn why we’re removing these features and what you may have to do in response, you can follow the links in the bulleted list above.

Why are we doing this?

At MetaMask, we only break APIs as a last resort. Since we first launched our inpage provider API, we have generally only added features. Some of those features were added before standards and conventions were fully established. Unfortunately, some of them are incompatible with standards we are adopting, and maintaining them has become too costly for us. They have to go.

If you are a dapp developer, you may have gotten into the habit of treating e.g. the user’s selected account or network as immutable after initializing your dapp. MetaMask helped sustain this illusion — by, for instance, reloading the page on network change — for a variety of reasons related to the conventions of Ethereum and JavaScript. Today, writing asynchronous, event-driven JS has never been easier, which new provider standards like EIP 1102 and EIP 1193 take full advantage of. By implementing these standards, we hope to provide better experiences for both developers and users in the dapp ecosystem.

What does this mean?

We are removing the following experimental methods:

• ethereum._metamask.isEnabled
• ethereum._metamask.isApproved

If you want to use a library like web3.js in your dapp, you have to bring your own. To connect to MetaMask and get the user’s account and selected address, you should follow this pattern:

This is how you should handle connecting to MetaMask and any modern Ethereum provider.

That’s it. We strongly encourage using events and ethereum.send. We strongly discourage the use of legacy features like ethereum.sendAsync and ethereum.selectedAddress. You should only request to connect to MetaMask in response to user interaction — you should never request to connect spontaneously, such as on page load.

Conclusion

In early 2020, we are making our inpage provider fully compatible with EIPs 1102 and 1193. To do so, we have to deprecate a number of legacy features. In the end, we believe that dapp developers and users will benefit from this change. Otherwise, we would not do it.

Beyond standardizing our provider API, these changes set us up for some of the most exciting changes we’ve ever made to the MetaMask platform. Check out our plugin system and its prerequisite, our capabilities-inspired permissions system.