1 | # ethereumjs-wallet
|
2 |
|
3 | [![NPM Package][npm-badge]][npm-link]
|
4 | [![Actions Status][actions-badge]][actions-link]
|
5 | [![Coverage Status][coverage-badge]][coverage-link]
|
6 | [![Discord][discord-badge]][discord-link]
|
7 |
|
8 | A lightweight wallet implementation. At the moment it supports key creation and conversion between various formats.
|
9 |
|
10 | It is complemented by the following packages:
|
11 |
|
12 | - [@ethereumjs/tx](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/tx) to sign transactions
|
13 | - [ethereumjs-icap](https://github.com/ethereumjs/ethereumjs-icap) to manipulate ICAP addresses
|
14 | - [store.js](https://github.com/marcuswestin/store.js) to use browser storage
|
15 |
|
16 | Motivations are:
|
17 |
|
18 | - be lightweight
|
19 | - work in a browser
|
20 | - use a single, maintained version of crypto library (and that should be in line with [`ethereumjs-util`](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/util) and `@ethereumjs/tx`)
|
21 | - support import/export between various wallet formats
|
22 | - support BIP32 HD keys
|
23 |
|
24 | Features not supported:
|
25 |
|
26 | - signing transactions
|
27 | - managing storage (neither in node.js or the browser)
|
28 |
|
29 | ## Wallet API
|
30 |
|
31 | For information about the Wallet's API, please go to [./docs/classes/wallet.md](./docs/classes/wallet.md).
|
32 |
|
33 | You can import the `Wallet` class like this
|
34 |
|
35 | Node.js / ES5:
|
36 |
|
37 | ```js
|
38 | const Wallet = require('ethereumjs-wallet').default
|
39 | ```
|
40 |
|
41 | ESM / TypeScript:
|
42 |
|
43 | ```js
|
44 | import Wallet from 'ethereumjs-wallet'
|
45 | ```
|
46 |
|
47 | ## Thirdparty API
|
48 |
|
49 | Importing various third party wallets is possible through the `thirdparty` submodule:
|
50 |
|
51 | Node.js / ES5:
|
52 |
|
53 | ```js
|
54 | const { thirdparty } = require('ethereumjs-wallet')
|
55 | ```
|
56 |
|
57 | ESM / TypeScript:
|
58 |
|
59 | ```js
|
60 | import { thirdparty } from 'ethereumjs-wallet'
|
61 | ```
|
62 |
|
63 | Please go to [./docs/README.md](./docs/README.md) for more info.
|
64 |
|
65 | ## HD Wallet API
|
66 |
|
67 | To use BIP32 HD wallets, first include the `hdkey` submodule:
|
68 |
|
69 | Node.js / ES5:
|
70 |
|
71 | ```js
|
72 | const { hdkey } = require('ethereumjs-wallet')
|
73 | ```
|
74 |
|
75 | ESM / TypeScript:
|
76 |
|
77 | ```js
|
78 | import { hdkey } from 'ethereumjs-wallet'
|
79 | ```
|
80 |
|
81 | Please go to [./docs/classes/ethereumhdkey.md](./docs/classes/ethereumhdkey.md) for more info.
|
82 |
|
83 | ## Provider Engine
|
84 |
|
85 | Provider Engine is
|
86 | [not very actively maintained](https://github.com/MetaMask/web3-provider-engine#web3-providerengine)
|
87 | and support has been removed along `v1.0.0` release, see
|
88 | issue [#115](https://github.com/ethereumjs/ethereumjs-wallet/issues/115) for context.
|
89 |
|
90 | You can use the the old `src/provider-engine.ts` code (see associated PR) as some boilerplate
|
91 | for your own integration if needed.
|
92 |
|
93 | ## Remarks about `toV3`
|
94 |
|
95 | The `options` is an optional object hash, where all the serialization parameters can be fine tuned:
|
96 |
|
97 | - uuid - UUID. One is randomly generated.
|
98 | - 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.
|
99 | - iv - Initialization vector for the `cipher`. Size must match the requirements of the cipher. Random number generated via `crypto.getRandomBytes` if nothing is supplied.
|
100 | - kdf - The key derivation function, see below.
|
101 | - dklen - Derived key length. For certain `cipher` settings, this must match the block sizes of those.
|
102 | - cipher - The cipher to use. Names must match those of supported by `OpenSSL`, e.g. `aes-128-ctr` or `aes-128-cbc`.
|
103 |
|
104 | Depending on the `kdf` selected, the following options are available too.
|
105 |
|
106 | For `pbkdf2`:
|
107 |
|
108 | - `c` - Number of iterations. Defaults to 262144.
|
109 | - `prf` - The only supported (and default) value is `hmac-sha256`. So no point changing it.
|
110 |
|
111 | For `scrypt`:
|
112 |
|
113 | - `n` - Iteration count. Defaults to 262144.
|
114 | - `r` - Block size for the underlying hash. Defaults to 8.
|
115 | - `p` - Parallelization factor. Defaults to 1.
|
116 |
|
117 | The following settings are favoured by the Go Ethereum implementation and we default to the same:
|
118 |
|
119 | - `kdf`: `scrypt`
|
120 | - `dklen`: `32`
|
121 | - `n`: `262144`
|
122 | - `r`: `8`
|
123 | - `p`: `1`
|
124 | - `cipher`: `aes-128-ctr`
|
125 |
|
126 | # EthereumJS
|
127 |
|
128 | See our organizational [documentation](https://ethereumjs.readthedocs.io) for an introduction to `EthereumJS` as well as information on current standards and best practices.
|
129 |
|
130 | If you want to join for work or do improvements on the libraries have a look at our [contribution guidelines](https://ethereumjs.readthedocs.io/en/latest/contributing.html).
|
131 |
|
132 | ## License
|
133 |
|
134 | MIT License
|
135 |
|
136 | Copyright (C) 2016 Alex Beregszaszi
|
137 |
|
138 | [actions-badge]: https://github.com/ethereumjs/ethereumjs-wallet/workflows/Build/badge.svg
|
139 | [actions-link]: https://github.com/ethereumjs/ethereumjs-wallet/actions
|
140 | [coverage-badge]: https://img.shields.io/coveralls/ethereumjs/ethereumjs-wallet.svg
|
141 | [coverage-link]: https://coveralls.io/r/ethereumjs/ethereumjs-wallet
|
142 | [discord-badge]: https://img.shields.io/static/v1?logo=discord&label=discord&message=Join&color=blue
|
143 | [discord-link]: https://discord.gg/TNwARpR
|
144 | [npm-badge]: https://img.shields.io/npm/v/ethereumjs-wallet.svg
|
145 | [npm-link]: https://www.npmjs.org/package/ethereumjs-wallet
|