@colony/purser-metamask

These docs serve to outline the API format and methods provided by the @colony/purser-metamsk library.

Unlike other wallet libraries, this one works entirely in async mode, meaning every return will be a Promise that must resolve (or reject, if something goes wrong...).

Console output

In development mode there will be a number of warnings or errors outputted verbosely to the console.

When building with NODE_ENV=production all output will be silenced.

Metmask

A browser extension that provides a more secure interface to a software wallet. Available for Chrome, Firefox or Opera.

For a more in-depth look at what the resulting object looks like, see the Common Wallet Interface docs.

Note: Transaction signing and implicit sending

Although this library focuses to be offline, this is not entirely true in the case of Metamask. This is because Metamask doesn't allow you to just sign a transaction. After signing, it will also broadcast it to the network.

Currently this cannot be overcome and you as a developer have to be aware of it.

There's an issue tracking the progress of this currently: MetaMask/metamask-extension#3475.

Imports:

There are different ways in which you can import the library in your project (as a module), but in the end they all bring in the same thing:

Using ES5 require() statements:

var metamask = require('@colony/purser-metamask'); // metamask.open().then();

var open = require('@colony/purser-metamask').open; // open().then();

Using ES6 import statements:

import metamask from '@colony/purser-metamask'; // await metamask.open();

import { open } from '@colony/purser-metamask'; // await open();

Methods

open

await open(walletArguments: Object);

This method returns a Promise which, after resolving, it will return a new MetamaskWallet instance object. (See: Common Wallet Interface for details).

Unlike the other wallet types in this library, this static method does not take any arguments. It will use the selected address from Metamask.

Note: If Metamask is not unlocked it cannot access the address, so an Error will be thrown.

Usage examples:

Open the metamask wallet:

import { open } from '@colony/purser-metamask';

const wallet = await open();

detect

await detect();

This is a helper method to detect if the Metamask injected web3 proxy instance is available. It's not necessary for you to use since it's baked into the library, it's just exposed here for convenience.

This method returns a Promise which, after resolving, it will return only return true, if the Metamask instance is available and can be interacted with (not locked). Otherwise it will throw an Error with the specific problem it encountered.

Usage examples:

Open the metamask wallet:

import { detect as isMetamaskAvailable } from '@colony/purser-metamask';

await isMetamaskAvailable(); // true