metamask-extension/README.md

# MetaMask Browser Extension
[![Build Status](https://circleci.com/gh/MetaMask/metamask-extension.svg?style=shield&circle-token=a1ddcf3cd38e29267f254c9c59d556d513e3a1fd)](https://circleci.com/gh/MetaMask/metamask-extension) [![Coverage Status](https://coveralls.io/repos/github/MetaMask/metamask-extension/badge.svg?branch=master)](https://coveralls.io/github/MetaMask/metamask-extension?branch=master) [![Stories in Ready](https://badge.waffle.io/MetaMask/metamask-extension.png?label=in%20progress&title=waffle.io)](https://waffle.io/MetaMask/metamask-extension)

You can find the latest version of MetaMask on [our official website](https://metamask.io/).  For help using MetaMask, visit our [User Support Site](https://metamask.zendesk.com/hc/en-us).

For up to the minute news, follow our [Twitter](https://twitter.com/metamask_io) or [Medium](https://medium.com/metamask) pages.

To learn how to develop MetaMask-compatible applications, visit our [Developer Docs](https://metamask.github.io/metamask-docs/).

To learn how to contribute to the MetaMask project itself, visit our [Internal Docs](https://github.com/MetaMask/metamask-extension/tree/develop/docs).

## Building locally

- Install [Node.js](https://nodejs.org) version 8 and the latest available npm@6
    - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you.
    - If you install Node.js manually, ensure you're using npm@6
        - Install npm@6 using `npm install -g npm@6`
- Install dependencies: `npm install`
- Install gulp globally with `npm install -g gulp-cli`.
- Build the project to the `./dist/` folder with `gulp build`.
- Optionally, to rebuild on file changes, run `gulp dev`.
- To package .zip files for distribution, run `gulp zip`, or run the full build & zip with `gulp dist`.

 Uncompressed builds can be found in `/dist`, compressed builds can be found in `/builds` once they're built.

## Contributing

You can read [our internal docs here](https://metamask.github.io/metamask-extension/).

You can re-generate the docs locally by running `npm run doc`, and contributors can update the hosted docs by running `npm run publish-docs`.

### Running Tests

Requires `mocha` installed. Run `npm install -g mocha`.

Then just run `npm test`.

You can also test with a continuously watching process, via `npm run watch`.

You can run the linter by itself with `gulp lint`.

## Architecture

[![Architecture Diagram](./docs/architecture.png)][1]

## Development

```bash
npm install
npm start
```

## Build for Publishing

```bash
npm run dist
```

#### Writing Browser Tests

To write tests that will be run in the browser using QUnit, add your test files to `test/integration/lib`.

## Other Docs

- [How to add custom build to Chrome](./docs/add-to-chrome.md)
- [How to add custom build to Firefox](./docs/add-to-firefox.md)
- [How to develop a live-reloading UI](./docs/ui-dev-mode.md)
- [How to add a new translation to MetaMask](./docs/translating-guide.md)
- [Publishing Guide](./docs/publishing.md)
- [The MetaMask Team](./docs/team.md)
- [How to develop an in-browser mocked UI](./docs/ui-mock-mode.md)
- [How to live reload on local dependency changes](./docs/developing-on-deps.md)
- [How to add new networks to the Provider Menu](./docs/adding-new-networks.md)
- [How to manage notices that appear when the app starts up](./docs/notices.md)
- [How to port MetaMask to a new platform](./docs/porting_to_new_environment.md)
- [How to use the TREZOR emulator](./docs/trezor-emulator.md)
- [How to generate a visualization of this repository's development](./docs/development-visualization.md)

[1]: http://www.nomnoml.com/#view/%5B%3Cactor%3Euser%5D%0A%0A%5Bmetamask-ui%7C%0A%20%20%20%5Btools%7C%0A%20%20%20%20%20react%0A%20%20%20%20%20redux%0A%20%20%20%20%20thunk%0A%20%20%20%20%20ethUtils%0A%20%20%20%20%20jazzicon%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20account-detail%0A%20%20%20%20%20accounts%0A%20%20%20%20%20locked-screen%0A%20%20%20%20%20restore-vault%0A%20%20%20%20%20identicon%0A%20%20%20%20%20config%0A%20%20%20%20%20info%0A%20%20%20%5D%0A%20%20%20%5Breducers%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20metamask%0A%20%20%20%20%20identities%0A%20%20%20%5D%0A%20%20%20%5Bactions%7C%0A%20%20%20%20%20%5BaccountManager%5D%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%5D%3A-%3E%5Bactions%5D%0A%20%20%20%5Bactions%5D%3A-%3E%5Breducers%5D%0A%20%20%20%5Breducers%5D%3A-%3E%5Bcomponents%5D%0A%5D%0A%0A%5Bweb%20dapp%7C%0A%20%20%5Bui%20code%5D%0A%20%20%5Bweb3%5D%0A%20%20%5Bmetamask-inpage%5D%0A%20%20%0A%20%20%5B%3Cactor%3Eui%20developer%5D%0A%20%20%5Bui%20developer%5D-%3E%5Bui%20code%5D%0A%20%20%5Bui%20code%5D%3C-%3E%5Bweb3%5D%0A%20%20%5Bweb3%5D%3C-%3E%5Bmetamask-inpage%5D%0A%5D%0A%0A%5Bmetamask-background%7C%0A%20%20%5Bprovider-engine%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bid%20store%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%3E%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%3C-%3E%5Bid%20store%5D%0A%20%20%5Bconfig%20manager%7C%0A%20%20%20%20%5Brpc%20configuration%5D%0A%20%20%20%20%5Bencrypted%20keys%5D%0A%20%20%20%20%5Bwallet%20nicknames%5D%0A%20%20%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%5Bconfig%20manager%5D%0A%20%20%5Bid%20store%5D%3C-%3E%5Bconfig%20manager%5D%0A%5D%0A%0A%5Buser%5D%3C-%3E%5Bmetamask-ui%5D%0A%0A%5Buser%5D%3C%3A--%3A%3E%5Bweb%20dapp%5D%0A%0A%5Bmetamask-contentscript%7C%0A%20%20%5Bplugin%20restart%20detector%5D%0A%20%20%5Brpc%20passthrough%5D%0A%5D%0A%0A%5Brpc%20%7C%0A%20%20%5Bethereum%20blockchain%20%7C%0A%20%20%20%20%5Bcontracts%5D%0A%20%20%20%20%5Baccounts%5D%0A%20%20%5D%0A%5D%0A%0A%5Bweb%20dapp%5D%3C%3A--%3A%3E%5Bmetamask-contentscript%5D%0A%5Bmetamask-contentscript%5D%3C-%3E%5Bmetamask-background%5D%0A%5Bmetamask-background%5D%3C-%3E%5Bmetamask-ui%5D%0A%5Bmetamask-background%5D%3C-%3E%5Brpc%5D%0A
-												readme - fix "plugin" to "extension"
											
										
										
											2017-12-16 00:06:06 +01:00
+								# MetaMask Browser Extension
-												Remove greenkeeper badge from README

											
										
										
											2018-10-16 00:14:24 +02:00
+								[![Build Status](https://circleci.com/gh/MetaMask/metamask-extension.svg?style=shield&circle-token=a1ddcf3cd38e29267f254c9c59d556d513e3a1fd)](https://circleci.com/gh/MetaMask/metamask-extension) [![Coverage Status](https://coveralls.io/repos/github/MetaMask/metamask-extension/badge.svg?branch=master)](https://coveralls.io/github/MetaMask/metamask-extension?branch=master) [![Stories in Ready](https://badge.waffle.io/MetaMask/metamask-extension.png?label=in%20progress&title=waffle.io)](https://waffle.io/MetaMask/metamask-extension)
-												readme - fix greenkeeper badge position
											
										
										
											2017-08-04 01:40:56 +02:00
-												Make docs links consistent (#5920)

* Make docs links consistent

So our various docs pages inter-link consistently per https://github.com/MetaMask/metamask-docs/issues/1

* Add docs links to internal docs page

											
										
										
											2018-12-13 01:18:18 +01:00
+								You can find the latest version of MetaMask on [our official website](https://metamask.io/).  For help using MetaMask, visit our [User Support Site](https://metamask.zendesk.com/hc/en-us).
-												Merge branch 'master' of github.com:MetaMask/metamask-extension into greenkeeper/initial

											
										
										
											2017-08-04 00:05:32 +02:00
-												Make docs links consistent (#5920)

* Make docs links consistent

So our various docs pages inter-link consistently per https://github.com/MetaMask/metamask-docs/issues/1

* Add docs links to internal docs page

											
										
										
											2018-12-13 01:18:18 +01:00
+								For up to the minute news, follow our [Twitter](https://twitter.com/metamask_io) or [Medium](https://medium.com/metamask) pages.
-												docs(readme): add Greenkeeper badge
											
										
										
											2017-07-19 00:41:33 +02:00
-												Make docs links consistent (#5920)

* Make docs links consistent

So our various docs pages inter-link consistently per https://github.com/MetaMask/metamask-docs/issues/1

* Add docs links to internal docs page

											
										
										
											2018-12-13 01:18:18 +01:00
+								To learn how to develop MetaMask-compatible applications, visit our [Developer Docs](https://metamask.github.io/metamask-docs/).
-												Add mission statement v1

											
										
										
											2018-05-29 18:27:02 +02:00
-												Make docs links consistent (#5920)

* Make docs links consistent

So our various docs pages inter-link consistently per https://github.com/MetaMask/metamask-docs/issues/1

* Add docs links to internal docs page

											
										
										
											2018-12-13 01:18:18 +01:00
+								To learn how to contribute to the MetaMask project itself, visit our [Internal Docs](https://github.com/MetaMask/metamask-extension/tree/develop/docs).
-												Add developer faq to top of readme

											
										
										
											2016-09-10 05:01:27 +02:00
-												Add simple build instructions (#454)


											
										
										
											2016-07-16 03:04:52 +02:00
+								## Building locally
-												Update local build instructions

											
										
										
											2018-11-21 20:22:35 +01:00
+								- Install [Node.js](https://nodejs.org) version 8 and the latest available npm@6
 								    - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you.
 								    - If you install Node.js manually, ensure you're using npm@6
 								        - Install npm@6 using `npm install -g npm@6`
 								- Install dependencies: `npm install`
 								- Install gulp globally with `npm install -g gulp-cli`.
 								- Build the project to the `./dist/` folder with `gulp build`.
 								- Optionally, to rebuild on file changes, run `gulp dev`.
 								- To package .zip files for distribution, run `gulp zip`, or run the full build & zip with `gulp dist`.
-												Add simple build instructions (#454)


											
										
										
											2016-07-16 03:04:52 +02:00
-												Store versioned builds in builds folder

											
										
										
											2016-07-27 00:35:08 +02:00
+								 Uncompressed builds can be found in `/dist`, compressed builds can be found in `/builds` once they're built.
-												Add jsdoc gh-pages script

											
										
										
											2018-09-12 23:10:06 +02:00
+								## Contributing
 								You can read [our internal docs here](https://metamask.github.io/metamask-extension/).
 								You can re-generate the docs locally by running `npm run doc`, and contributors can update the hosted docs by running `npm run publish-docs`.
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								### Running Tests
-												Added instructions for installing local build

											
										
										
											2016-11-22 03:16:45 +01:00
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								Requires `mocha` installed. Run `npm install -g mocha`.
-												Added instructions for installing local build

											
										
										
											2016-11-22 03:16:45 +01:00
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								Then just run `npm test`.
 								You can also test with a continuously watching process, via `npm run watch`.
 								You can run the linter by itself with `gulp lint`.
-												Added instructions for installing local build

											
										
										
											2016-11-22 03:16:45 +01:00
-												Add architecture diagram to readme

											
										
										
											2016-06-14 01:53:21 +02:00
+								## Architecture
 								[![Architecture Diagram](./docs/architecture.png)][1]
-												Add simple dev readme

											
										
										
											2015-12-21 01:25:45 +01:00
+								## Development
 								```bash
 								npm install
-												meta - README - add npm start to instructions

thanks @karlfloersch
											
										
										
											2016-11-21 18:34:31 +01:00
+								npm start
 								```
 								## Build for Publishing
 								```bash
 								npm run dist
-												Add simple dev readme

											
										
										
											2015-12-21 01:25:45 +01:00
+								```
-												Add ui mocking mode explanation

											
										
										
											2016-07-01 03:44:37 +02:00
-												Began adding browser-native encryptor module

Added new Qunit build process that will browserify the contents of `test/integration/lib` into the QUnit browser, allowing much more modular testing, including unit testing of our modules in our target browsers.

Made a basic unit test file of this form for the new encryptor module, which fails miserably because I've only just begun to work with it.

I've started with this blog post as a starting point, and will be adjusting it to our needs from there:
http://qnimate.com/passphrase-based-encryption-using-web-cryptography-api/

											
										
										
											2016-10-13 05:03:14 +02:00
+								#### Writing Browser Tests
 								To write tests that will be run in the browser using QUnit, add your test files to `test/integration/lib`.
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								## Other Docs
-												Added changelog and deploy docs

											
										
										
											2016-03-22 18:43:56 +01:00
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								- [How to add custom build to Chrome](./docs/add-to-chrome.md)
 								- [How to add custom build to Firefox](./docs/add-to-firefox.md)
 								- [How to develop a live-reloading UI](./docs/ui-dev-mode.md)
-												Document process of adding a new translation

											
										
										
											2018-03-09 20:18:43 +01:00
+								- [How to add a new translation to MetaMask](./docs/translating-guide.md)
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								- [Publishing Guide](./docs/publishing.md)
-												Add team member documentation

To help exeternal contributors make sense of who is active on the
project, and who they should go to to ask certain questions.

											
										
										
											2018-04-12 22:40:54 +02:00
+								- [The MetaMask Team](./docs/team.md)
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								- [How to develop an in-browser mocked UI](./docs/ui-mock-mode.md)
 								- [How to live reload on local dependency changes](./docs/developing-on-deps.md)
 								- [How to add new networks to the Provider Menu](./docs/adding-new-networks.md)
 								- [How to manage notices that appear when the app starts up](./docs/notices.md)
-												Add guide to porting to new platforms

Adds a new guide to porting MetaMask to new platforms. Intended for all those devs asking us how to make a mobile MetaMask.

											
										
										
											2017-09-14 22:31:10 +02:00
+								- [How to port MetaMask to a new platform](./docs/porting_to_new_environment.md)
-												Fix link to TREZOR emulator docs in README
											
										
										
											2018-07-20 00:47:22 +02:00
+								- [How to use the TREZOR emulator](./docs/trezor-emulator.md)
-												Break docs up into individual files

											
										
										
											2017-06-05 22:55:48 +02:00
+								- [How to generate a visualization of this repository's development](./docs/development-visualization.md)
-												Add architecture diagram to readme

											
										
										
											2016-06-14 01:53:21 +02:00
 								[1]: http://www.nomnoml.com/#view/%5B%3Cactor%3Euser%5D%0A%0A%5Bmetamask-ui%7C%0A%20%20%20%5Btools%7C%0A%20%20%20%20%20react%0A%20%20%20%20%20redux%0A%20%20%20%20%20thunk%0A%20%20%20%20%20ethUtils%0A%20%20%20%20%20jazzicon%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20account-detail%0A%20%20%20%20%20accounts%0A%20%20%20%20%20locked-screen%0A%20%20%20%20%20restore-vault%0A%20%20%20%20%20identicon%0A%20%20%20%20%20config%0A%20%20%20%20%20info%0A%20%20%20%5D%0A%20%20%20%5Breducers%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20metamask%0A%20%20%20%20%20identities%0A%20%20%20%5D%0A%20%20%20%5Bactions%7C%0A%20%20%20%20%20%5BaccountManager%5D%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%5D%3A-%3E%5Bactions%5D%0A%20%20%20%5Bactions%5D%3A-%3E%5Breducers%5D%0A%20%20%20%5Breducers%5D%3A-%3E%5Bcomponents%5D%0A%5D%0A%0A%5Bweb%20dapp%7C%0A%20%20%5Bui%20code%5D%0A%20%20%5Bweb3%5D%0A%20%20%5Bmetamask-inpage%5D%0A%20%20%0A%20%20%5B%3Cactor%3Eui%20developer%5D%0A%20%20%5Bui%20developer%5D-%3E%5Bui%20code%5D%0A%20%20%5Bui%20code%5D%3C-%3E%5Bweb3%5D%0A%20%20%5Bweb3%5D%3C-%3E%5Bmetamask-inpage%5D%0A%5D%0A%0A%5Bmetamask-background%7C%0A%20%20%5Bprovider-engine%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bid%20store%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%3E%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%3C-%3E%5Bid%20store%5D%0A%20%20%5Bconfig%20manager%7C%0A%20%20%20%20%5Brpc%20configuration%5D%0A%20%20%20%20%5Bencrypted%20keys%5D%0A%20%20%20%20%5Bwallet%20nicknames%5D%0A%20%20%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%5Bconfig%20manager%5D%0A%20%20%5Bid%20store%5D%3C-%3E%5Bconfig%20manager%5D%0A%5D%0A%0A%5Buser%5D%3C-%3E%5Bmetamask-ui%5D%0A%0A%5Buser%5D%3C%3A--%3A%3E%5Bweb%20dapp%5D%0A%0A%5Bmetamask-contentscript%7C%0A%20%20%5Bplugin%20restart%20detector%5D%0A%20%20%5Brpc%20passthrough%5D%0A%5D%0A%0A%5Brpc%20%7C%0A%20%20%5Bethereum%20blockchain%20%7C%0A%20%20%20%20%5Bcontracts%5D%0A%20%20%20%20%5Baccounts%5D%0A%20%20%5D%0A%5D%0A%0A%5Bweb%20dapp%5D%3C%3A--%3A%3E%5Bmetamask-contentscript%5D%0A%5Bmetamask-contentscript%5D%3C-%3E%5Bmetamask-background%5D%0A%5Bmetamask-background%5D%3C-%3E%5Bmetamask-ui%5D%0A%5Bmetamask-background%5D%3C-%3E%5Brpc%5D%0A