metamask-extension/README.md

# MetaMask Plugin [![Build Status](https://circleci.com/gh/MetaMask/metamask-plugin.svg?style=shield&circle-token=a1ddcf3cd38e29267f254c9c59d556d513e3a1fd)](https://circleci.com/gh/MetaMask/metamask-plugin)

## Building locally

 - Install [Node.js](https://nodejs.org/en/) version 6.3.1 or later.
 - Install local dependencies with `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.

## Architecture

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

## Development

```bash
npm install
```

#### In Chrome

Open `Settings` > `Extensions`.

Check "Developer mode".

At the top, click `Load Unpacked Extension`.

Navigate to your `metamask-plugin/dist/chrome` folder.

Click `Select`.

You now have the plugin, and can click 'inspect views: background plugin' to view its dev console.

#### In Firefox

Go to the url `about:debugging`.

Click the button `Load Temporary Add-On`.

Select the file `dist/firefox/manifest.json`.

You can optionally enable debugging, and click `Debug`, for a console window that logs all of Metamask's processes to a single console.

If you have problems debugging, try connecting to the IRC channel `#webextensions` on `irc.mozilla.org`.

For longer questions, use the StackOverfow tag `firefox-addons`.

### Developing on UI Only

You can run `npm run ui`, and your browser should open a live-reloading demo version of the plugin UI.

Some actions will crash the app, so this is only for tuning aesthetics, but it allows live-reloading styles, which is a much faster feedback loop than reloading the full extension.

### Developing on UI with Mocked Background Process

You can run `npm run mock` and your browser should open a live-reloading demo version of the plugin UI, just like the `npm run ui`, except that it tries to actually perform all normal operations.

It does not yet connect to a real blockchain (this could be a good test feature later, connecting to a test blockchain), so only local operations work.

You can reset the mock ui at any time with the `Reset` button at the top of the screen.

### Developing on Dependencies

To enjoy the live-reloading that `gulp dev` offers while working on the `web3-provider-engine` or other dependencies:

 1. Clone the dependency locally.
 2. `npm install` in its folder.
 3. Run `npm link` in its folder.
 4. Run `npm link $DEP_NAME` in this project folder.
 5. Next time you `gulp dev` it will watch the dependency for changes as well!

### 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`.

### Deploying the UI

 You must be authorized already on the MetaMask plugin.

 0. Update the version in `app/manifest.json` and the Changelog in `CHANGELOG.md`.
 1. Visit [the chrome developer dashboard](https://chrome.google.com/webstore/developer/dashboard?authuser=2).
 2. Run `gulp dist` (or `gulp zip` if you've already built)
 3. Upload the latest zip file from `builds/metamask-$PLATFORM-$VERSION.zip` as the updated package.

[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 - camel case MetaMask 2016-07-06 20:04:26 +02:00			`# MetaMask Plugin [![Build Status](https://circleci.com/gh/MetaMask/metamask-plugin.svg?style=shield&circle-token=a1ddcf3cd38e29267f254c9c59d556d513e3a1fd)](https://circleci.com/gh/MetaMask/metamask-plugin)`
Add simple dev readme 2015-12-21 01:25:45 +01:00
Add simple build instructions (#454) 2016-07-16 03:04:52 +02:00			`## Building locally`

Update readme node version 2016-07-28 20:58:37 +02:00			`- Install [Node.js](https://nodejs.org/en/) version 6.3.1 or later.`
Add simple build instructions (#454) 2016-07-16 03:04:52 +02:00			- Install local dependencies with `npm install`.
Add platform specific builds and zip tasks (#486) * Add platform specific folders to dist folder * Remove gulp hacks * Add platform specific bundling dev and dist tasks now build into platform-specific folders within the `dist` folder. Added tasks `gulp zip` and `gulp dist`. `zip` builds the platform-specific folders into platform-specific bundles within the `dist` folder. `dist` builds and then zips all at once. * Fix chrome bundle zipping * Fix broken reference in eth warning * Fix but where web3.eth.accounts are not available in firefox. * Bump changelog 2016-07-27 00:15:40 +02:00			- Install gulp globally with `npm install -g gulp-cli`.
Add simple build instructions (#454) 2016-07-16 03:04:52 +02:00			- Build the project to the `./dist/` folder with `gulp build`.
			- Optionally, to rebuild on file changes, run `gulp dev`.
Add platform specific builds and zip tasks (#486) * Add platform specific folders to dist folder * Remove gulp hacks * Add platform specific bundling dev and dist tasks now build into platform-specific folders within the `dist` folder. Added tasks `gulp zip` and `gulp dist`. `zip` builds the platform-specific folders into platform-specific bundles within the `dist` folder. `dist` builds and then zips all at once. * Fix chrome bundle zipping * Fix broken reference in eth warning * Fix but where web3.eth.accounts are not available in firefox. * Bump changelog 2016-07-27 00:15:40 +02:00			- 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 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`
			```
Add ui mocking mode explanation 2016-07-01 03:44:37 +02:00
Add mock dev mode 2016-07-22 03:08:35 +02:00			`#### In Chrome`
Add plugin adding doc 2015-12-21 01:31:44 +01:00
			Open `Settings` > `Extensions`.
meta - readme - improve instructions 2016-02-08 21:07:29 +01:00
			`Check "Developer mode".`

Add plugin adding doc 2015-12-21 01:31:44 +01:00			At the top, click `Load Unpacked Extension`.
meta - readme - improve instructions 2016-02-08 21:07:29 +01:00
Fixed deploy instructions 2016-07-27 01:04:26 +02:00			Navigate to your `metamask-plugin/dist/chrome` folder.
meta - readme - improve instructions 2016-02-08 21:07:29 +01:00
Add plugin adding doc 2015-12-21 01:31:44 +01:00			Click `Select`.

			`You now have the plugin, and can click 'inspect views: background plugin' to view its dev console.`
Watch metamask-ui for changes during grunt dev 2016-03-02 21:14:23 +01:00
Fixed deploy instructions 2016-07-27 01:04:26 +02:00			`#### In Firefox`
Add firefox instructions to readme 2016-07-25 22:36:30 +02:00
			Go to the url `about:debugging`.

			Click the button `Load Temporary Add-On`.

Fixed deploy instructions 2016-07-27 01:04:26 +02:00			Select the file `dist/firefox/manifest.json`.
Add firefox instructions to readme 2016-07-25 22:36:30 +02:00
			You can optionally enable debugging, and click `Debug`, for a console window that logs all of Metamask's processes to a single console.

Add note about mozilla irc 2016-07-25 23:03:53 +02:00			If you have problems debugging, try connecting to the IRC channel `#webextensions` on `irc.mozilla.org`.

Add note about firefox stackoverflow to readme 2016-07-25 23:50:19 +02:00			For longer questions, use the StackOverfow tag `firefox-addons`.

Add mock dev mode 2016-07-22 03:08:35 +02:00			`### Developing on UI Only`

			You can run `npm run ui`, and your browser should open a live-reloading demo version of the plugin UI.

			`Some actions will crash the app, so this is only for tuning aesthetics, but it allows live-reloading styles, which is a much faster feedback loop than reloading the full extension.`

			`### Developing on UI with Mocked Background Process`

			You can run `npm run mock` and your browser should open a live-reloading demo version of the plugin UI, just like the `npm run ui`, except that it tries to actually perform all normal operations.

			`It does not yet connect to a real blockchain (this could be a good test feature later, connecting to a test blockchain), so only local operations work.`

			You can reset the mock ui at any time with the `Reset` button at the top of the screen.

			`### Developing on Dependencies`
Watch metamask-ui for changes during grunt dev 2016-03-02 21:14:23 +01:00
Move UI deps into main plugin package.json Also move UI test scripts into main plugin Also move testing explanation to main plugin README. 2016-04-14 00:46:39 +02:00			To enjoy the live-reloading that `gulp dev` offers while working on the `web3-provider-engine` or other dependencies:
Watch metamask-ui for changes during grunt dev 2016-03-02 21:14:23 +01:00
Add grunt watch to web3-provider-engine 2016-03-02 21:48:15 +01:00			`1. Clone the dependency locally.`
Watch metamask-ui for changes during grunt dev 2016-03-02 21:14:23 +01:00			2. `npm install` in its folder.
			3. Run `npm link` in its folder.
Add grunt watch to web3-provider-engine 2016-03-02 21:48:15 +01:00			4. Run `npm link $DEP_NAME` in this project folder.
grunt to gulp readme changes 2016-03-14 10:21:07 +01:00			5. Next time you `gulp dev` it will watch the dependency for changes as well!
Added changelog and deploy docs 2016-03-22 18:43:56 +01:00
Move UI deps into main plugin package.json Also move UI test scripts into main plugin Also move testing explanation to main plugin README. 2016-04-14 00:46:39 +02:00			`### Running Tests`

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

Unify test suites 2016-04-18 20:41:29 +02:00			Then just run `npm test`.

			You can also test with a continuously watching process, via `npm run watch`.
Move UI deps into main plugin package.json Also move UI test scripts into main plugin Also move testing explanation to main plugin README. 2016-04-14 00:46:39 +02:00
Began adding auto linting 2016-06-21 21:07:13 +02:00			You can run the linter by itself with `gulp lint`.

Move UI deps into main plugin package.json Also move UI test scripts into main plugin Also move testing explanation to main plugin README. 2016-04-14 00:46:39 +02:00			`### Deploying the UI`
Added changelog and deploy docs 2016-03-22 18:43:56 +01:00
readme - camel case MetaMask 2016-07-06 20:04:26 +02:00			`You must be authorized already on the MetaMask plugin.`
Added changelog and deploy docs 2016-03-22 18:43:56 +01:00
			0. Update the version in `app/manifest.json` and the Changelog in `CHANGELOG.md`.
			`1. Visit [the chrome developer dashboard](https://chrome.google.com/webstore/developer/dashboard?authuser=2).`
Fixed deploy instructions 2016-07-27 01:04:26 +02:00			2. Run `gulp dist` (or `gulp zip` if you've already built)
			3. Upload the latest zip file from `builds/metamask-$PLATFORM-$VERSION.zip` as the updated package.
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