1 | # BitcoinJS (bitcoinjs-lib)
|
2 | [![Build Status](https://travis-ci.org/bitcoinjs/bitcoinjs-lib.png?branch=master)](https://travis-ci.org/bitcoinjs/bitcoinjs-lib)
|
3 | [![NPM](https://img.shields.io/npm/v/bitcoinjs-lib.svg)](https://www.npmjs.org/package/bitcoinjs-lib)
|
4 |
|
5 | [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
|
6 |
|
7 | A javascript Bitcoin library for node.js and browsers. Written in TypeScript, but committing the JS files to verify.
|
8 |
|
9 | Released under the terms of the [MIT LICENSE](LICENSE).
|
10 |
|
11 | ## Should I use this in production?
|
12 | If you are thinking of using the *master* branch of this library in production, **stop**.
|
13 | Master is not stable; it is our development branch, and [only tagged releases may be classified as stable](https://github.com/bitcoinjs/bitcoinjs-lib/tags).
|
14 |
|
15 |
|
16 | ## Can I trust this code?
|
17 | > Don't trust. Verify.
|
18 |
|
19 | We recommend every user of this library and the [bitcoinjs](https://github.com/bitcoinjs) ecosystem audit and verify any underlying code for its validity and suitability, including reviewing any and all of your project's dependencies.
|
20 |
|
21 | Mistakes and bugs happen, but with your help in resolving and reporting [issues](https://github.com/bitcoinjs/bitcoinjs-lib/issues), together we can produce open source software that is:
|
22 |
|
23 | - Easy to audit and verify,
|
24 | - Tested, with test coverage >95%,
|
25 | - Advanced and feature rich,
|
26 | - Standardized, using [prettier](https://github.com/prettier/prettier) and Node `Buffer`'s throughout, and
|
27 | - Friendly, with a strong and helpful community, ready to answer questions.
|
28 |
|
29 |
|
30 | ## Documentation
|
31 | Presently, we do not have any formal documentation other than our [examples](#examples), please [ask for help](https://github.com/bitcoinjs/bitcoinjs-lib/issues/new) if our examples aren't enough to guide you.
|
32 |
|
33 |
|
34 | ## Installation
|
35 | ``` bash
|
36 | npm install bitcoinjs-lib
|
37 | ```
|
38 |
|
39 | Typically we support the [Node Maintenance LTS version](https://github.com/nodejs/Release).
|
40 | If in doubt, see the [.travis.yml](.travis.yml) for what versions are used by our continuous integration tests.
|
41 |
|
42 | **WARNING**: We presently don't provide any tooling to verify that the release on `npm` matches GitHub. As such, you should verify anything downloaded by `npm` against your own verified copy.
|
43 |
|
44 |
|
45 | ## Usage
|
46 | Crypto is hard.
|
47 |
|
48 | When working with private keys, the random number generator is fundamentally one of the most important parts of any software you write.
|
49 | For random number generation, we *default* to the [`randombytes`](https://github.com/crypto-browserify/randombytes) module, which uses [`window.crypto.getRandomValues`](https://developer.mozilla.org/en-US/docs/Web/API/window.crypto.getRandomValues) in the browser, or Node js' [`crypto.randomBytes`](https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback), depending on your build system.
|
50 | Although this default is ~OK, there is no simple way to detect if the underlying RNG provided is good enough, or if it is **catastrophically bad**.
|
51 | You should always verify this yourself to your own standards.
|
52 |
|
53 | This library uses [tiny-secp256k1](https://github.com/bitcoinjs/tiny-secp256k1), which uses [RFC6979](https://tools.ietf.org/html/rfc6979) to help prevent `k` re-use and exploitation.
|
54 | Unfortunately, this isn't a silver bullet.
|
55 | Often, Javascript itself is working against us by bypassing these counter-measures.
|
56 |
|
57 | Problems in [`Buffer (UInt8Array)`](https://github.com/feross/buffer), for example, can trivially result in **catastrophic fund loss** without any warning.
|
58 | It can do this through undermining your random number generation, accidentally producing a [duplicate `k` value](https://www.nilsschneider.net/2013/01/28/recovering-bitcoin-private-keys.html), sending Bitcoin to a malformed output script, or any of a million different ways.
|
59 | Running tests in your target environment is important and a recommended step to verify continuously.
|
60 |
|
61 | Finally, **adhere to best practice**.
|
62 | We are not an authorative source of best practice, but, at the very least:
|
63 |
|
64 | * [Don't re-use addresses](https://en.bitcoin.it/wiki/Address_reuse).
|
65 | * Don't share BIP32 extended public keys ('xpubs'). [They are a liability](https://bitcoin.stackexchange.com/questions/56916/derivation-of-parent-private-key-from-non-hardened-child), and it only takes 1 misplaced private key (or a buggy implementation!) and you are vulnerable to **catastrophic fund loss**.
|
66 | * [Don't use `Math.random`](https://security.stackexchange.com/questions/181580/why-is-math-random-not-designed-to-be-cryptographically-secure) - in any way - don't.
|
67 | * Enforce that users always verify (manually) a freshly-decoded human-readable version of their intended transaction before broadcast.
|
68 | * Don't *ask* users to generate mnemonics, or 'brain wallets', humans are terrible random number generators.
|
69 | * Lastly, if you can, use [Typescript](https://www.typescriptlang.org/) or similar.
|
70 |
|
71 |
|
72 | ### Browser
|
73 | The recommended method of using `bitcoinjs-lib` in your browser is through [Browserify](https://github.com/substack/node-browserify).
|
74 | If you're familiar with how to use browserify, ignore this and carry on, otherwise, it is recommended to read the tutorial at https://browserify.org/.
|
75 |
|
76 | **NOTE**: We use Node Maintenance LTS features, if you need strict ES5, use [`--transform babelify`](https://github.com/babel/babelify) in conjunction with your `browserify` step (using an [`es2015`](https://babeljs.io/docs/plugins/preset-es2015/) preset).
|
77 |
|
78 | **WARNING**: iOS devices have [problems](https://github.com/feross/buffer/issues/136), use atleast [buffer@5.0.5](https://github.com/feross/buffer/pull/155) or greater, and enforce the test suites (for `Buffer`, and any other dependency) pass before use.
|
79 |
|
80 | ### Typescript or VSCode users
|
81 | Type declarations for Typescript are included in this library. Normal installation should include all the needed type information.
|
82 |
|
83 | ## Examples
|
84 | The below examples are implemented as integration tests, they should be very easy to understand.
|
85 | Otherwise, pull requests are appreciated.
|
86 | Some examples interact (via HTTPS) with a 3rd Party Blockchain Provider (3PBP).
|
87 |
|
88 | ### Warning: Currently the tests use TransactionBuilder, which will be removed in the future (v6.x.x or higher)
|
89 | We will move towards replacing all instances of TransactionBuilder in the tests with the new Psbt.
|
90 |
|
91 | Currently we have a few examples on how to use the newer Psbt class at the following link:
|
92 | - [Psbt examples](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions-psbt.js)
|
93 |
|
94 | The rest of the examples are below (using TransactionBuilder for Transaction creation)
|
95 |
|
96 | - [Generate a random address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
97 | - [Import an address via WIF](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
98 | - [Generate a 2-of-3 P2SH multisig address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
99 | - [Generate a SegWit address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
100 | - [Generate a SegWit P2SH address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
101 | - [Generate a SegWit 3-of-4 multisig address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
102 | - [Generate a SegWit 2-of-2 P2SH multisig address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
103 | - [Support the retrieval of transactions for an address (3rd party blockchain)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
104 | - [Generate a Testnet address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
105 | - [Generate a Litecoin address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/addresses.js)
|
106 | - [Create a 1-to-1 Transaction](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
107 | - [Create a 2-to-2 Transaction](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
108 | - [Create (and broadcast via 3PBP) a typical Transaction](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
109 | - [Create (and broadcast via 3PBP) a Transaction with an OP\_RETURN output](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
110 | - [Create (and broadcast via 3PBP) a Transaction with a 2-of-4 P2SH(multisig) input](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
111 | - [Create (and broadcast via 3PBP) a Transaction with a SegWit P2SH(P2WPKH) input](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
112 | - [Create (and broadcast via 3PBP) a Transaction with a SegWit P2WPKH input](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
113 | - [Create (and broadcast via 3PBP) a Transaction with a SegWit P2PK input](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
114 | - [Create (and broadcast via 3PBP) a Transaction with a SegWit 3-of-4 P2SH(P2WSH(multisig)) input](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
115 | - [Verify a Transaction signature](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/transactions.js)
|
116 | - [Import a BIP32 testnet xpriv and export to WIF](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/bip32.js)
|
117 | - [Export a BIP32 xpriv, then import it](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/bip32.js)
|
118 | - [Export a BIP32 xpub](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/bip32.js)
|
119 | - [Create a BIP32, bitcoin, account 0, external address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/bip32.js)
|
120 | - [Create a BIP44, bitcoin, account 0, external address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/bip32.js)
|
121 | - [Create a BIP49, bitcoin testnet, account 0, external address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/bip32.js)
|
122 | - [Use BIP39 to generate BIP32 addresses](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/bip32.js)
|
123 | - [Create (and broadcast via 3PBP) a Transaction where Alice can redeem the output after the expiry (in the past)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/cltv.js)
|
124 | - [Create (and broadcast via 3PBP) a Transaction where Alice can redeem the output after the expiry (in the future)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/cltv.js)
|
125 | - [Create (and broadcast via 3PBP) a Transaction where Alice and Bob can redeem the output at any time](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/cltv.js)
|
126 | - [Create (but fail to broadcast via 3PBP) a Transaction where Alice attempts to redeem before the expiry](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/cltv.js)
|
127 | - [Create (and broadcast via 3PBP) a Transaction where Alice can redeem the output after the expiry (in the future) (simple CHECKSEQUENCEVERIFY)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/csv.js)
|
128 | - [Create (but fail to broadcast via 3PBP) a Transaction where Alice attempts to redeem before the expiry (simple CHECKSEQUENCEVERIFY)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/csv.js)
|
129 | - [Create (and broadcast via 3PBP) a Transaction where Bob and Charles can send (complex CHECKSEQUENCEVERIFY)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/csv.js)
|
130 | - [Create (and broadcast via 3PBP) a Transaction where Alice (mediator) and Bob can send after 2 blocks (complex CHECKSEQUENCEVERIFY)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/csv.js)
|
131 | - [Create (and broadcast via 3PBP) a Transaction where Alice (mediator) can send after 5 blocks (complex CHECKSEQUENCEVERIFY)](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/test/integration/csv.js)
|
132 |
|
133 | If you have a use case that you feel could be listed here, please [ask for it](https://github.com/bitcoinjs/bitcoinjs-lib/issues/new)!
|
134 |
|
135 |
|
136 | ## Contributing
|
137 | See [CONTRIBUTING.md](CONTRIBUTING.md).
|
138 |
|
139 |
|
140 | ### Running the test suite
|
141 |
|
142 | ``` bash
|
143 | npm test
|
144 | npm run-script coverage
|
145 | ```
|
146 |
|
147 | ## Complementing Libraries
|
148 | - [BIP21](https://github.com/bitcoinjs/bip21) - A BIP21 compatible URL encoding library
|
149 | - [BIP38](https://github.com/bitcoinjs/bip38) - Passphrase-protected private keys
|
150 | - [BIP39](https://github.com/bitcoinjs/bip39) - Mnemonic generation for deterministic keys
|
151 | - [BIP32-Utils](https://github.com/bitcoinjs/bip32-utils) - A set of utilities for working with BIP32
|
152 | - [BIP66](https://github.com/bitcoinjs/bip66) - Strict DER signature decoding
|
153 | - [BIP68](https://github.com/bitcoinjs/bip68) - Relative lock-time encoding library
|
154 | - [BIP69](https://github.com/bitcoinjs/bip69) - Lexicographical Indexing of Transaction Inputs and Outputs
|
155 | - [Base58](https://github.com/cryptocoinjs/bs58) - Base58 encoding/decoding
|
156 | - [Base58 Check](https://github.com/bitcoinjs/bs58check) - Base58 check encoding/decoding
|
157 | - [Bech32](https://github.com/bitcoinjs/bech32) - A BIP173 compliant Bech32 encoding library
|
158 | - [coinselect](https://github.com/bitcoinjs/coinselect) - A fee-optimizing, transaction input selection module for bitcoinjs-lib.
|
159 | - [merkle-lib](https://github.com/bitcoinjs/merkle-lib) - A performance conscious library for merkle root and tree calculations.
|
160 | - [minimaldata](https://github.com/bitcoinjs/minimaldata) - A module to check bitcoin policy: SCRIPT_VERIFY_MINIMALDATA
|
161 |
|
162 |
|
163 | ## Alternatives
|
164 | - [BCoin](https://github.com/indutny/bcoin)
|
165 | - [Bitcore](https://github.com/bitpay/bitcore)
|
166 | - [Cryptocoin](https://github.com/cryptocoinjs/cryptocoin)
|
167 |
|
168 |
|
169 | ## LICENSE [MIT](LICENSE)
|