---
eip: 1102
title: Opt-in web3 access
author: Paul Bouchon <mail@bitpshr.net>
discussions-to: https://ethereum-magicians.org/t/opt-in-web3-access/414
status: Draft
type: Standards Track
category: Interface
created: 2018-05-04
---

## Simple summary

This proposal describes a new way for DOM environments to expose the web3 API that requires user approval.

## Abstract

MetaMask and most other tools that provide access to web3-enabled environments do so automatically and without user consent. This exposes users of such environments to fingerprinting attacks since untrusted websites can check for a `web3` object and reliably identify web3-enabled clients.

This proposal outlines a new protocol in which dapps request access to the web3 API instead of relying on its preexistence in a given DOM environment.

## Specification

### Typical dapp initialization

```
START dapp
IF web3 is defined
    CONTINUE dapp
IF web3 is undefined
    STOP dapp
```

### Proposed dapp initialization

```
START dapp
IF web3 is defined
    CONTINUE dapp
IF web3 is undefined
    REQUEST[1] web3 API
    IF user approves
        INJECT[2] web3 API
        NOTIFY[3] dapp
        CONTINUE dapp
    IF user rejects
    IF non-web3 environment
        NOOP[4]
```

#### `[1] REQUEST`

Dapps MUST request the web3 API by sending a message using [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) API. This message MUST be sent with a payload object containing a `type` property with a value of “WEB3_API_REQUEST” and an optional `id` property corresponding to an identifier of a specific wallet provider, such as "METAMASK".

#### `[2] INJECT`

Dapp browsers should inject the web3 API using an implementation-specific strategy that can expose the web3 API to the user’s browser context, such as HTML script tag injection.

#### `[3] NOTIFY`

Dapps browsers MUST notify dapps of successful web3 exposure by sending a message using [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) API. This message MUST be sent with a payload object containing a `type` property with a value of “WEB3_API_SUCCESS" and an optional `id` property corresponding to an identifier of a specific wallet provider, such as "METAMASK".

#### `[4] NOOP`

If a user rejects web3 access on an untrusted site, the site itself MUST NOT be notified in any way; notification of a rejection would allow third-party tools to still identify that a client is web3-enabled despite not being granted web3 access.

### Example implementation: `postMessage`

The following example demonstrates one possible implementation of this strategy in a browser-based DOM environment. Note that web3 environments on other platforms would most likely use platform-specific native messaging protocols, not `postMessage`.

```js
if (typeof web3 !== 'undefined') {
    // web3 API defined, start dapp
} else {
    window.addEventListener('message', function (event) {
        if (!event.data || !event.data.type) { return; }
        if (event.data.type === 'WEB3_API_SUCCESS') {
            // web3 API defined, start dapp
        }
    });
    // request web3 API
    window.postMessage({ type: 'WEB3_API_REQUEST' });
}
```

## Rationale

An [open issue](https://github.com/MetaMask/metamask-extension/issues/714) against the [MetaMask](https://github.com/MetaMask/metamask-extension) extension has received community upvotes and Richard Burton of the [Balance](https://github.com/balance-io) team published a well-received [blog post](https://medium.com/@ricburton/metamask-walletconnect-js-b47857efb4f7) discussing these potential changes.

### Constraints

* Web3 MUST NOT be exposed to websites by default.
* Dapps MUST request web3 if it does not exist.
* Users MUST be able to approve or reject web3 access.
* Web3 MUST be exposed to websites after user consent.
* Environments MAY continue auto-exposing web3 if users can disable this behavior.

### Immediate value-add

* Users can reject web3 access on untrusted sites to prevent web3 fingerprinting.

### Long-term value-add

* Dapps could request specific account information based on user consent.
* Dapps could request specific user information based on user consent (uPort, DIDs).
* Dapps could request a specific network based on user consent.
* Dapps could request multiple instances of the above based on user consent.

## Backwards compatibility

This proposal impacts dapp authors and requires that they request access to the web3 API before using it. This proposal also impacts developers of web3-enabled environments or dapp browsers as these tools should no longer auto-expose the web3 API; instead, they should only do so if a website requests the API and if the user consents to its access. Environments may continue to auto-expose the web3 API as long as users have the ability to disable this behavior.

## Implementation

The MetaMask team is currently working an [MVP implementation](https://github.com/MetaMask/metamask-extension/issues/3930) of the strategy described above and expects to begin limited user testing soon.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).