2016-02-23 18:57:37 +00:00
# ethereumjs-wallet
2016-03-26 18:20:53 +00:00
[![NPM Package ](https://img.shields.io/npm/v/ethereumjs-wallet.svg?style=flat-square )](https://www.npmjs.org/package/ethereumjs-wallet)
2018-01-17 12:51:10 +00:00
[![Build Status ](https://travis-ci.org/ethereumjs/ethereumjs-wallet.svg?branch=master )](https://travis-ci.org/ethereumjs/ethereumjs-wallet)
2016-03-26 18:20:53 +00:00
[![Coverage Status ](https://img.shields.io/coveralls/ethereumjs/ethereumjs-wallet.svg?style=flat-square )](https://coveralls.io/r/ethereumjs/ethereumjs-wallet)
[![Gitter ](https://img.shields.io/gitter/room/ethereum/ethereumjs-lib.svg?style=flat-square )](https://gitter.im/ethereum/ethereumjs-lib) or #ethereumjs on freenode
2016-02-23 18:57:37 +00:00
A lightweight wallet implementation. At the moment it supports key creation and conversion between various formats.
It is complemented by the following packages:
- [ethereumjs-tx ](https://github.com/ethereumjs/ethereumjs-tx ) to sign transactions
- [ethereumjs-icap ](https://github.com/ethereumjs/ethereumjs-icap ) to manipulate ICAP addresses
- [store.js ](https://github.com/marcuswestin/store.js ) to use browser storage
Motivations are:
- be lightweight
- work in a browser
2016-03-25 00:11:44 +00:00
- use a single, maintained version of crypto library (and that should be in line with `ethereumjs-util` and `ethereumjs-tx` )
2016-02-23 18:57:37 +00:00
- support import/export between various wallet formats
2016-03-23 14:21:07 +00:00
- support BIP32 HD keys
2016-02-23 18:57:37 +00:00
Features not supported:
- signing transactions
- managing storage (neither in node.js or the browser)
2016-03-23 02:25:44 +00:00
## Wallet API
2016-02-23 18:57:37 +00:00
Constructors:
2016-02-24 12:55:36 +00:00
* `generate([icap])` - create an instance based on a new random key (setting `icap` to true will generate an address suitable for the `ICAP Direct mode` )
2016-03-26 17:57:34 +00:00
* `generateVanityAddress(pattern)` - create an instance where the address is valid against the supplied pattern (**this will be very slow**)
2016-03-23 00:39:20 +00:00
* `fromPrivateKey(input)` - create an instance based on a raw private key
2016-03-25 16:05:22 +00:00
* `fromExtendedPrivateKey(input)` - create an instance based on a BIP32 extended private key (xprv)
2016-03-23 14:06:27 +00:00
* `fromPublicKey(input, [nonStrict])` - create an instance based on a public key (certain methods will not be available)
2016-03-25 16:05:22 +00:00
* `fromExtendedPublicKey(input)` - create an instance based on a BIP32 extended public key (xpub)
2016-02-24 01:52:12 +00:00
* `fromV1(input, password)` - import a wallet (Version 1 of the Ethereum wallet format)
2016-03-16 13:22:22 +00:00
* `fromV3(input, password, [nonStrict])` - import a wallet (Version 3 of the Ethereum wallet format). Set `nonStrict` true to accept files with mixed-caps.
2016-02-24 01:52:12 +00:00
* `fromEthSale(input, password)` - import an Ethereum Pre Sale wallet
2016-03-08 21:56:10 +00:00
For the V1, V3 and EthSale formats the input is a JSON serialized string. All these formats require a password.
2016-03-23 14:06:27 +00:00
Note: `fromPublicKey()` only accepts uncompressed Ethereum-style public keys, unless the `nonStrict` flag is set to true.
2016-02-23 18:57:37 +00:00
Instance methods:
2016-02-24 01:52:12 +00:00
* `getPrivateKey()` - return the private key
* `getPublicKey()` - return the public key
* `getAddress()` - return the address
2016-03-08 23:24:11 +00:00
* `getChecksumAddressString()` - return the [address with checksum ](https://github.com/ethereum/EIPs/issues/55 )
2016-03-16 13:43:47 +00:00
* `getV3Filename([timestamp])` - return the suggested filename for V3 keystores
2016-02-24 01:52:12 +00:00
* `toV3(password, [options])` - return the wallet as a JSON string (Version 3 of the Ethereum wallet format)
All of the above instance methods return a Buffer or JSON. Use the `String` suffixed versions for a string output, such as `getPrivateKeyString()` .
2016-03-25 16:05:22 +00:00
Note: `getPublicKey()` only returns uncompressed Ethereum-style public keys.
2016-03-23 14:29:30 +00:00
## Thirdparty API
Importing various third party wallets is possible through the `thirdparty` submodule:
`var thirdparty = require('ethereumjs-wallet/thirdparty')`
Constructors:
* `fromEtherCamp(passphrase)` - import a brain wallet used by Ether.Camp
* `fromEtherWallet(input, password)` - import a wallet generated by EtherWallet
* `fromKryptoKit(seed)` - import a wallet from a KryptoKit seed
* `fromQuorumWallet(passphrase, userid)` - import a brain wallet used by Quorum Wallet
2016-03-23 02:25:44 +00:00
## HD Wallet API
To use BIP32 HD wallets, first include the `hdkey` submodule:
`var hdkey = require('ethereumjs-wallet/hdkey')`
Constructors:
* `fromMasterSeed(seed)` - create an instance based on a seed
2016-03-23 14:21:07 +00:00
* `fromExtendedKey(key)` - create an instance based on a BIP32 extended private or public key
2016-03-23 02:25:44 +00:00
For the seed we suggest to use [bip39 ](https://npmjs.org/packages/bip39 ) to create one from a BIP39 mnemonic.
Instance methods:
2016-03-25 16:05:22 +00:00
* `privateExtendedKey()` - return a BIP32 extended private key (xprv)
* `publicExtendedKey()` - return a BIP32 extended public key (xpub)
2016-03-23 02:25:44 +00:00
* `derivePath(path)` - derive a node based on a path (e.g. m/44'/0'/0/1)
* `deriveChild(index)` - derive a node based on a child index
* `getWallet()` - return a `Wallet` instance as seen above
2016-03-25 01:09:57 +00:00
## Provider Engine
The Wallet can be easily plugged into [provider-engine ](https://github.com/metamask/provider-engine ) to provide signing:
```js
const WalletSubprovider = require('ethereumjs-wallet/provider-engine')
< engine > .addProvider(new WalletSubprovider(< wallet instance > ))
```
Note it only supports the basic wallet. With a HD Wallet, call `getWallet()` first.
2016-02-24 01:52:12 +00:00
### Remarks about `toV3`
The `options` is an optional object hash, where all the serialization parameters can be fine tuned:
- uuid - UUID. One is randomly generated.
- salt - Random salt for the `kdf` . Size must match the requirements of the KDF (key derivation function). Random number generated via `crypto.getRandomBytes` if nothing is supplied.
- iv - Initialization vector for the `cipher` . Size must match the requirements of the cipher. Random number generated via `crypto.getRandomBytes` if nothing is supplied.
- kdf - The key derivation function, see below.
- dklen - Derived key length. For certain `cipher` settings, this must match the block sizes of those.
- cipher - The cipher to use. Names must match those of supported by `OpenSSL` , e.g. `aes-128-ctr` or `aes-128-cbc` .
Depending on the `kdf` selected, the following options are available too.
For `pbkdf2` :
- `c` - Number of iterations. Defaults to 262144.
- `prf` - The only supported (and default) value is `hmac-sha256` . So no point changing it.
For `scrypt` :
- `n` - Iteration count. Defaults to 262144.
- `r` - Block size for the underlying hash. Defaults to 8.
- `p` - Parallelization factor. Defaults to 1.
2016-02-23 18:57:37 +00:00
2016-02-24 01:52:12 +00:00
The following settings are favoured by the Go Ethereum implementation and we default to the same:
- `kdf` : `scrypt`
- `dklen` : `32`
- `n` : `262144`
- `r` : `8`
- `p` : `1`
- `cipher` : `aes-128-ctr`
2016-03-23 02:25:44 +00:00
## License
MIT License
Copyright (C) 2016 Alex Beregszaszi