Wallets and Signers¶

A Wallet manages a private/public key pair which is used to cryptographically sign transactions and prove ownership on the Ethereum network.

Wallet¶

The Wallet implements the Signer API and can be used anywhere a Signer is expected and has all the required properties.

Creating Instances¶

new ^Wallet ( privateKey [ , provider ] )

Creates a new instance from privateKey and optionally connect a provider

^Wallet . createRandom ( [ options ] ) ^=> ^Wallet

Creates a new random wallet. Ensure this wallet is stored somewhere safe, if lost there is NO way to recover it.

Options may have the properties:

extraEntropy — additional entropy to stir into the random source

^Wallet . fromEncryptedJson ( json, password [ , progressCallback ] ) ^=> ^Wallet

Decrypt an encrypted Secret Storage JSON Wallet (from Geth, parity, Crowdsale tools, or that was created using prototype.encrypt )

^Wallet . fromMnemonic ( mnemonic [ , path ^{= “m/44’/60’/0’/0/0”} [ , wordlist ] ] ) ^=> ^Wallet

Generate a BIP-039 + BIP-044 wallet from mnemonic deriving path using the wordlist. The default language is English (en).

In the browserified dist/ethers.min.js only the English wordlist is available. Each additional wordlist may be included by adding a <script> for the dist/wordlist-*.js

The current supported wordlists are:

Language	node.js	Browser
English (US)	`ethers.wordlists.en`	included
Italian	`ethers.wordlists.it`	`dist/wordlist-it.js`
Japanese	`ethers.wordlists.ja`	`dist/wordlist-ja.js`
Korean	`ethers.wordlists.ko`	`dist/wordlist-ko.js`
Chinese (simplified)	`ethers.wordlists.zh_cn`	`dist/wordlist-zh.js`
Chinese (traditional)	`ethers.wordlists.zh_tw`	`dist/wordlist-zh.js`

^prototype . connect ( provider ) ^=> ^Wallet: Creates a new Wallet instance from an existing instance, connected to a new provider.

load a private key¶

let privateKey = "0x0123456789012345678901234567890123456789012345678901234567890123";
let wallet = new ethers.Wallet(privateKey);

// Connect a wallet to mainnet
let provider = ethers.getDefaultProvider();
let walletWithProvider = new ethers.Wallet(privateKey, provider);

create a new random account¶

let randomWallet = ethers.Wallet.createRandom();

load a JSON wallet¶

let data = {
    id: "fb1280c0-d646-4e40-9550-7026b1be504a",
    address: "88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290",
    Crypto: {
        kdfparams: {
            dklen: 32,
            p: 1,
            salt: "bbfa53547e3e3bfcc9786a2cbef8504a5031d82734ecef02153e29daeed658fd",
            r: 8,
            n: 262144
        },
        kdf: "scrypt",
        ciphertext: "10adcc8bcaf49474c6710460e0dc974331f71ee4c7baa7314b4a23d25fd6c406",
        mac: "1cf53b5ae8d75f8c037b453e7c3c61b010225d916768a6b145adf5cf9cb3a703",
        cipher: "aes-128-ctr",
        cipherparams: {
            iv: "1dcdf13e49cea706994ed38804f6d171"
         }
    },
    "version" : 3
};

let json = JSON.stringify(data);
let password = "foo";

ethers.Wallet.fromEncryptedJson(json, password).then(function(wallet) {
    console.log("Address: " + wallet.address);
    // "Address: 0x88a5C2d9919e46F883EB62F7b8Dd9d0CC45bc290"
});

load a mnemonic phrase¶

let mnemonic = "radar blur cabbage chef fix engine embark joy scheme fiction master release";
let mnemonicWallet = ethers.Wallet.fromMnemonic(mnemonic);

// Load the second account from a mnemonic
let path = "m/44'/60'/1'/0/0";
let secondMnemonicWallet = ethers.Wallet.fromMnemonic(mnemonic, path);

// Load using a non-english locale wordlist (the path "null" will use the default)
let secondMnemonicWallet = ethers.Wallet.fromMnemonic(mnemonic, null, ethers.wordlists.ko);

Prototype¶

^prototype . address

The public address of a wallet

^prototype . privateKey

The private key of a wallet; keep this secret

^prototype . provider

A connected Provider which allows the wallet to connect to the Ethereum network to query its state and send transactions, or null if no provider is connected.

To change the provider, use the connect method, which will return a new instance of the Wallet connected to the provider.

^prototype . mnemonic

