Merge branch 'master' into releases

CONTRIBUTING.md

@@ -43,31 +43,33 @@ Consistency on the way classes are used is paramount to allow an easier understa
 
 The design guidelines have quite a high abstraction level. These style guidelines are more concrete and easier to apply, and also more opinionated. The design guidelines mentioned above are the way we think about general software development and we believe they should be present in any software project.
 
-### G0 - General: Default to Felixge's Style Guide
+### General
+
+#### G0 - Default to Felixge's Style Guide
 
 Follow this Node.js Style Guide: https://github.com/felixge/node-style-guide#nodejs-style-guide
 
-### G1 - General: No Magic Numbers
+#### G1 - No Magic Numbers
 
 Avoid constants in the code as much as possible. Magic strings are also magic numbers.
 
-### G2 - General: Internal Objects should be Instances
+#### G2 - Internal Objects Should be Instances
 
 If a class has a `publicKey` member, for instance, that should be a `PublicKey` instance.
 
-### G3 - General: Internal amounts must be integers representing Satoshis
+#### G3 - Internal Amounts Must be Integers Representing Satoshis
 
 Avoid representation errors by always dealing with satoshis. For conversion for frontends, use the `Unit` class.
 
-### G4 - General: Internal network references must be Network instances
+#### G4 - Internal Network References Must be Network Instances
 
 A special case for [G2](#g2---general-internal-objects-should-be-instances) all network references must be `Network` instances (see `lib/network.js`), but when returned to the user, its `.name` property should be used.
 
-### G5 - General: Objects should display nicely in the console
+#### G5 - Objects Should Display Nicely in the Console
 
 Write a `.inspect()` method so an instance can be easily debugged in the console.
 
-### G6 - General: Naming Utility Namespaces
+#### G6 - Naming Utility Namespaces
 
 Name them in CamelCase, as they are namespaces.
 
@@ -80,7 +82,7 @@ DON'T:
 var bufferUtil = require('./util/buffer');
 ```
 
-### G7 - General: Standard Methods
+#### G7 - Standard Methods
 
 When possible, bitcore objects should have standard methods on an instance prototype:
 * `toObject` - A plain JavaScript object that can be JSON stringified
@@ -93,7 +95,9 @@ These should have a matching static method that can be used for instantiation:
 * `fromString` - Should be able to instantiate with output from `toString`
 * `fromBuffer` - Should likewise be able to instantiate from output from `toBuffer`
 
-### E1 - Errors: Use bitcore.Errors
+### Errors
+
+#### E1 - Use bitcore.Errors
 
 We've designed a structure for Errors to follow and are slowly migrating to it.
 
@@ -103,9 +107,11 @@ Usage:
 * Whenever a new class is created, add a generic error for that class in `lib/errors/spec.js`.
 * Specific errors for that class should subclass that error. Take a look at the structure in `lib/errors/spec.js`, it should be clear how subclasses are generated from that file.
 
-### E2 - Errors: Provide a `getValidationError` static method for classes
+#### E2 - Provide a `getValidationError` Static Method for Classes
+
+### Interface
 
-### I1 - Interface: Make Code that Fails Early
+#### I1 - Code that Fails Early
 
 In order to deal with JavaScript's weak typing and confusing errors, we ask our code to fail as soon as possible when an unexpected input was provided.
 
@@ -118,11 +124,11 @@ $.checkArgumentType(something, PrivateKey, 'something'); // The third argument i
 $.checkArgumentType(something, PrivateKey); // but it's optional (will show up as "(unknown argument)")
 ```
 
-### I2 - Interface: Permissive Constructors
+#### I2 - Permissive Constructors
 
 Most classes have static methods named `fromBuffer`, `fromString`, `fromJSON`. Whenever one of those methods is provided, the constructor for that class should also be able to detect the type of the arguments and call the appropriate method.
 
-### I3 - Interface: Method Chaining
+#### I3 - Method Chaining
 
 For classes that have a mutable state, most of the methods that can be chained *SHOULD* be chained, allowing for interfaces that read well, like:
 
@@ -134,7 +140,7 @@ var transaction = new Transaction()
     .sign(privkey);
 ```
 
-### I4 - Interface: Copy Constructors
+#### I4 - Copy Constructors
 
 Constructors, when provided an instance of the same class, should:
 * Return the same object, if the instances of this class are immutable
@@ -156,7 +162,7 @@ function ImmutableClass(arg) {
 }
 ```
 
-### I5 - Interface: No new keyword for Constructors
+#### I5 - No New Keyword for Constructors
 
 Constructors should not require to be called with `new`. This rule is not heavily enforced, but is a "nice to have".
 
@@ -169,17 +175,19 @@ function NoNewRequired(args) {
 }
 ```
 
-### T1 - Testing: Tests Must be Written Elegantly
+### Testing
+
+#### T1 - Tests Must be Written Elegantly
 
 Style guidelines are not relaxed for tests. Tests are a good way to show how to use the library, and maintaining them is extremely necessary.
 
 Don't write long tests, write helper functions to make them be as short and concise as possible (they should take just a few lines each), and use good variable names.
 
-### T2 - Testing: Tests Must not be Random
+#### T2 - Tests Must not be Random
 
 Inputs for tests should not be generated randomly. Also, the type and structure of outputs should be checked.
 
-### T3 - Testing: Require 'bitcore' and look up classes from there
+#### T3 - Require 'bitcore' and Look up Classes from There
 
 This helps to make tests more useful as examples, and more independent of where they are placed. This also helps prevent forgetting to include all submodules in the bitcore object.
 
@@ -193,6 +201,20 @@ DON'T:
 var PublicKey = require('../lib/publickey');
 ```
 
+#### T4 - Data for Tests Included in a JSON File
+
+If possible, data for tests should be included in a JSON file in the `test/data` directory. This improves interoperability with other libraries and keeps tests cleaner.
+
+### Documentation
+
+#### D1 - Guide and API Reference
+
+All modules should include a developer guide and API reference. The API reference documentation is generated using JSDOC. Each function that exposes a public API should include a description, @return and @param, as appropriate. The general documentation guide for the module should be located in the `docs/guide` directory and is written in GitHub Flavored Markdown.
+
+#### D2 - Proofread
+
+Please proofread documentation to avoid unintentional spelling and grammatical mistakes before submitting a pull request.
+
 ## Pull Request Workflow
 
 Our workflow is based on GitHub's pull requests. We use feature branches, prepended with: `test`, `feature`, `fix`, `refactor`, or `remove` according to the change the branch introduces. Some examples for such branches are:

README.md

@@ -32,7 +32,9 @@ simpleTx.sign(privateKey);
 
 The complete docs are hosted here: [bitcore documentation](http://bitcore.io/guide/). There's also a [bitcore API reference](http://bitcore.io/api/) available generated from the JSDocs of the project, where you'll find low-level details on each bitcore utility.
 
-[![Read the Developer Guide](http://bitpay.github.io/bitcore/images/read-the-developer-guide-btn.png)](http://bitcore.io/guide/)  [![Read the API Reference](http://bitpay.github.io/bitcore/images/read-the-api-reference-btn.png)](http://bitcore.io/api/)
+[Read the Developer Guide](http://bitcore.io/guide/)
+
+[Read the API Reference](http://bitcore.io/api/)
 
 To get community assistance and ask for help with implementation questions, please use our [community forums](http://bitpaylabs.com/c/bitcore).
 

bower.json

@@ -19,8 +19,12 @@
   "license": "MIT",
   "ignore": [
     "**/.*",
-    "node_modules",
-    "bower_components",
-    "tests"
+    "CONTRIBUTING.md",
+    "gulpfile.js",
+    "lib",
+    "index.js",
+    "karma.conf.js",
+    "npm-shrinkwrap.json",
+    "test"
   ]
 }

docs/guide/address.md

@@ -5,7 +5,7 @@ description: A simple interface to generate and validate a bitcoin address.
 
 ## Description
 
-Represents a bitcoin Address. Addresses are the most popular way to make bitcoin transactions. See [the official Bitcoin Wiki](https://en.bitcoin.it/wiki/Address) for technical background information.
+Represents a bitcoin address. Addresses are the most popular way to make bitcoin transactions. See [the official Bitcoin Wiki](https://en.bitcoin.it/wiki/Address) for technical background information.
 
 ## Instantiate an Address
 

docs/guide/block.md

@@ -5,14 +5,13 @@ description: A simple interface to parse and validate a bitcoin blocks.
 
 ## Description
 
-A Block instance represents the information of a block in the bitcoin network. Given a hexa or base64 string representation of the serialization of a block with its transactions, you can instantiate a Block instance. Methods are provided to calculate and check the merkle root hash (if enough data is provided), but transactions won't necessarily be valid spends, and this class won't validate them. A binary representation as a `Buffer` instance is also valid input for a Block's constructor. 
+A Block instance represents the information of a block in the bitcoin network. Given a hexadecimal string representation of the serialization of a block with its transactions, you can instantiate a Block instance. Methods are provided to calculate and check the merkle root hash (if enough data is provided), but transactions won't necessarily be valid spends, and this class won't validate them. A binary representation as a `Buffer` instance is also valid input for a Block's constructor. 
 
 ```javascript
-
 // instantiate a new block instance
 var block = new Block(hexaEncodedBlock);
 
-// will verify that the correspending block transactions match the header
+// will verify that the corresponding block transactions match the header
 assert(block.validMerkleRoot());
 
 // blocks have several properties
@@ -27,10 +26,9 @@ For detailed technical information about a block please visit [Blocks](https://e
 
 ## Block Header
 
-Each instance of Block has a BlockHeader *(which can be instantiated seperately)*. The header has validation methods, to verify that the block.
+Each instance of Block has a BlockHeader *(which can be instantiated separately)*. The header has validation methods, to verify that the block.
 
 ```javascript
-
 // will verify that the nonce demonstrates enough proof of work
 assert(block.header.validProofOfWork());
 

docs/guide/browser.md

@@ -0,0 +1,64 @@
+title: Browser Builds
+description: Guide to writing modules and optimizing browser bundles.
+---
+
+# Browser Builds
+
+When developing a module that will need to work in a browser and does not use the entire Bitcore namespace, it's recommended to narrow the scope of the requires to the particular modules that are needed. It will produce a smaller browser bundle as it will only include the JavaScript that is nessessary. Below is a quick tutorial that will use three modules.
+
+## Tutorial
+
+**Step 1**: Require Bitcore Modules
+
+Here we require specific Bitcore modules that will be used in a `index.js` file:
+
+```javascript
+
+var PrivateKey = require('bitcore/lib/privatekey');
+var PublicKey = require('bitcore/lib/publickey');
+var Address = require('bitcore/lib/address');
+
+// the rest of the module here
+
+```
+
+**Step 2**: Browserifying
+
+Next we will generate a browser bundle using [browserify](https://www.npmjs.com/package/browserify) by running the command:
+
+```bash
+browserify index.js -o index.browser.js
+```
+
+This will output a file `index.browser.js` at around 700KB *(the entire Bitcore namespace is around 2MB)*.
+
+**Step 3**: Uglifying
+
+This can be further optimized by using [uglifyjs](https://www.npmjs.com/package/uglify-js), and running the command:
+
+```bash
+uglifyjs index.browser.js --compress --mangle -o index.browser.min.js
+```
+
+The resulting file `index.browser.min.js` in this case should be less than 300KB.
+
+## Modules
+
+Here is a list of some of the common modules:
+
+```javascript
+var Address = require('bitcore/lib/address');
+var Block = require('bitcore/lib/block');
+var BlockHeader = require('bitcore/lib/blockheader');
+var HDPrivateKey = require('bitcore/lib/hdprivatekey');
+var HDPublicKey = require('bitcore/lib/hdpublickey');
+var PaymentProtocol = require('bitcore/lib/paymentprotocol');
+var PrivateKey = require('bitcore/lib/privatekey');
+var PublicKey = require('bitcore/lib/publickey');
+var Script = require('bitcore/lib/script');
+var Transaction = require('bitcore/lib/transaction');
+var URI = require('bitcore/lib/uri');
+var Unit = require('bitcore/lib/unit');
+```
+
+For more informatation about each of the modules please see the [Bitcore Documentation](index.md).

docs/guide/crypto.md

@@ -25,4 +25,4 @@ The `bitcore.Crypto.Hash` namespace contains a set of hashes and utilities. Thes
 
 ## ECDSA
 
-`bitcore.Crypto.ECDSA` contains a pure JavaScript implementation of the elliptic curve DSA signature scheme.
+`bitcore.Crypto.ECDSA` contains a pure JavaScript implementation of the elliptic curve DSA signature scheme based on [elliptic.js](https://github.com/indutny/elliptic).

docs/guide/ecies.md

@@ -9,7 +9,7 @@ Bitcore implements [Elliptic Curve Integrated Encryption Scheme (ECIES)](http://
 
 For more information refer to the [bitcore-ecies](https://github.com/bitpay/bitcore-ecies) github repo.
 
-## Instalation
+## Installation
 
 ECIES is implemented as a separate module and you must add it to your dependencies:
 

docs/guide/hierarchical.md

@@ -3,9 +3,9 @@ description: Lets you create and derive extended public and private keys accordi
 ---
 # HDKeys
 
-## Hierarichically Derived Keys
+## Hierarchically Derived Keys
 
-Bitcore provides full support for [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), allowing for many key management schemas that benefit from this property.  Please be sure to read and understand the basic concepts and the warnings on that BIP before using these classes.
+Bitcore provides full support for [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), allowing for many key management schemas that benefit from this property. Please be sure to read and understand the basic concepts and the warnings on that BIP before using these classes.
 
 ## HDPrivateKey
 

docs/guide/index.md

@@ -29,12 +29,16 @@ To get started, just `npm install bitcore` or `bower install bitcore`.
 * [Interface to the Bitcoin P2P network](peer.md)
 * [Managing a pool of peers](pool.md)
 * [Connecting to a bitcoind instance through JSON-RPC](jsonrpc.md)
+* [Connecting to a Insight instance to retrieve informetion](insight.md)
 
 ## Extra
 * [Crypto](crypto.md)
 * [Encoding](encoding.md)
 * [ECIES](ecies.md)
 
+## Module Development
+* [Browser Builds](browser.md)
+
 # Examples 
 
 ## Create a Private Key

docs/guide/insight.md

@@ -0,0 +1,36 @@
+title: Insight Explorer
+description: Provides an interface to fetch information about the state of the blockchain from a trusted Insight server.
+---
+# Insight
+
+## Description
+
+`bitcore.transport.explorers.Insight` is a simple agent to perform queries to an Insight blockchain explorer. The default servers are `https://insight.bitpay.com` and `https://test-insight.bitpay.com`, hosted by BitPay Inc. You can (and we strongly suggest you do) run your own insight server. For more information, head to https://github.com/bitpay/insight-api
+
+There are currently two methods implemented (the API will grow as features are requested): `getUnspentUtxos` and `broadcast`. 
+
+### Retrieving Unspent UTXOs for an Address (or set of)
+
+```javascript
+var insight = new Insight();
+insight.getUnspentUtxos('1Bitcoin...', function(err, utxos) {
+  if (err) {
+    // Handle errors...
+  } else {
+    // Maybe use the UTXOs to create a transaction
+  }
+});
+```
+
+### Broadcasting a Transaction
+
+```javascript
+var insight = new Insight();
+insight.broadcast(tx, function(err, returnedTxId) {
+  if (err) {
+    // Handle errors...
+  } else {
+    // Mark the transaction as broadcasted
+  }
+});
+```

docs/guide/networks.md

@@ -5,7 +5,7 @@ description: A simple interface to handle livenet and testnet bitcoin networks.
 
 ## Description
 
-Bitcore provides support for the main bitcoin network as well as for `testnet3`, the current test blockchain. We encourage the use of `Networks.livenet` and `Networks.testnet` as constants. Note that the library sometimes may check for equality against this object. Avoid creating a deep copy of this object and using that.
+Bitcore provides support for the main bitcoin network as well as for `testnet3`, the current test blockchain. We encourage the use of `Networks.livenet` and `Networks.testnet` as constants. Note that the library sometimes may check for equality against this object. Please avoid creating a deep copy of this object.
 
 The `Network` namespace has a function, `get(...)` that returns an instance of a `Network` or `undefined`. The only argument to this function is some kind of identifier of the network: either its name, a reference to a Network object, or a number used as a magic constant to identify the network (for example, the value `0` that gives bitcoin addresses the distinctive `'1'` at its beginning on livenet, is a `0x6F` for testnet).
 

docs/guide/paymentprotocol.md

@@ -100,7 +100,7 @@ var merchant_data = details.get('merchant_data');
 
 ## Send a Payment
 
-After the request is verified a payment can be sent to the merchant, from the customer's wallet:
+After the request is verified a payment can be sent to the merchant from the customer's wallet:
 
 ```javascript
 

docs/guide/peer.md

@@ -1,5 +1,5 @@
 title: Peer
-description: The Peer class privides a simple interface for connecting to a node in the bitcoin network.
+description: The Peer class provides a simple interface for connecting to a node in the bitcoin network.
 ---
 # Peer