Merge pull request #798 from eordano/feature/docs

Update docs folder structure

docs/config.json

@@ -0,0 +1,6 @@
+{
+    "useSideMenu": true,
+    "lineBreaks": "gfm",
+    "additionalFooterText": "Bitcore™ © 2013-2014 BitPay, Inc. Bitcore is released under the MIT license. ",
+    "anchorCharacter": "#"
+}

docs/examples.md

@@ -0,0 +1,48 @@
+# Examples
+
+## Create a private key
+
+```
+var privKey = new bitcore.PrivateKey();
+```
+
+## Create an Address
+```
+var privKey = new bitcore.PrivateKey();
+var address = privKey.toAddress();
+```
+
+## Create a Multisig Address
+```
+// Build a 2-of-3 address from public keys
+var P2SHAddress = new bitcore.Address([publicKey1, publicKey2, publicKey3], 2);
+```
+
+## Request a Payment
+```
+var paymentInfo = {
+  address: '1DNtTk4PUCGAdiNETAzQFWZiy2fCHtGnPx',
+  amount: 120000 //satoshis
+};
+var uri = new bitcore.URI(paymentInfo).toString();
+```
+
+## Create a transaction
+```
+var transaction = new Transaction()
+    .from(utxos)          // Feed information about what unspend outputs one can use
+    .to(address, amount)  // Add an output with the given amount of satoshis
+    .change(address)      // Sets up a change address where the rest of the funds will go
+    .sign(privkeySet)     // Signs all the inputs it can
+```
+
+## Connect to the network
+```
+var peer = new Peer('5.9.85.34');
+
+peer.on('inv', function(message) {
+  // new invetory
+});
+
+peer.connect();
+```

docs/helpers/Crypto.md

@@ -1,23 +1,25 @@
-# Crypto
+# > `bitcore.crypto`
 
-The cryptographic primitives (ECDSA and HMAC) implementations in this package have been audited bythe BitPay engineering team. More review and certifications are always welcomed.
+## Description
 
-## random
+The cryptographic primitives (ECDSA and HMAC) implementations in this package have been reviewed by the BitPay engineering team. More audits and reviews are welcomed.
 