The mnemonic phrase for this wallet, or null if the mnemonic is unknown.

^prototype . path

The mnemonic path for this wallet, or null if the mnemonic is unknown.

Signing¶

^prototype . sign ( transaction ) ^=> ^{Promise<string>}

Signs transaction and returns a Promise that resolves to the signed transaction as a hex string.

In general, the sendTransaction method is preferred to sign, as it can automatically populate values asynchronously.

The properties for transaction are all optional and include:

to

gasLimit

gasPrice

nonce

data

value

chainId

^prototype . signMessage ( message ) ^=> ^{Promise<string>}

Signs message and returns a Promise that resolves to the flat-format signature.

If message is a string, it is converted to UTF-8 bytes, otherwise it is preserved as a binary representation of the Arrayish data.

signing transactions¶

let privateKey = "0x3141592653589793238462643383279502884197169399375105820974944592"
let wallet = new ethers.Wallet(privateKey)

console.log(wallet.address)
// "0x7357589f8e367c2C31F51242fB77B350A11830F3"

// All properties are optional
let transaction = {
    nonce: 0,
    gasLimit: 21000,
    gasPrice: utils.bigNumberify("20000000000"),

    to: "0x88a5C2d9919e46F883EB62F7b8Dd9d0CC45bc290",
    // ... or supports ENS names
    // to: "ricmoo.firefly.eth",

    value: utils.parseEther("1.0"),
    data: "0x",

    // This ensures the transaction cannot be replayed on different networks
    chainId: ethers.utils.getNetwork('homestead').chainId
}

let signPromise = wallet.sign(transaction)

signPromise.then((signedTransaction) => {

    console.log(signedTransaction);
    // "0xf86c808504a817c8008252089488a5c2d9919e46f883eb62f7b8dd9d0cc45bc2
    //    90880de0b6b3a76400008025a05e766fa4bbb395108dc250ec66c2f88355d240
    //    acdc47ab5dfaad46bcf63f2a34a05b2cb6290fd8ff801d07f6767df63c1c3da7
    //    a7b83b53cd6cea3d3075ef9597d5"

    // This can now be sent to the Ethereum network
    let provider = ethers.getDefaultProvider()
    provider.sendTransaction(signedTransaction).then((tx) => {

        console.log(tx);
        // {
        //    // These will match the above values (excluded properties are zero)
        //    "nonce", "gasLimit", "gasPrice", "to", "value", "data", "chainId"
        //
        //    // These will now be present
        //    "from", "hash", "r", "s", "v"
        //  }
        // Hash:
    });
})

signing text messages¶

let privateKey = "0x3141592653589793238462643383279502884197169399375105820974944592"
let wallet = new ethers.Wallet(privateKey);

// Sign a text message
let signPromise = wallet.signMessage("Hello World!")

signPromise.then((signature) => {

    // Flat-format
    console.log(signature);
    // "0xea09d6e94e52b48489bd66754c9c02a772f029d4a2f136bba9917ab3042a0474
    //    301198d8c2afb71351753436b7e5a420745fed77b6c3089bbcca64113575ec3c
    //    1c"

    // Expanded-format
    console.log(ethers.utils.splitSignature(signature));
    // {
    //   r: "0xea09d6e94e52b48489bd66754c9c02a772f029d4a2f136bba9917ab3042a0474",
    //   s: "0x301198d8c2afb71351753436b7e5a420745fed77b6c3089bbcca64113575ec3c",
    //   v: 28,
    //   recoveryParam: 1
    //  }
});

signing binary messages¶

let privateKey = "0x3141592653589793238462643383279502884197169399375105820974944592"
let wallet = new ethers.Wallet(privateKey);

// The 66 character hex string MUST be converted to a 32-byte array first!
let hash = "0x3ea2f1d0abf3fc66cf29eebb70cbd4e7fe762ef8a09bcc06c8edf641230afec0";
let binaryData = ethers.utils.arrayify(hash);

let signPromise = wallet.signMessage(binaryData)

signPromise.then((signature) => {

    console.log(signature);
    // "0x5e9b7a7bd77ac21372939d386342ae58081a33bf53479152c87c1e787c27d06b
    //    118d3eccff0ace49891e192049e16b5210047068384772ba1fdb33bbcba58039
    //    1c"
});

Blockchain Operations¶

These operations require the wallet have a provider attached to it.

