Breaking Changes to the MetaMask Provider are Here

Changes are now live with version 9.0.0 of the extension on Firefox, and are coming to Chrome in a matter of days. MetaMask Mobile will receive the changes in an upcoming release.

As of today, MetaMask has stopped injecting window.web3, and made a limited number of breaking changes to our Ethereum Provider API (window.ethereum). We’ve regularly messaged the community about these changes for more than a year, but if you’ve missed these announcements, don’t worry. This post contains everything you need to know about what’s changing, why we’re doing it, and what to do if your dapp is affected. If you just want to know how to handle the changes, you can head straight to our migration guide.

Why Did We Make This Decision?

The breaking changes we’re making to our provider API are simple enough: they’re either bug fixes or removed experimental features that are no longer useful. With these changes, we are completely compliant with the Ethereum JavaScript provider specification.

web3.js is a convenience library used to wrap our provider API, and the 0.20.7 version that we currently have been providing to sites has been unmaintained since 2018. As a result, this version contains bugs and usability issues that will never be fixed. Upgrading to a maintained version of web3.js was not a viable option, since all such versions are also breaking relative to version 0.20.7.

Since maintaining a project the size of web3.js is beyond our capabilities, we had to make the tough call to remove it. With the benefit of hindsight, injecting window.web3 was never the right choice. It’s a heavy file to inject into every web page, and even the Mist browser, a significant influence on early versions of MetaMask, planned to stop injecting window.web3 before it shut down.

Removing our window.web3 will increase the performance of MetaMask, encourage better development practices in the Ethereum web ecosystem, and will prevent problems down the road. For further context about this change, please see here and here.

What’s Changing?

Although you should probably go straight to our documentation, here’s a summary of the breaking changes:

First and foremost, we’re removing our injected window.web3.

Second, we’re making the following breaking changes to our Provider API (window.ethereum):

• Stop 0-padding eth_chainId return values for some chains
• Stop emitting chainIdChanged, and instead emit chainChanged
• Removing ethereum.publicConfigStore
• Removing the ethereum._metamask.isEnabled experimental method
• Removing the ethereum._metamask.isApproved experimental method

Next Steps

• If you do not use any of the features that are being removed as part of this update, you’re good to go!
• If you do use any of the above features, go to our migration guide.

The best way to stay up-to-date on all developer related MetaMask news is to subscribe to MetaMask Monthly. If you have questions or need a little help migrating to the new API, head to this GitHub issue or the MetaMask Discord to connect with the team and we’ll do our very best to help you out.

Thank you for reading, and for making the Ethereum ecosystem the incredible place that it is!