-The `bitcore.Crypto.Random` namespace contains a single function, named `getRandomBuffer(size)` that returns a `Buffer` instance with random bytes. It may not work depending on the engine that bitcore is running on (doesn't work with IE versions lesser than 11).
+## Random
 
-## bn
+The `bitcore.crypto.Random` namespace contains a single function, named `getRandomBuffer(size)` that returns a `Buffer` instance with random bytes. It may not work depending on the engine that bitcore is running on (doesn't work with IE versions lesser than 11).
+
+## BN
 
 The `bitcore.Crypto.BN` class contains a wrapper around [bn.js](https://github.com/indutny/bn.js), the bignum library used internally in bitcore.
 
-## point
+## Point
 
 The `bitcore.Crypto.Point` class contains a wrapper around the class Point of [elliptic.js](https://github.com/indutny/elliptic.js), the elliptic curve library used internally in bitcore.
 
-## hash
+## Hash
 
 The `bitcore.Crypto.Hash` namespace contains a set of hashes and utilities. These are either the native `crypto` hash functions from `node.js` or their respective browser shims as provided by the `browserify` library.
 
-## ecdsa
+## ECDSA
 
 `bitcore.Crypto.ECDSA` contains a pure javascript implementation of the elliptic curve DSA signature scheme. 

docs/helpers/Encoding.md

@@ -1,8 +1,10 @@
-# Encoding
+# > `bitcore.encoding`
+
+## Description
 
 The `bitcore.Encoding` namespace contains utilities for encoding information in common formats in the bitcoin ecosystem.
 
-## Base58
+## Base58 & Base58Check
 
 Two classes are provided: `Base58` and `Base58Check`. The first one merely encodes/decodes a set of bytes in base58 format. The second one will also take the double `sha256` hash of the information and append the last 4 bytes of the hash as a checksum when encoding, and check this checksum when decoding.
 

docs/helpers/Networks.md

@@ -1,4 +1,6 @@
-# Networks
+# > `bitcore.Networks`
+
+## Description
 
 Bitcore provides support for both 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.
 

docs/helpers/PaymentProtocol.md

@@ -1,3 +1,5 @@
+# > `bitcore.PaymentProtocol`
+
 # Payment Protocol
 
 `PaymentProtocol` and associated functions and methods will serialize, deserialize, sign and verify payment protocol messages both in Node.js and web browsers. Both X.509 and [bitcoin identity protocol](https://en.bitcoin.it/wiki/Identity_protocol_v1) are supported. For detailed technical information, please view [BIP70](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki).
@@ -176,4 +178,4 @@ var payment = new PaymentProtocol().makePayment(decodedPayment);
 var tx = payment.message.transactions[0];
 ```
 
-For detailed diagram of the exchange of messages, please see the [Protocol section of BIP70](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki#protocol).
+For detailed diagram of the exchange of messages, please see the [Protocol section of BIP70](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki#protocol).

docs/helpers/URI.md

@@ -1,4 +1,6 @@
-# URI
+# > `bitcore.URI`
+
+## Description
 
 Represents a bitcoin payment uri. Bitcoin URI strings became the most popular way to share payment request, sometimes as a bitcoin link and others using a QR code.
 
@@ -9,6 +11,8 @@ bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu?amount=1.2
 bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu?amount=1.2&message=Payment&label=Satoshi&extra=other-param
 ```
 
+## URI Validation
+
 The main use that we expect you'll have for the `URI` class in bitcore is validating and parsing bitcoin URIs. A `URI` instance exposes the address as a bitcore `Address` object and the amount in Satoshis, if present.
 
 The code for validating uris looks like this:
@@ -19,11 +23,14 @@ var uri = new URI(uriString);
 console.log(uri.address.network, uri.amount); // 'livenet', 120000000
 ```
 
+## URI Parameters
 All standard parameters can be found as members of the `URI` instance. However a bitcoin uri may contain other non-standard parameters, all those can be found under the `extra` namespace.
 
 See [the official BIP21 spec](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) for more information.
 
-Other usecase important usecase for the `URI` class is creating a bitcoin URI for sharing a payment request. That can be acomplished by using an Object to create an instance of URI.
+## Create URI
+
+Another important use case for the `URI` class is creating a bitcoin URI for sharing a payment request. That can be accomplished by using a dictionary to create an instance of URI.
 
 The code for creating an URI from an Object looks like this:
 ```javascript

docs/helpers/Unit.md

@@ -1,8 +1,12 @@
-# Unit
+# > `bitcore.Unit`
+
+## Description
 
 Unit is an utility for handling and converting bitcoins units. We strongly recommend you to always use satoshis to represent amount inside your application and only convert them to other units in the front-end.
 
-The supported units are BTC, mBTC, bits and satoshis. The codes for each unit can be found as members of the Unit class.
+## Supported units
+
+The supported units are BTC, mBTC, bits (micro BTCs, uBTC) and satoshis. The codes for each unit can be found as members of the Unit class.
 
 ```javascript
 var btcCode = Unit.BTC;
@@ -12,7 +16,9 @@ var bitsCode = Unit.bits;
 var satsCode = Unit.satoshis;
 ```
 
-There are two ways for creating a unit instance. You can instanciate the class using a value and a unit code; alternatively if the unit it's fixed you could you some of the static methods. Check some examples below:
+## Creating units
+
+There are two ways for creating a unit instance. You can instantiate the class using a value and a unit code; alternatively if the unit it's fixed you could you some of the static methods. Check some examples below:
 
 ```javascript
 var unit;
@@ -29,6 +35,8 @@ unit = Unit.fromBits(amount);
 unit = Unit.fromSatoshis(amount);
 ```
 
+## Conversion
+
 Once you have a unit instance, you can check it's representantion in all the available units. For your convinience the classes expose three ways to acomplish this. Using the `.to(unitCode)` method, using a fixed unit like `.toSatoshis()` or by using the accessors.
 
 ```javascript

docs/index.md

@@ -0,0 +1,28 @@
+# Bitcore v0.8
+
+## Addresses and Key Management
+
+* [Addresses](models/Address.md)
+* [Using different networks](helpers/Networks.md)
+* [Private Keys](models/PrivateKey.md) and [Public Keys](models/PublicKey.md)
+* [Hierarchically-derived Private and Public Keys](models/Hierarchical.md)
+
+## Payment handling
+* [Using different Units](helpers/Unit.md)
+* [Acknowledging and Requesting payments: Bitcoin URIs](helpers/URI.md)
+* [Payment Protocol Support](helpers/PaymentProtocol.md)
+* [The Transaction Class](models/Transaction.md)
+
+## Bitcoin internals
+* [Scripts](models/Script.md)
+* [Block](models/Block.md)
+
+## Networking
+* [Interface to the Bitcoin P2P network](networking/Peer.md)
+* [Managing a pool of peers](networking/Pool.md)
+* [Connecting to a bitcoind instance through JSON-RPC](networking/JSONRPC.md)
+
+## Extra
+* [Crypto](helpers/Crypto.md)
+* [Encoding](helpers/Encoding.md)
+* [ECIES](helpers/ECIES.md)

docs/models/Address.md

@@ -1,4 +1,6 @@
-# Address
+# > `bitcore.Address`
+
+## Description
 
 Represents a bitcoin Address. Addresses became the most popular way to make bitcoin transactions. See [the official Bitcoin Wiki](https://en.bitcoin.it/wiki/Address) for more information.
 

docs/models/Block.md

@@ -1,4 +1,6 @@
-# Block
+# > `bitcore.Block`
+
+## Description
 
 A Block instance represents the information on 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. 
 

docs/models/Hierarchical.md

@@ -1,4 +1,6 @@
-# Hierarichically Derived Keys
+# > `bitcore.HDKeys`
+
+## Hierarichically 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.
 

docs/models/PrivateKey.md

@@ -1,4 +1,6 @@
-# Private Key
+# > `bitcore.PrivateKey`
+
+## Description
 
 Represents a bitcoin private key and is needed to be able to spend bitcoin and sign transactions. See the official [Bitcoin Wiki](https://en.bitcoin.it/wiki/Private_key) for more information about private keys. A PrivateKey in Bitcore is an immutable object that has methods to import and export into a variety of formats including [Wallet Import Format](https://en.bitcoin.it/wiki/Wallet_import_format).
 

docs/models/PublicKey.md

@@ -1,4 +1,6 @@
-# Public Key
+# > `bitcore.PublicKey`
+
+## Description
 
 Represents a bitcoin public key and is needed to be able to receive bitcoin, as is usually represented as a bitcoin [Address](Address.md), see the official [Bitcoin Wiki](https://en.bitcoin.it/wiki/Technical_background_of_version_1_Bitcoin_addresses). A PublicKey in Bitcore is an immutable object and can be instantiated from a [Point](Crypto.md), string, [PrivateKey](PrivateKey.md), Buffer and a [BN](Crypto.md).
 
@@ -28,4 +30,4 @@ if (PublicKey.isValid('02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0
 }
 ```
 
-Note: It's important to note that there are two possible ways to represent public key, the standard is *compressed* and includes the x value and parity (as represented above in the documentation). There is also a longer version that is *uncompressed* which includes both x and y values, and using this can generate a different bitcoin address, so it's important to note this possibility, however it's discouraged to be used.
+Note: It's important to note that there are two possible ways to represent public key, the standard is *compressed* and includes the x value and parity (as represented above in the documentation). There is also a longer version that is *uncompressed* which includes both x and y values, and using this can generate a different bitcoin address, so it's important to note this possibility, however it's discouraged to be used.

docs/models/Script.md

@@ -1,4 +1,6 @@
-# Script
+# > `bitcore.Script`
+
+## Description
 
 All bitcoin transactions have scripts embedded into its inputs and outputs.  The scripts use a very simple programming language, which is evaluated from left to right using a stack. The language is designed such that it guarantees all scripts will execute in a limited amount of time (it is not Turing-Complete).
 

docs/models/Transaction.md

@@ -1,6 +1,8 @@
-# Transaction
+# > `bitcore.Transaction`
 
-Bitcore provides a very simple API for creating transactions. We expect this API to be accessible for developers without knowing the working internals of bitcoin in deep. What follows is a small introduction to transactions with some basic knowledge required to use this API.
+## Description
+
+Bitcore provides a very simple API for creating transactions. We expect this API to be accessible for developers without knowing the working internals of bitcoin in deep detail. What follows is a small introduction to transactions with some basic knowledge required to use this API.
 
 A Transaction contains a set of inputs and a set of outputs. Each input contains a reference to another transaction's output, and a signature that allows the value referenced in that ouput to be used in this transaction.
 

docs/navigation.md

@@ -0,0 +1,30 @@
+# Bitcore
+
+[Index](index.md)
+
+[Models]()
+
+* [Address](models/Address.md)
+* [Block](models/Block.md)
+* [Hierarchical](models/Hierarchical.md)
+* [Private Key](models/Privatekey.md)
+* [Public Key](models/Publickey.md)
+* [Script](models/Script.md)
+* [Transaction](models/Transaction.md)
+
+[Helpers]()
+
+* [Crypto](helpers/Crypto.md)
+* [Encoding](helpers/Encoding.md)
+* [Payment Protocol](helpers/PaymentProtocol.md)
+* [Networks](helpers/Networks.md)
+* [Unit](helpers/Unit.md)
+* [URI](helpers/URI.md)
+
+[Networking]()
+
+* [Peer](networking/Peer.md)
+* [Pool](networking/Pool.md)
+* [JSON-RPC](networking/JSONRPC.md)
+
+[Examples](examples.md)

docs/networking/Peer.md

@@ -1,7 +1,11 @@
-# Peer
+# > `bitcore.transport.Peer`
+
+## Description
 
 Represents a node from the p2p bitcoin network. The Peer class supports connecting directly to other nodes or through a socks5 proxy like Tor.
 
+## Creating a peer
+
 The code to create a new peer looks like this:
 
 ```javascript
@@ -20,6 +24,8 @@ var testnetPeer = new Peer('5.9.85.34', 18334, bitcore.testnet);
 var peer = new Peer('5.9.85.34').setProxy('localhost', 9050);
 ```
 
+## States
+
 A peer instance is always in one of the following states:
 
 * `disconnected`: No connection with the remote node.
@@ -47,6 +53,8 @@ peer.on('disconnect', function() {
 peer.connect();
 ```
 
+## Handle messages
+
 Once connected, a peer instance can send and receive messages. Every time a message arrives it's emitted as a new event. Let's see an example of this:
 
 ```javascript
@@ -69,6 +77,8 @@ peer.on('addr', function(message) {
 peer.connect();
 ```
 
+## Sending messages
+
 In order to send messages the Peer class offers the `sendMessage(message)` method, which receives an instance of a message. All supported messages can be found on the `bitcore.transport.Messages` module. For more information about messages refer to the [protocol specification](https://en.bitcoin.it/wiki/Protocol_specification).
 
 An example for requesting other connected nodes to a peers looks like this:

docs/networking/Pool.md

@@ -1,4 +1,6 @@
-# Pool
+# > `bitcore.transport.Pool`
+
+## Pool
 
 A pool maintains a connection of [Peers](Peer.md). A pool will discover peers via DNS seeds, as well as when peer addresses are announced through the network.
 
@@ -25,4 +27,4 @@ pool.disconnect()
 
 ```
 
-For more information about Peer events, please read the [Peer](Peer.md) documentation. Peer events are relayed to the pool, a peer event `inv` in the pool would be `peerinv`. When a peer is disconnected the pool will try to connect to the list of known addresses to maintain connection.
+For more information about Peer events, please read the [Peer](Peer.md) documentation. Peer events are relayed to the pool, a peer event `inv` in the pool would be `peerinv`. When a peer is disconnected the pool will try to connect to the list of known addresses to maintain connection.

lib/transaction/transaction.js

@@ -520,7 +520,7 @@ Transaction.prototype.sign = function(privateKey, sigtype) {
   return this;
 };
 
-Transaction.prototype._getPrivateKeySignatures = function(privKey, sigtype) {
+Transaction.prototype.getSignatures = function(privKey, sigtype) {
   privKey = new PrivateKey(privKey);
   sigtype = sigtype || Signature.SIGHASH_ALL;
   var transaction = this;
@@ -549,10 +549,6 @@ Transaction.prototype.applySignature = function(signature) {
   return this;
 };
 
-Transaction.prototype.getSignatures = function(privKey, sigtype) {
-  return this._getPrivateKeySignatures(privKey, sigtype);
-};
-
 Transaction.prototype.isFullySigned = function() {
   return _.all(_.map(this.inputs, function(input) {
     return input.isFullySigned();
@@ -571,7 +567,6 @@ Transaction.prototype.verifySignature = function(sig, pubkey, nin, subscript) {
   return Sighash.verify(this, sig, pubkey, nin, subscript);
 };
 
-
 /**
  * Check that a transaction passes basic sanity tests. If not, return a string
  * describing the error. This function contains the same logic as