bitcoinjs-lib/README.md

188 lines
9.1 KiB
Markdown
Raw Normal View History

2014-07-01 19:30:14 +02:00
# BitcoinJS (bitcoinjs-lib)
2011-05-06 01:08:46 +02:00
2014-06-22 16:59:59 +02:00
[![Build Status](https://travis-ci.org/bitcoinjs/bitcoinjs-lib.png?branch=master)](https://travis-ci.org/bitcoinjs/bitcoinjs-lib)
2016-01-27 07:48:25 +01:00
[![NPM](https://img.shields.io/npm/v/bitcoinjs-lib.svg)](https://www.npmjs.org/package/bitcoinjs-lib)
[![tip for next commit](https://tip4commit.com/projects/735.svg)](http://tip4commit.com/projects/735)
2014-03-14 04:37:22 +01:00
[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)
2014-07-02 05:27:58 +02:00
2014-07-01 19:30:14 +02:00
The pure JavaScript Bitcoin library for node.js and browsers.
2016-02-25 08:23:00 +01:00
Used by over a million wallet users and the backbone for almost all Bitcoin web wallets in production today.
2014-07-01 19:30:14 +02:00
## Features
2014-04-23 17:36:46 +02:00
2014-07-01 19:30:14 +02:00
- Clean: Pure JavaScript, concise code, easy to read.
- Tested: Coverage > 90%, third-party integration tests.
- Careful: Two person approval process for small, focused pull requests.
- Compatible: Works on Node.js and all modern browsers.
- Powerful: Support for advanced features, such as multi-sig, HD Wallets.
- Secure: Strong random number generation, PGP signed releases, trusted developers.
- Principled: No support for browsers with crap RNG (IE < 11)
- Standardized: Node community coding style, Browserify, Node's stdlib and Buffers.
- Fast: Optimized code, uses typed arrays instead of byte arrays for performance.
- Experiment-friendly: Bitcoin Mainnet and Testnet support.
- Altcoin-ready: Capable of working with bitcoin-derived cryptocurrencies (such as Dogecoin).
2014-03-08 22:08:08 +01:00
2014-07-01 19:30:14 +02:00
## Should I use this in production?
2016-04-27 08:35:22 +02:00
If you are thinking of using the master branch of this library in production, **stop**.
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).
2011-05-06 01:08:46 +02:00
2014-03-08 22:08:08 +01:00
## Installation
2011-12-20 12:47:50 +01:00
2014-03-01 14:03:37 +01:00
`npm install bitcoinjs-lib`
2014-03-19 04:10:39 +01:00
## Setup
2014-03-08 22:08:08 +01:00
### Node.js
var bitcoin = require('bitcoinjs-lib')
2014-03-08 22:08:08 +01:00
### Browser
If you're familiar with how to use browserify, ignore this and proceed normally.
These steps are advisory only, and may not be necessary for your application.
[Browserify](https://github.com/substack/node-browserify) is assumed to be installed for these steps.
From your repository, create an `index.js` file
``` javascript
module.exports = {
base58: require('bs58'),
bitcoin: require('bitcoinjs-lib'),
ecurve: require('ecurve'),
BigInteger: require('bigi'),
Buffer: require('buffer')
}
```
Install each of the above packages locally
``` bash
npm install bs58 bitcoinjs-lib ecurve bigi buffer
```
After installation, use browserify to compile `index.js` for use in the browser:
``` bash
$ browserify index.js --standalone foo > app.js
```
2016-07-22 16:14:35 +02:00
You will now be able to use `<script src="app.js" />` in your browser, with each of the above exports accessible via the global `foo` object (or whatever you chose for the `--standalone` parameter above).
2014-03-01 14:03:37 +01:00
**NOTE**: See our package.json for the currently supported version of browserify used by this repository.
2015-04-10 02:46:59 +02:00
**NOTE**: When uglifying the javascript, you must exclude the following variable names from being mangled: `Array`, `BigInteger`, `Boolean`, `Buffer`, `ECPair`, `Function`, `Number`, `Point` and `Script`.
This is because of the function-name-duck-typing used in [typeforce](https://github.com/dcousens/typeforce).
2016-04-08 03:45:28 +02:00
Example:
``` bash
uglifyjs ... --mangle --reserved 'Array,BigInteger,Boolean,Buffer,ECPair,Function,Number,Point'
```
2016-07-22 23:58:46 +02:00
### Flow
2016-07-23 13:40:15 +02:00
Definitions for [Flow typechecker](https://flowtype.org/) are available in flow-typed repository.
2016-07-22 23:58:46 +02:00
2016-07-23 13:40:15 +02:00
[You can either download them directly](https://github.com/flowtype/flow-typed/blob/master/definitions/npm/bitcoinjs-lib_v2.x.x/flow_%3E%3Dv0.17.x/bitcoinjs-lib_v2.x.x.js) from the repo, or with the flow-typed CLI
2016-07-22 23:58:46 +02:00
# npm install -g flow-typed
$ flow-typed install -f 0.27 bitcoinjs-lib@2.2.0 # 0.27 for flow version, 2.2.0 for bitcoinjs-lib version
2016-08-13 03:46:42 +02:00
2016-07-23 13:40:15 +02:00
The definitions are complete and up to date with version 2.2.0. The definitions are maintained by [@runn1ng](https://github.com/runn1ng).
## Examples
2014-03-19 04:10:39 +01:00
2014-11-29 02:48:27 +01:00
The below examples are implemented as integration tests, they should be very easy to understand. Otherwise, pull requests are appreciated.
2014-03-19 04:10:39 +01:00
- [Generate a random address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/basic.js#L9)
- [Generate a address from a SHA256 hash](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/basic.js#L20)
- [Generate a address and WIF for Litecoin](https://github.com/bitcoin/bitcoinjs-lib/blob/d853806/test/integration/basic.js#L29)
- [Import an address via WIF](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/basic.js#L43)
- [Create a Transaction](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/basic.js#L50)
- [Create an OP RETURN transaction](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/advanced.js#L24)
- [Create a 2-of-3 multisig P2SH address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/multisig.js#L9)
- [Spend from a 2-of-4 multisig P2SH address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/multisig.js#L25)
- [Generate a single-key stealth address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/stealth.js)
- [Generate a dual-key stealth address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/stealth.js)
- [Create a BIP32 wallet external address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/bip32.js)
- [Create a BIP44, bitcoin, account 0, external address](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/bip32.js)
- [Recover a BIP32 parent private key from the parent public key and a derived non-hardened child private key](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/bip32.js)
- [Recover a Private key from duplicate R values in a signature](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/crypto.js)
- [Create a CLTV locked transaction where the expiry is past](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/cltv.js#L36)
- [Create a CLTV locked transaction where the parties bypass the expiry](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/cltv.js#L70)
- [Create a CLTV locked transaction which fails due to expiry in the future](https://github.com/bitcoinjs/bitcoinjs-lib/blob/d853806/test/integration/cltv.js#L102)
2014-07-10 05:48:54 +02:00
2015-10-27 05:39:34 +01:00
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)!
2014-07-10 05:48:54 +02:00
2014-07-02 01:02:52 +02:00
## Projects utilizing BitcoinJS
2014-03-01 14:03:37 +01:00
2014-07-02 01:02:52 +02:00
- [BitAddress](https://www.bitaddress.org)
- [Blockchain.info](https://blockchain.info/wallet)
2015-03-10 10:04:52 +01:00
- [Blocktrail](https://www.blocktrail.com/)
- [Dark Wallet](https://www.darkwallet.is/)
2015-02-24 02:33:55 +01:00
- [DecentralBank](http://decentralbank.com/)
2014-07-02 01:02:52 +02:00
- [Dogechain Wallet](https://dogechain.info)
2016-02-05 04:44:43 +01:00
- [EI8HT Wallet](http://ei8.ht/)
2014-07-02 01:02:52 +02:00
- [GreenAddress](https://greenaddress.it)
- [Robocoin](https://wallet.robocoin.com)
- [Skyhook ATM](http://projectskyhook.com)
2014-10-14 04:04:27 +02:00
2014-07-02 01:02:52 +02:00
## Contributors
Stefan Thomas is the inventor and creator of this project. His pioneering work made Bitcoin web wallets possible.
2016-04-27 08:33:59 +02:00
Daniel Cousens, Wei Lu, JP Richardson and Kyle Drake lead the major refactor of the library from 0.1.3 to 1.0.0.
2014-07-02 01:02:52 +02:00
Since then, many people have contributed. [Click here](https://github.com/bitcoinjs/bitcoinjs-lib/graphs/contributors) to see the comprehensive list.
2014-09-05 07:45:39 +02:00
2014-03-19 04:10:39 +01:00
## Contributing
2015-11-09 05:37:12 +01:00
We are always accepting of pull requests, but we do adhere to specific standards in regards to coding style, test driven development and commit messages.
2014-03-19 04:10:39 +01:00
Please make your best effort to adhere to these when contributing to save on trivial corrections.
2014-03-19 04:10:39 +01:00
### Running the test suite
2014-03-19 04:10:39 +01:00
$ npm test
2014-07-01 19:30:14 +02:00
$ npm run-script coverage
2014-03-19 04:10:39 +01:00
2014-07-02 01:02:52 +02:00
## Complementing Libraries
- [BIP21](https://github.com/bitcoinjs/bip21) - A BIP21 compatible URL encoding utility library
- [BIP38](https://github.com/bitcoinjs/bip38) - Passphrase-protected private keys
- [BIP39](https://github.com/bitcoinjs/bip39) - Mnemonic generation for deterministic keys
- [BIP32-Utils](https://github.com/bitcoinjs/bip32-utils) - A set of utilities for working with BIP32
- [BIP66](https://github.com/bitcoinjs/bip66) - Strict DER signature decoding
2016-07-21 19:08:43 +02:00
- [BIP69](https://github.com/bitcoinjs/bip69) - Lexicographical Indexing of Transaction Inputs and Outputs
- [Base58](https://github.com/cryptocoinjs/bs58) - Base58 encoding/decoding
- [Base58 Check](https://github.com/bitcoinjs/bs58check) - Base58 check encoding/decoding
2014-07-02 01:02:52 +02:00
- [BCoin](https://github.com/indutny/bcoin) - BIP37 / Bloom Filters / SPV client
2016-10-21 06:22:28 +02:00
- [coinselect](https://github.com/bitcoinjs/coinselect) - A fee-optimizing, transaction input selection module for bitcoinjs-lib.
2014-07-02 01:02:52 +02:00
- [insight](https://github.com/bitpay/insight) - A bitcoin blockchain API for web wallets.
2016-10-21 06:21:02 +02:00
- [merkle-lib](https://github.com/bitcoinjs/merkle-lib) - A performance conscious library for merkle root and tree calculations.
2016-10-21 06:22:28 +02:00
- [minimaldata](https://github.com/bitcoinjs/minimaldata) - A module to check bitcoin policy: SCRIPT_VERIFY_MINIMALDATA
2014-07-02 01:02:52 +02:00
## Alternatives
2014-03-01 14:03:37 +01:00
2014-03-08 22:08:08 +01:00
- [Bitcore](https://github.com/bitpay/bitcore)
- [Cryptocoin](https://github.com/cryptocoinjs/cryptocoin)
2016-01-27 07:45:55 +01:00
## LICENSE [MIT](LICENSE)
2012-07-30 19:09:21 +02:00
2014-03-08 22:08:08 +01:00
## Copyright
2012-07-30 19:09:21 +02:00
2015-12-17 06:23:46 +01:00
BitcoinJS (c) 2011-2016 bitcoinjs-lib contributors
2014-03-01 14:03:37 +01:00
Released under MIT license