Update docs for when breaking changes go live (MetaMask#207)

docs/guide/README.md

@@ -7,9 +7,9 @@ Welcome to MetaMask’s Developer Documentation. This documentation is for learn
 - For up to the minute news, follow our [Peepeth](https://peepeth.com/MetaMask/), [Twitter](https://twitter.com/metamask_io) or [Medium](https://medium.com/metamask) pages.
 - To learn how to contribute to the MetaMask project itself, visit our [Internal Docs](https://github.com/MetaMask/metamask-extension/tree/develop/docs).
 
-::: danger Breaking Changes Imminent
-We are in the process of shipping changes that will break certain Ethereum web applications.
-These changes may ship at any time, and all future major versions of MetaMask on all platforms will be affected.
+::: warning Breaking Provider Changes
+We are in the process of shipping changes that will break some Ethereum web applications.
+These changes have already shipped for the MetaMask browser extension, and may ship for MetaMask Mobile at any time.
 Please read our [Migration Guide](./provider-migration.html) for more details.
 
 Action is required for Ethereum application developers only.

docs/guide/ethereum-provider.md

@@ -4,10 +4,12 @@
 We recommend that all web3 site developers read the [Basic Usage](#basic-usage) section.
 :::
 
-::: danger Breaking Changes Imminent
-We are in the process of shipping changes that will break certain Ethereum web applications.
-These changes may ship at any time, and all future major versions of MetaMask on all platforms will be affected.
-Please see the [Upcoming Breaking Changes](#upcoming-breaking-changes) section for details.
+::: warning Breaking Provider Changes
+We are in the process of shipping changes that will break some Ethereum web applications.
+These changes have already shipped for the MetaMask browser extension, and may ship for MetaMask Mobile at any time.
+Please see the [Breaking Provider Changes](#upcoming-breaking-changes) section for details.
+
+If your website is broken and you're wondering how to fix it, please see the [Migration Guide](./provider-migration.html).
 
 Action is required for Ethereum application developers only.
 MetaMask users do not need to do anything.
@@ -21,7 +23,7 @@ We recommend using [`@metamask/detect-provider`](https://npmjs.com/package/@meta
 The Ethereum JavaScript provider API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193).
 
 ```javascript
-// this function detects most providers injected at window.ethereum
+// This function detects most providers injected at window.ethereum
 import detectEthereumProvider from '@metamask/detect-provider';
 
 const provider = await detectEthereumProvider();
@@ -39,21 +41,24 @@ if (provider) {
 
 [[toc]]
 
-## Upcoming Breaking Changes
+## Breaking Changes
+
+::: tip Tip
+If you are new to using the provider, you do not have to worry about these changes, and can skip ahead [to the next section](#api).
+:::
 
-::: danger Important Information
-We are in the process of shipping changes that will break certain Ethereum web applications.
-All future major versions of MetaMask on all platforms will be affected.
-To ensure that your site won't break, you need to handle these changes today.
-We will make an announcement on [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/8077) when the changes ship.
+::: warning Breaking Changes are Live
+On January 12, 2020, these changes went live for the Firefox extension.
+Chrome, Brave, and Edge will go live in the coming days.
+MetaMask Mobile will receive these changes as soon as possible.
 
-All consumers of MetaMask's provider may be affected by the `eth_chainId` bug (see [next subsection](#window-ethereum-api-changes)).
-Other than that, if you are new to using the provider, you do not have to worry about these changes, and can skip ahead [to the next section](#api).
+If your website is broken and you're wondering how to fix it, please see the [Migration Guide](./provider-migration.html).
+If you want to learn more about the changes, please read on.
 :::
 
 ### `window.ethereum` API Changes
 
-We will:
+The following changes to the `window.ethereum` API are breaking:
 
 - Ensure that chain IDs returned by `eth_chainId` are **not** 0-padded
   - For example, instead of `0x01`, we will always return `0x1`, wherever the chain ID is returned or accessible.
@@ -65,30 +70,21 @@ We will:
 - Remove the `ethereum.publicConfigStore` object
   - This object was, despite its name, never intended for public consumption.
     Its removal _may_ affect those who do not use it directly, e.g. if another library you use relies on the object.
-- Remove the [`ethereum.autoRefreshOnNetworkChange`](#ethereum-autorefreshonnetworkchange-to-be-removed) property
+- Remove the `ethereum.autoRefreshOnNetworkChange` property
   - Consumers will still be able to set this property on the provider, it just won't do anything.
 
-These changes _may_ break your website.
-Please read our [Migration Guide](./provider-migration.html) for more details.
-
 ### `window.web3` Removal
 
 ::: tip Tip
-If you do not use the `window.web3` object injected by MetaMask, you will not be affected by these changes.
-
-To understand why we're removing `window.web3`, please see [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/7163).
+If you do not use the `window.web3` object injected by MetaMask, you can ignore this section.
 :::
 
-In the near future, we will:
-
-- Stop injecting `window.web3` into web pages
-
-If you rely on the `window.web3` object currently injected by MetaMask, these changes _will_ break your website.
-Please read our [migration guide](./provider-migration.html) for more details.
+As part of the breaking changes, we will stop injecting `web3.js` as `window.web3` into web pages.
+MetaMask will continue to inject a shim object as `window.web3`, to issue warnings when websites attempt to access `window.web3`.
 
 ## Basic Usage
 
-For any non-trivial Ethereum web application — a.k.a. web3 site — to work, you will have to:
+For any non-trivial Ethereum web application — a.k.a. dapp, web3 site etc. — to work, you will have to:
 
 - Detect the Ethereum provider (`window.ethereum`)
 - Detect which Ethereum network the user is connected to
@@ -104,22 +100,12 @@ If you are in need of higher-level abstractions than those provided by this API,
 
 ## Chain IDs
 
-::: warning
-At the moment, the [`ethereum.chainId`](#ethereum-chainid) property and the [`chainChanged`](#chainchanged) event should be preferred over the `eth_chainId` RPC method.
-Their chain ID values are correctly formatted, per the table below.
-
-`eth_chainId` returns an incorrectly formatted (0-padded) chain ID for the chains in the table below, e.g. `0x01` instead of `0x1`.
-See the [Upcoming Breaking Changes section](#upcoming-breaking-changes) for details on when the `eth_chainId` RPC method will be fixed.
-
-Custom RPC endpoints are not affected; they always return the chain ID specified by the user.
-:::
-
 These are the IDs of the Ethereum chains that MetaMask supports by default.
 Consult [chainid.network](https://chainid.network) for more.
 
 | Hex  | Decimal | Network                         |
 | ---- | ------- | ------------------------------- |
-| 0x1  | 1       | Ethereum Main Network (MainNet) |
+| 0x1  | 1       | Ethereum Main Network (Mainnet) |
 | 0x3  | 3       | Ropsten Test Network            |
 | 0x4  | 4       | Rinkeby Test Network            |
 | 0x5  | 5       | Goerli Test Network             |
@@ -129,45 +115,12 @@ Consult [chainid.network](https://chainid.network) for more.
 
 ### ethereum.isMetaMask
 
-::: tip Tip
-This property is not guaranteed to be correct for all providers. Non-MetaMask providers may also set this property to `true`.
+::: warning Note
+This property is non-standard. Non-MetaMask providers may also set this property to `true`.
 :::
 
 `true` if the user has MetaMask installed.
 
-### ethereum.chainId
-
-::: warning
-The value of this property can change at any time, and should not be exclusively relied upon. See the [`chainChanged`](#chainchanged) event for details.
-
-**NOTE:** See the [Chain IDs section](#chain-ids) for important information about the MetaMask provider's chain IDs.
-:::
-
-A hexadecimal string representing the current chain ID.
-
-### ethereum.autoRefreshOnNetworkChange (TO BE REMOVED)
-
-::: danger DANGER
-The value of this property will only affect MetaMask's behavior if `window.web3` is accessed during the page lifecycle.
-When `window.web3` [is removed](#window-web3-removal), this property will be removed as well.
-
-As the consumer of this API, it is your responsbility to handle chain changes using the [`chainChanged` event](#chainChanged).
-We recommend reloading the page on `chainChange` unless you have good reason not to.
-:::
-
-By default, this property is `true`.
-
-If this property is truthy, MetaMask will reload the page in the following cases:
-
-- When the connected chain (network) changes, if `window.web3` has been accessed during the page lifecycle
-- When `window.web3` is accessed, if the connected chain (network) has changed during the page lifecycle
-
-To disable this behavior, set this property to `false` immediately after detecting the provider:
-
-```javascript
-ethereum.autoRefreshOnNetworkChange = false;
-```
-
 ## Methods
 
 ### ethereum.isConnected()
@@ -304,8 +257,8 @@ We plan to allow the `eth_accounts` array to be able to contain multiple address
 
 ### chainChanged
 
-::: warning
-**NOTE:** See the [Chain IDs section](#chain-ids) for important information about the MetaMask provider's chain IDs.
+::: tip Tip
+See the [Chain IDs section](#chain-ids) for MetaMask's default chains and their chain IDs.
 :::
 
 ```typescript
@@ -390,34 +343,6 @@ We expose some experimental, MetaMask-specific methods under the `ethereum._meta
 
 ## Experimental Methods
 
-### ethereum.\_metamask.isApproved() (TO BE REMOVED)
-
-::: danger DANGER
-This will be removed in the future.
-
-Please see the [Using the Provider section](#using-the-provider) for the recommended way of keeping track of user accounts.
-:::
-
-```typescript
-ethereum._metamask.isApproved(): Promise<boolean>;
-```
-
-This method returns a `Promise` that resolves to a `boolean` indicating if the caller has access to user accounts.
-
-### ethereum.\_metamask.isEnabled() (TO BE REMOVED)
-
-::: danger DANGER
-This will be removed in the future.
-
-Please see the [Using the Provider section](#using-the-provider) for the recommended way of keeping track of user accounts.
-:::
-
-```typescript
-ethereum._metamask.isEnabled(): boolean;
-```
-
-This method returns a `boolean` indicating if the caller has access to user accounts.
-
 ### ethereum.\_metamask.isUnlocked()
 
 ```typescript
@@ -440,6 +365,19 @@ Because of this, you may find web3 sites that use this API, or other providers t
 
 ## Legacy Properties
 
+### ethereum.chainId (DEPRECATED)
+
+::: warning
+This property is non-standard, and therefore deprecated.
+
+If you need to retrieve the current chain ID, use [`ethereum.request({ method: 'eth_chainId' })`](#ethereum-request-args).
+See also the [`chainChanged`](#chainchanged) event for more information about how to handle chain IDs.
+
+The value of this property can change at any time.
+:::
+
+A hexadecimal string representing the current chain ID.
+
 ### ethereum.networkVersion (DEPRECATED)
 
 ::: warning

docs/guide/mobile-best-practices.md

@@ -4,9 +4,9 @@ If this page doesn't answer your question, please feel free to open an issue [in
 
 ## The Provider (window.ethereum)
 
-::: danger Breaking Changes Imminent
-MetaMask Mobile is also affected by the breaking changes to our provider, and the removal of `window.web3`.
-These changes may ship at any time, and all future major versions of MetaMask on all platforms will be affected.
+::: danger Breaking Provider Changes
+We are in the process of shipping changes that will break some Ethereum web applications.
+These changes have already shipped for the MetaMask browser extension, and may ship for MetaMask Mobile at any time.
 Please read our [Migration Guide](./provider-migration.html) for more details.
 
 Action is required for Ethereum application developers only.

docs/guide/provider-migration.md

@@ -2,23 +2,16 @@
 
 ::: tip Attention MetaMask Users
 This documentation is for Ethereum application developers.
-As a MetaMask user, you don't need to do anything!
+As a MetaMask user, you don't need to do anything.
 :::
 
-::: danger Breaking Changes Imminent
-We are in the process of shipping all of these changes.
-These changes may ship at any time, and all future major versions of MetaMask on all platforms will be affected.
+As noted in the [Ethereum Provider documentation](./ethereum-provider.html#upcoming-breaking-changes), breaking changes went live for the Firefox extension on January 12, 2020.
+Chrome, Brave, and Edge will go live in the coming days.
+MetaMask Mobile will receive these changes as soon as possible.
 
-If your website relies on any of these features, it may break when these changes are made unless you migrate.
-:::
-
-As noted in the [Ethereum Provider documentation](./ethereum-provider.html#upcoming-breaking-changes), we are in the process of shipping breaking changes to our provider API and removing our injected `window.web3` object.
+The breaking changes include modifications to the `window.ethereum` API and the removal of `window.web3`.
 This guide describes how to migrate to the new provider API, and how to replace our `window.web3`.
 
-All replacement APIs are live, and we recommend migrating _immediately_.
-
-You can follow [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/8077) to be notified of the dates of the breaking changes once we announce them.
-
 ## Table of Contents
 
 [[toc]]
@@ -32,10 +25,12 @@ Please see [Handling the Removal of `ethereum.autoRefreshOnNetworkChange`](#hand
 :::
 
 For historical reasons, MetaMask has injected [`[email protected]`](https://github.com/ethereum/web3.js/tree/0.20.7) into all web pages.
-This version of `web3` is deprecated, [has known security issues](https://github.com/ethereum/web3.js/issues/3065), and is no longer maintained by the [web3.js](https://github.com/ethereum/web3.js/) team, so the only way we can continue providing a secure experience to our developers is by removing this library.
+This version of `web3` is deprecated, [has known security issues](https://github.com/ethereum/web3.js/issues/3065), and is no longer maintained by the [web3.js](https://github.com/ethereum/web3.js/) team.
+Therefore, we decided to remove this library.
 
-If your website relies on our `window.web3` object, your Ethereum-related functionality will break when we stop injecting `window.web3`.
-Continue reading to learn more about the migration options. Some are as simple as a one-line change.
+If your website relied on our `window.web3` object, you will have to migrate.
+Please continue reading to understand your options.
+Some are as simple as a one-line change.
 
 ::: tip Tip
 Regardless of how you choose to migrate, you may want to read the `[email protected]` documentation, which you can find [here](https://github.com/ethereum/web3.js/blob/0.20.7/DOCUMENTATION.md).
@@ -58,11 +53,11 @@ We recommend [`ethers`](https://npmjs.com/package/ethers) ([documentation](https
 
 ::: warning
 We strongly recommend that you consider one of the other two migration paths before resorting to this one.
-It is not future-proof, and it is not guaranteed to work.
+It is not future-proof, we will not add new features to it.
 :::
 
 Finally, if you just want your web3 site to continue to work, we created [`@metamask/legacy-web3`](https://npmjs.com/package/@metamask/legacy-web3).
-This package is a drop-in replacement for our `window.web3` that you can add to your web3 site even before MetaMask stops injecting `window.web3`.
+This package is a drop-in replacement for our `window.web3` that you can add to your website even before remove `window.web3` on all platforms.
 
 `@metamask/legacy-web3` should work exactly like our injected `window.web3`, including by refreshing the page on chain/network changes, but _we cannot guarantee that it works perfectly_.
 We will not fix any future incompatibilities between `[email protected]` and MetaMask itself, nor will we fix any bugs in `[email protected]` itself.
@@ -73,10 +68,11 @@ For installation and usage instructions, please see [npm](https://npmjs.com/pack
 
 ### Handling `eth_chainId` Return Values
 
-Due to a long-standing bug, MetaMask's implementation of the `eth_chainId` RPC method has returned 0-padded values for the [default Ethereum chains](./ethereum-provider.html#chain-ids) _except_ Kovan.
-For example, instead of `0x1` and `0x2`, we currently return `0x01` and `0x02`.
+The `eth_chainId` RPC method now returns correctly formatted values, e.g. `0x1` and `0x2`, instead of _incorrectly_ formatted values, e.g. `0x01` and `0x02`.
+MetaMask's implementation of `eth_chainId` used to return 0-padded values for the [default Ethereum chains](./ethereum-provider.html#chain-ids) _except_ Kovan.
+If you expect 0-padded chain ID values from `eth_chainId`, make sure to update your code to expect the correct format instead.
 
-For the time being, instead of calling the `eth_chainId` RPC method, you should use the [`ethereum.chainId` property](./ethereum-provider.html#ethereum-chainid) and the [`chainChanged` event](./ethereum-provider.html#chainchanged).
+For more details on chain IDs and how to handle them, see the [`chainChanged` event](./ethereum-provider.html#chainchanged).
 
 ### Handling the Removal of `chainIdChanged`
 
@@ -97,18 +93,16 @@ ethereum.on('chainChanged', (chainId) => {
 
 ### Handling the Removal of `isEnabled()` and `isApproved()`
 
-Before the new provider API shipped, we added
-[`_metamask.isEnabled`](./ethereum-provider.html#ethereum-metamask-isenabled-to-be-removed) and
-[`_metamask.isApproved`](./ethereum-provider.html#ethereum-metamask-isapproved-to-be-removed)
+Before the new provider API shipped, we added the `_metamask.isEnabled` and `_metamask.isApproved` methods
 to enable web3 sites to check if they have [access to the user's accounts](./rpc-api.html#eth-requestaccounts).
-`isEnabled` and `isApproved` are identical, except that `isApproved` is `async`.
-These methods were arguably never that useful, but they are completely redundant since the introduction of MetaMask's [permission system](./rpc-api.html#permissions).
+`isEnabled` and `isApproved` functioned identically, except that `isApproved` was `async`.
+These methods were arguably never that useful, and they became completely redundant with the introduction of MetaMask's [permission system](./rpc-api.html#permissions).
 
 We recommend that you check for account access in the following ways:
 
 1. You can call the [`wallet_getPermissions` RPC method](./rpc-api.html#wallet-getpermissions) and check for the `eth_accounts` permission.
 
-2. You can call the `eth_accounts` RPC method and the [`ethereum._metamask.isUnlocked()` function](./ethereum-provider.html#ethereum-metamask-isunlocked).
+2. You can call the `eth_accounts` RPC method and the [`ethereum._metamask.isUnlocked()` method](./ethereum-provider.html#ethereum-metamask-isunlocked).
 
    - MetaMask has to be unlocked before you can access the user's accounts.
      If the array returned by `eth_accounts` is empty, check if MetaMask is locked using `isUnlocked()`.

docs/guide/sending-transactions.md

@@ -14,7 +14,7 @@ const transactionParameters = {
   value: '0x00', // Only required to send ether to the recipient from the initiating external account.
   data:
     '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', // Optional, but used for defining smart contract creation and interaction.
-  chainId: 3, // Used to prevent transaction reuse across blockchains. Auto-filled by MetaMask.
+  chainId: '0x3', // Used to prevent transaction reuse across blockchains. Auto-filled by MetaMask.
 };
 
 // txHash is a hex string

docs/snippets/handleProvider.js

@@ -26,9 +26,8 @@ function startApp(provider) {
 /* Handle chain (network) and chainChanged (per EIP-1193) */
 /**********************************************************/
 
-// Normally, we would recommend the 'eth_chainId' RPC method, but it currently
-// returns incorrectly formatted chain ID values.
-let currentChainId = ethereum.chainId;
+const chainId = await ethereum.request({ method: 'eth_chainId' });
+handleChainChanged(chainId);
 
 ethereum.on('chainChanged', handleChainChanged);