@colony/purser-ledger

These docs serve to outline the API format and methods provided by the @colony/purser-ledger 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.

Hardware

A hardware device that gives you access to it's internal stored account(s). Usually enforced by a hardware true random number generator.

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

Note: udev rules

On unix systems the Ledger Wallet will need udev rules manually set, since the kernel doesn't recognize HID devices by default.

See the Fix connection issues Ledger support issue, for how to set them.

Note: Auto-locking

By default, the Ledger device will auto-lock after 10 minutes. (It will show a screen-saver). When this happens the browser will no longer be able to communicate with it and it will act like it's disconnected.

Only after re-entering your PIN and unlocking it, it will resume normal operation.

Note: Mozilla Firefox U2F

Due to the current state of U2F implementation in Mozilla Firefox, the Ledger Device's Ethereum Wallet will not be able to function, since it relies on features not implemented yet.

On the bright side, the FIDO web authentication app will still work as the features required for that are implemented.

Just make sure you enable U2F functionality, by setting security.webauth.u2f to true, from the about:config page

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 ledger = require('@colony/purser-ledger'); // ledger.open().then();

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

Using ES6 import statements:

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

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

Methods

open

await open(walletArguments: Object);

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

Without any arguments it will open the first 10 accounts in the derivation path, but you can change that via the addressCount object prop argument (Unlike the software wallet, this is the only argument the open method takes, but to preserved consistency, it's still being passed in as an object).

Also, the first index from the addresses that you opened will be selected as the default one (See: the setDefaultAddress() method from the Common Wallet Interface), while the rest of them will be available under the otherAddresses Array prop on the wallet instance.

Argument props

walletArguments.addressCount: Number = 10

Sets the number of addresses to derive from the derivation path. Defaults to 10 and cannot be set lower than 1.

It will set first one as the default (index 0), while the rest will be available through the otherAddresses Array, found as a prop on the Wallet Instance (index 0 through 9 in this case).

You will be able to change them using the setDefaultAddress() instance method (See: Common Wallet Interface for details)).

walletArguments.chainId: Number = 1

Sets the id of the network (eg: homestead, ropsten, etc...) you want your account to be opened under (changes the derivationPath of the opened addresses).

It will also be used if you don't provide one when trying to sign a transaction.

Defaults to id 1: homestead.

Usage examples:

Open the Ledger wallet using the default number of addresses:

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

const wallet = await open();

Open the Ledger wallet using a custom number of addresses:

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

const wallet = await open({ addressCount: 100 });

// Optionally set another address as the default

await wallet.setDefaultAddress(12); //true

Open the Ledger wallet using a different chain id:

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

const wallet = await open({ chainId: 3 }); // ropsten

await wallet.derivationPath; // m/44'/1'/0'/0/0