diff --git a/README.md b/README.md index 1491854..df162db 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ A pure, powerful core for your bitcoin project. Bitcore is a complete, native interface to the Bitcoin network, and provides the core functionality needed to develop apps for bitcoin. #Principles + Bitcoin is a powerful new peer-to-peer platform for the next generation of financial technology. The decentralized nature of the Bitcoin network allows for highly resilient bitcoin infrastructure, and the developer community needs reliable, open-source tools to implement bitcoin apps and services. **Bitcore unchains developers from fallible, centralized APIs, and provides the tools to interact with the real Bitcoin network.** @@ -15,11 +16,13 @@ Bitcoin is a powerful new peer-to-peer platform for the next generation of finan #Get Started Bitcore runs on [node](http://nodejs.org/), and can be installed via [npm](https://npmjs.org/): + ``` npm install bitcore ``` It is a collection of objects useful to bitcoin applications; class-like idioms are enabled via [Soop](https://github.com/bitpay/soop). In most cases, a developer will require the object's class directly. For instance: + ``` var bitcore = require('bitcore'); var Address = bitcore.Address; @@ -32,7 +35,9 @@ var PeerManager = bitcore.PeerManager; Some examples are provided at the [examples](/examples) path. Here are some snippets: ## Validating an address + Validating a Bitcoin address: + ```js var bitcore = require('bitcore'); var Address = bitcore.Address; @@ -51,8 +56,11 @@ addrs.forEach(function(addr) { console.log(addr.data + ' is ' + (valid ? '' : 'not ') + 'valid'); }); ``` + ## Monitoring Blocks and Transactions + For this example you need a running bitcoind instance with RPC enabled. + ```js var bitcore = require('bitcore'); var networks = bitcore.networks; @@ -68,7 +76,6 @@ var handleBlock = function(info) { var handleTx = function(info) { var tx = info.message.tx.getStandardizedObject(); - console.log('** TX Received **'); console.log(tx); }; @@ -76,7 +83,6 @@ var handleTx = function(info) { var handleInv = function(info) { console.log('** Inv **'); console.log(info.message); - var invs = info.message.invs; info.conn.sendGetData(invs); }; @@ -96,9 +102,10 @@ peerman.start(); PeerManager will emit the following events: 'version', 'verack', 'addr', 'getaddr', 'error' 'disconnect'; and will relay events like: 'tx', 'block', 'inv'. Please see [PeerManager.js](PeerManager.js), [Peer.js](Peer.js) and [Connection.js](Connection.js) - ## Consuming bitcoind RPC -For this example you need a running bitcoind instance with RPC enabled. + +For this example you need a running bitcoind instance with RPC enabled. + ```js var bitcore = require('bitcore'); var RpcClient = bitcore.RpcClient; @@ -123,6 +130,7 @@ rpc.getBlock(hash, function(err, ret) { console.log(ret); }); ``` + Check the list of all supported RPC call at [RpcClient.js](RpcClient.js) ## Creating and sending a Transaction through P2P @@ -140,69 +148,66 @@ var PeerManager = require('soop').load('../PeerManager', { network: networks.testnet }); -// this can be get from insight.bitcore.io API o blockchain.info - +// Unspent transactions can be found via the insight.bitcore.io or blockchain.info APIs var unspent = [ - { - "address": "n4g2TFaQo8UgedwpkYdcQFF6xE2Ei9Czvy", - "txid": "2ac165fa7a3a2b535d106a0041c7568d03b531e58aeccdd3199d7289ab12cfc1", - "scriptPubKey": "76a914fe021bac469a5c49915b2a8ffa7390a9ce5580f988ac", - "vout": 1, - "amount": 1.0101, - "confirmations":7 - }, - { - "address": "mhNCT9TwZAGF1tLPpZdqfkTmtBkY282YDW", - "txid": "2ac165fa7a3a2b535d106a0041c7568d03b531e58aeccdd3199d7289ab12cfc2", - "scriptPubKey": "76a9141448534cb1a1ec44665b0eb2326e570814afe3f188ac", - "vout": 0, - "confirmations": 1, - "amount": 10 - }, + { + "address": "n4g2TFaQo8UgedwpkYdcQFF6xE2Ei9Czvy", + "txid": "2ac165fa7a3a2b535d106a0041c7568d03b531e58aeccdd3199d7289ab12cfc1", + "scriptPubKey": "76a914fe021bac469a5c49915b2a8ffa7390a9ce5580f988ac", + "vout": 1, + "amount": 1.0101, + "confirmations":7 + }, + { + "address": "mhNCT9TwZAGF1tLPpZdqfkTmtBkY282YDW", + "txid": "2ac165fa7a3a2b535d106a0041c7568d03b531e58aeccdd3199d7289ab12cfc2", + "scriptPubKey": "76a9141448534cb1a1ec44665b0eb2326e570814afe3f188ac", + "vout": 0, + "confirmations": 1, + "amount": 10 + } ]; -//private keys in WIF format (see TransactionBuilder.js for other options) +// Private keys in WIF format (see TransactionBuilder.js for other options) var keys = [ "cSq7yo4fvsbMyWVN945VUGUWMaSazZPWqBVJZyoGsHmNq6W4HVBV", "cPa87VgwZfowGZYaEenoQeJgRfKW6PhZ1R65EHTkN1K19cSvc92G", "cPQ9DSbBRLva9av5nqeF5AGrh3dsdW8p2E5jS4P8bDWZAoQTeeKB" ]; - var peerman = new PeerManager(); peerman.addPeer(new Peer('127.0.0.1', 18333)); peerman.on('connect', function() { var conn = peerman.getActiveConnection(); if (conn) { - var outs = [{address:toAddress, amount:amt}]; + var outs = [{address: toAddress, amount: amt}]; var opts = {remainderOut: {address: changeAddressString}}; var TransactionBuilder = bitcore.TransactionBuilder; var tx = new TransactionBuilder(opts) - .setUnspent(Unspent) - .setOutputs(outs) - .sign(keys) - .build(); + .setUnspent(unspent) + .setOutputs(outs) + .sign(keys) + .build(); - /* create and signing can be done in multiple steps using: + /* Create and signing can be done in multiple steps: * * var builder = new bitcore.TransactionBuilder(opts) - * .setUnspent(utxos) - * .setOutputs(outs); - * //later - * builder.sign(key1); - * // get partially signed tx - * var tx = builder.build(); + * .setUnspent(utxos) + * .setOutputs(outs); * - * //later + * // Sign with the first key + * builder.sign(key1); + * var tx = builder.build(); // Partially signed transaction + * + * // Sign with the second key * builder.sign(key2); * if (builder.isFullySigned()){ * var tx = builder.build(); * } * - * The selected Unspent Outputs for the transaction can be retrieved with: - * var selectedUnspent = build.getSelectedUnspent(); + * var selectedUnspent = build.getSelectedUnspent(); // Retrieve selected unspent outputs from the transaction */ conn.sendTx(tx.serialize().toString('hex')); } @@ -214,8 +219,7 @@ peerman.on('connect', function() { peerman.start(); ``` - -## Parsing a Script +## Parsing a Script Gets an address strings from a ScriptPubKey Buffer @@ -265,25 +269,26 @@ console.log(getAddrStr(s)[0]); // mkZBYBiq6DNoQEKakpMJegyDbw2YiNQnHT ``` #Security + Please use at your own risk. Bitcore is still under heavy development and not quite ready for "drop-in" production use. If you find a security issue, please email security@bitcore.io. #Contributing + Bitcore needs some developer love. Please send pull requests for bug fixes, code optimization, and ideas for improvement. #Browser support + ## Building the browser bundle -To build bitcore full bundle for the browser: -(this is automatically executed after you run `npm install`) + +To build bitcore full bundle for the browser (this is automatically executed after you run `npm install`): ``` node browser/build.js -a ``` -This will generate a `browser/bundle.js` file which you can include -in your HTML to use bitcore in the browser. -## +This will generate a `browser/bundle.js` file which you can include in your HTML to use bitcore in the browser. ##Example browser usage @@ -303,23 +308,21 @@ From example/simple.html ``` -You can check a more complex usage example at examples/example.html +You can check a more complex usage example at examples/example.html. ## Generating a customized browser bundle -To generate a customized bitcore bundle, you can specify -which submodules you want to include in it with the -s option: + +To generate a customized bitcore bundle, you can specify which submodules you want to include in it with the -s option: ``` node browser/build.js -s Transaction,Address ``` -This will generate a `browser/bundle.js` containing only the Transaction - and Address class, with all their dependencies. -Use this option if you are not using the whole bitcore library, to optimize -the bundle size, script loading time, and general resource usage. + +This will generate a `browser/bundle.js` containing only the Transaction and Address class, with all their dependencies. Use this option if you are not using the whole bitcore library, to optimize the bundle size, script loading time, and general resource usage. ## Tests -Run tests in node: +Run tests in node: ``` mocha @@ -341,13 +344,10 @@ npm run-script coverage And then open coverage/lcov-report/index.html in your browser. - #License **Code released under [the MIT license](https://github.com/bitpay/bitcore/blob/master/LICENSE).** Copyright 2013-2014 BitPay, Inc. Bitcore is a trademark maintained by BitPay, Inc. - [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/bitpay/bitcore/trend.png)](https://bitdeli.com/free "Bitdeli Badge") -