^prototype . getBalance ( [ blockTag ^{= “latest”} ] ) ^=> ^{Promise<BigNumber>}: Returns a Promise that resolves to the balance of the wallet (as a BigNumber, in wei) at the blockTag.
^prototype . getTransactionCount ( [ blockTag ^{= “latest”} ] ) ^=> ^{Promise<number>}: Returns a Promise that resovles to the number of transactions this account has ever sent (also called the nonce) at the blockTag.
^prototype . estimateGas ( transaction ) ^=> ^{Promise<BigNumber>}: Returns a Promise with the estimated cost for transaction (as a BigNumber, in gas)

^prototype . sendTransaction ( transaction ) ^=> ^{Promise<TransactionResponse>}: Sends the transaction (see Transaction Requests) to the network and returns a Promise that resolves to a Transaction Response. Any properties that are not provided will be populated from the network.

query the network¶

// We require a provider to query the network
let provider = ethers.getDefaultProvider();

let privateKey = "0x3141592653589793238462643383279502884197169399375105820974944592"
let wallet = new ethers.Wallet(privateKey, provider);

let balancePromise = wallet.getBalance();

balancePromise.then((balance) => {
    console.log(balance);
});

let transactionCountPromise = wallet.getTransactionCount();

transactionCountPromise.then((transactionCount) => {
    console.log(transactionCount);
});

transfer ether¶

// We require a provider to send transactions
let provider = ethers.getDefaultProvider();

let privateKey = "0x3141592653589793238462643383279502884197169399375105820974944592"
let wallet = new ethers.Wallet(privateKey, provider);

let amount = ethers.utils.parseEther('1.0');

let tx = {
    to: "0x88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290",
    // ... or supports ENS names
    // to: "ricmoo.firefly.eth",

    // We must pass in the amount as wei (1 ether = 1e18 wei), so we
    // use this convenience function to convert ether to wei.
    value: ethers.utils.parseEther('1.0')
};

let sendPromise = wallet.sendTransaction(tx);

sendPromise.then((tx) => {
    console.log(tx);
    // {
    //    // All transaction fields will be present
    //    "nonce", "gasLimit", "pasPrice", "to", "value", "data",
    //    "from", "hash", "r", "s", "v"
    // }
});

Encrypted JSON Wallets¶

Many systems store private keys as encrypted JSON wallets, in various formats. There are several formats and algorithms that are used, all of which are supported to be read. Only the secure scrypt variation can be generated.

See Wallet.fromEncryptedJson for creating a Wallet instance from a JSON wallet.

^prototype . encrypt ( password [ , options [ , progressCallback ] ] ) ^=> ^{Promise<string>}

Encrypts the wallet as an encrypted JSON wallet, with the password.

All options are optional. The valid options are:

salt — the salt to use for scrypt

iv — the initialization vecotr to use for aes-ctr-128

uuid — the UUID to use for the wallet

scrypt — the scrypt parameters to use (N, r and p)

entropy — the mnemonic entropy of this wallet; generally you should not specify this

mnemonic — the mnemonic phrase of this wallet; generally you should not specify this

path — the mnemonic path of this wallet; generally you should not specify this

If the progressCallback is specified, it will be called periodically during encryption with a value between 0 and 1, inclusive indicating the progress.

encrypt a wallet as an encrypted JSON wallet¶

let password = "password123";

function callback(progress) {
    console.log("Encrypting: " + parseInt(progress * 100) + "% complete");
}

let encryptPromise = wallet.encrypt(password, callback);

encryptPromise.then(function(json) {
    console.log(json);
});

Signer API¶

The Signer API is an abstract class which makes it easy to extend and add new signers, that can be used by this library and extension libraries. The Wallet extends the Signer API, as do the JsonRpcSigner and the Ledger Hardware Wallet Signer.

To implement a Signer, inherit the abstract class ethers.types.Signer and implement the following properties:

^object . provider

A Provider that is connected to the network. This is optional, however, without a provider, only write-only operations should be expected to work.

^object . getAddress ( ) ^=> ^{Promise<Address>}

Returns a Promise that resolves to the account address.

^object . signMessage ( message ) ^=> ^Promise<hex>

Returns a Promise that resolves to the Flat-Format Signature for the message.

If message is a string, it is converted to UTF-8 bytes, otherwise it is preserved as a binary representation of the Arrayish data.

^object . sendTransaction ( transaction ) ^=> ^{Promise<TransactionResponse>}

Sends the transaction (see Transaction Requests) to the network and returns a Promise that resolves to a Transaction Response. Any properties that are not provided will be populated from the network.