bitcoinjs-lib/README.md

149 lines
4.8 KiB
Markdown
Raw Normal View History

2011-05-06 01:08:46 +02:00
# bitcoinjs-lib
2014-04-08 16:53:31 +02:00
[![Build Status](https://travis-ci.org/bitcoinjs/bitcoinjs-lib.png?branch=master)](https://travis-ci.org/bitcoinjs/bitcoinjs-lib) [![Coverage Status](https://coveralls.io/repos/bitcoinjs/bitcoinjs-lib/badge.png)](https://coveralls.io/r/bitcoinjs/bitcoinjs-lib)
2014-03-14 04:37:22 +01:00
2014-03-14 19:15:56 +01:00
[![Browser Support](https://ci.testling.com/bitcoinjs/bitcoinjs-lib.png)](https://ci.testling.com/bitcoinjs/bitcoinjs-lib)
2013-04-21 11:04:23 +02:00
A pure JavaScript Bitcoin library for node.js and browsers.
A continued implementation of the original `0.1.3` version used by over a million wallet users; and the backbone for almost all Bitcoin web wallets in production today.
## Should I use this in production?
2014-04-23 17:36:46 +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.
Master is currently being heavily refactored to clean things up, add new functionality and merge improvements from the community.
If you are looking for the original, it is tagged as `0.1.3`.
2014-04-23 17:36:46 +02:00
We are releasing quasi-stable releases tagged under `0.2.x`, with the expectation that this is still beta software and is `PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED`.
This is not the original bitcoinjs-lib that was not updated for a long time.
2014-03-08 22:08:08 +01:00
## Features
2011-05-06 01:08:46 +02:00
2014-03-08 22:08:08 +01:00
- Bitcoin Testnet and Mainnet (production) support
2014-03-01 14:03:37 +01:00
- [HD Wallets](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
- Random private key generation that uses [window.crypto.getRandomValues](https://developer.mozilla.org/en-US/docs/Web/API/Window.crypto) in the underlying implementation.
2014-03-01 14:03:37 +01:00
- ECDSA signing and verification
- Standard Transaction creation (pay-to-pubkey-hash), support for multisignature transactions
2014-03-08 22:08:08 +01:00
- A (somewhat incomplete) wallet implementation, improvements ongoing
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-08 22:08:08 +01:00
Note: The npm version is currently out of date, are working to resolve this. The best way to use the latest code is to clone the repository.
2014-03-19 04:10:39 +01:00
## Setup
2014-03-08 22:08:08 +01:00
### Node.js
var bitcoin = require('bitcoinjs-lib')
From the repo:
2014-03-01 14:03:37 +01:00
2014-03-08 22:08:08 +01:00
var bitcoin = require('./src/index.js')
2014-03-01 14:03:37 +01:00
2014-03-08 22:08:08 +01:00
### Browser
2014-03-08 22:08:08 +01:00
Compile `bitcoinjs-min.js` with the following command:
2014-03-08 22:08:08 +01:00
$ npm run-script compile
2014-03-08 22:08:08 +01:00
After loading this file in your browser, you will be able to use the global `Bitcoin` object.
2014-03-01 14:03:37 +01:00
2014-03-19 04:10:39 +01:00
## Usage
These examples assume you are running bitcoinjs-lib in the browser.
2014-03-19 04:10:39 +01:00
### Generating a Bitcoin address
```javascript
key = Bitcoin.ECKey.makeRandom()
2014-03-19 04:10:39 +01:00
2014-05-24 02:17:14 +02:00
// Print your private key (in WIF format)
console.log(key.toWIF())
// => 8c112cf628362ecf4d482f68af2dbb50c8a2cb90d226215de925417aa9336a48
2014-03-19 04:10:39 +01:00
2014-05-24 02:17:14 +02:00
// Print your public key (toString defaults to a Bitcoin address)
console.log(key.pub.getAddress().toString())
// => 14bZ7YWde4KdRb5YN7GYkToz3EHVCvRxkF
2014-03-19 04:10:39 +01:00
```
### Creating a Transaction
```javascript
tx = new Bitcoin.Transaction()
// Add the input (who is paying) of the form [previous transaction hash, index of the output to use]
tx.addInput("aa94ab02c182214f090e99a0d57021caffd0f195a81c24602b1028b130b63e31", 0)
2014-03-19 04:10:39 +01:00
// Add the output (who to pay to) of the form [payee's address, amount in satoshis]
tx.addOutput("1Gokm82v6DmtwKEB8AiVhm82hyFSsEvBDK", 15000)
2014-03-19 04:10:39 +01:00
// Initialize a private key using hex
key = Bitcoin.ECKey.fromHex("8c112cf628362ecf4d482f68af2dbb50c8a2cb90d226215de925417aa9336a48")
2014-03-19 04:10:39 +01:00
// Sign the first input with the new key
2014-03-19 04:10:39 +01:00
tx.sign(0, key)
// Print transaction serialized as hex
2014-03-19 04:10:39 +01:00
console.log(tx.serializeHex())
// => 0100000001313eb630b128102b60241ca895f1d0ffca2170d5a0990e094f2182c102ab94aa000000008a47304402200169f1f844936dc60df54e812345f5dd3e6681fea52e33c25154ad9cc23a330402204381ed8e73d74a95b15f312f33d5a0072c7a12dd6c3294df6e8efbe4aff27426014104e75628573696aed32d7656fb35e9c71ea08eb6492837e13d2662b9a36821d0fff992692fd14d74fdec20fae29128ba12653249cbeef521fc5eba84dde0689f27ffffffff01983a0000000000001976a914ad618cf4333b3b248f9744e8e81db2964d0ae39788ac00000000
// You could now push the transaction onto the Bitcoin network manually (see https://blockchain.info/pushtx)
2014-03-19 04:10:39 +01:00
```
2014-03-08 22:08:08 +01:00
## Projects utilizing bitcoinjs-lib
2014-03-01 14:03:37 +01:00
2014-03-08 22:08:08 +01:00
- [Blockchain.info Wallet](http://blockchain.info/wallet)
- [Bitaddress.org](https://www.bitaddress.org)
2014-03-08 22:10:39 +01:00
- [Coinpunk](https://coinpunk.com)
- [DarkWallet](https://darkwallet.unsystem.net)
- [GreenAddress](https://greenaddress.it)
2014-03-01 14:03:37 +01:00
2014-03-08 22:12:18 +01:00
Feel free to send pull requests to have your project/startup listed here.
2014-03-19 04:10:39 +01:00
## Contributing
### Instructions
1. Fork the repo
2. Push changes to your fork
2014-03-19 04:10:39 +01:00
3. Create a pull request
### Running the test suite
2014-03-19 04:10:39 +01:00
$ npm test
2014-03-08 22:08:08 +01: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)
2014-03-08 22:08:08 +01:00
## License
2011-12-20 12:47:50 +01:00
2014-03-08 22:08:08 +01:00
This library is free and open-source software released under the 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
2014-03-01 14:03:37 +01:00
BitcoinJS (c) 2011-2012 Stefan Thomas
Released under MIT license
2012-07-30 19:09:21 +02:00
http://bitcoinjs.org/
2014-03-01 14:03:37 +01:00
CryptoJS (c) 20092012 by Jeff Mott
Released under New BSD license
2012-07-30 19:09:21 +02:00
http://code.google.com/p/crypto-js/