From 048bad86fc40c2f2c32baf8e7df9f55ba80a7893 Mon Sep 17 00:00:00 2001 From: Yemel Jardi Date: Fri, 12 Dec 2014 16:26:33 -0300 Subject: [PATCH] Basic docs structure --- docs/config.json | 6 + docs/examples.md | 43 ++++++ docs/{ => helpers}/Crypto.md | 16 ++- docs/{ => helpers}/Encoding.md | 6 +- docs/{ => helpers}/Networks.md | 4 +- docs/{ => helpers}/URI.md | 11 +- docs/{ => helpers}/Unit.md | 12 +- docs/index.html | 212 ++++++++++++++++++++++++++++++ docs/index.md | 39 ++++++ docs/{ => models}/Address.md | 4 +- docs/{ => models}/Block.md | 4 +- docs/{ => models}/Hierarchical.md | 4 +- docs/{ => models}/Peer.md | 12 +- docs/{ => models}/PrivateKey.md | 4 +- docs/{ => models}/Script.md | 4 +- docs/{ => models}/Transaction.md | 4 +- docs/navigation.md | 22 ++++ 17 files changed, 386 insertions(+), 21 deletions(-) create mode 100644 docs/config.json create mode 100644 docs/examples.md rename docs/{ => helpers}/Crypto.md (88%) rename docs/{ => helpers}/Encoding.md (89%) rename docs/{ => helpers}/Networks.md (97%) rename docs/{ => helpers}/URI.md (84%) rename docs/{ => helpers}/Unit.md (87%) create mode 100644 docs/index.html create mode 100644 docs/index.md rename docs/{ => models}/Address.md (98%) rename docs/{ => models}/Block.md (98%) rename docs/{ => models}/Hierarchical.md (96%) rename docs/{ => models}/Peer.md (95%) rename docs/{ => models}/PrivateKey.md (97%) rename docs/{ => models}/Script.md (99%) rename docs/{ => models}/Transaction.md (99%) create mode 100644 docs/navigation.md diff --git a/docs/config.json b/docs/config.json new file mode 100644 index 0000000..76f478a --- /dev/null +++ b/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": "#" +} \ No newline at end of file diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..2e659c5 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,43 @@ +# 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 +``` +??? +``` + +## Request a Payment +``` +var paymentInfo = { + address: '1DNtTk4PUCGAdiNETAzQFWZiy2fCHtGnPx', + amount: 120000 //satoshis +}; +var uri = new bitcore.URI(paymentInfo).toString(); +``` + +## Create a transaction +``` +??? +``` + +## Connect to the network +``` +var peer = new Peer('5.9.85.34'); + +peer.on('inv', function(message) { + // new invetory +}); + +peer.connect(); +``` diff --git a/docs/Crypto.md b/docs/helpers/Crypto.md similarity index 88% rename from docs/Crypto.md rename to docs/helpers/Crypto.md index f1566f3..858e769 100644 --- a/docs/Crypto.md +++ b/docs/helpers/Crypto.md @@ -1,23 +1,25 @@ -# Crypto +# > `bitcore.crypto` + +## Description The cryptographic primitives (ECDSA and HMAC) implementations in this package have been audited bythe BitPay engineering team. More review and certifications are always welcomed. -## random +## Random -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). +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 +## 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. diff --git a/docs/Encoding.md b/docs/helpers/Encoding.md similarity index 89% rename from docs/Encoding.md rename to docs/helpers/Encoding.md index 932369b..bb86d78 100644 --- a/docs/Encoding.md +++ b/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. diff --git a/docs/Networks.md b/docs/helpers/Networks.md similarity index 97% rename from docs/Networks.md rename to docs/helpers/Networks.md index 59f053c..3c66807 100644 --- a/docs/Networks.md +++ b/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. diff --git a/docs/URI.md b/docs/helpers/URI.md similarity index 84% rename from docs/URI.md rename to docs/helpers/URI.md index 5bcc7f7..33c03a0 100644 --- a/docs/URI.md +++ b/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 usecase for the `URI` class is creating a bitcoin URI for sharing a payment request. That can be acomplished by using a dictionary to create an instance of URI. The code for creating an URI from an Object looks like this: ```javascript diff --git a/docs/Unit.md b/docs/helpers/Unit.md similarity index 87% rename from docs/Unit.md rename to docs/helpers/Unit.md index 2639148..05d4ea9 100644 --- a/docs/Unit.md +++ b/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,6 +16,8 @@ var bitsCode = Unit.bits; var satsCode = Unit.satoshis; ``` +## Creating units + 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: ```javascript @@ -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 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..c0b0f69 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,212 @@ + + + + + Bitcore | Core for your bitcoin projects + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..3aa9063 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,39 @@ +# Bitcore v0.8 + +## Description + +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. + +## Main Features + +* Cross platform +* All core bitcoin functionality +* Open-source +* Payment protocol support +* Private and public key management + + +## Get Started + +Use it on `Node.js`: + +``` +npm install bitcore +``` + +Use it client side on the browser: + +``` +bower install bitcore +``` + + +## Projects using Bitcore + +* Copay +* Insight +* enBitcoins +* BitBox +* Multi-signature Paper Wallet diff --git a/docs/Address.md b/docs/models/Address.md similarity index 98% rename from docs/Address.md rename to docs/models/Address.md index e5127ba..54cbc45 100644 --- a/docs/Address.md +++ b/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. diff --git a/docs/Block.md b/docs/models/Block.md similarity index 98% rename from docs/Block.md rename to docs/models/Block.md index cb786bf..148fb97 100644 --- a/docs/Block.md +++ b/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. diff --git a/docs/Hierarchical.md b/docs/models/Hierarchical.md similarity index 96% rename from docs/Hierarchical.md rename to docs/models/Hierarchical.md index 1f23f1a..2c2a7de 100644 --- a/docs/Hierarchical.md +++ b/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. diff --git a/docs/Peer.md b/docs/models/Peer.md similarity index 95% rename from docs/Peer.md rename to docs/models/Peer.md index 7bcbc39..b0f9201 100644 --- a/docs/Peer.md +++ b/docs/models/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: diff --git a/docs/PrivateKey.md b/docs/models/PrivateKey.md similarity index 97% rename from docs/PrivateKey.md rename to docs/models/PrivateKey.md index 4465ffa..bf7b096 100644 --- a/docs/PrivateKey.md +++ b/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). diff --git a/docs/Script.md b/docs/models/Script.md similarity index 99% rename from docs/Script.md rename to docs/models/Script.md index e26c978..8149b63 100644 --- a/docs/Script.md +++ b/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). diff --git a/docs/Transaction.md b/docs/models/Transaction.md similarity index 99% rename from docs/Transaction.md rename to docs/models/Transaction.md index bfc8cf6..b85cc24 100644 --- a/docs/Transaction.md +++ b/docs/models/Transaction.md @@ -1,4 +1,6 @@ -# Transaction +# > `bitcore.Transaction` + +## 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. What follows is a small introduction to transactions with some basic knowledge required to use this API. diff --git a/docs/navigation.md b/docs/navigation.md new file mode 100644 index 0000000..33325f2 --- /dev/null +++ b/docs/navigation.md @@ -0,0 +1,22 @@ +# Bitcore + +[About](index.md) +[Models]() + +* [Address](models/Address.md) +* [Block](models/Block.md) +* [Hierarchical](models/Hierarchical.md) +* [Peer](models/Peer.md) +* [Private Key](models/Privatekey.md) +* [Script](models/Script.md) +* [Transaction](models/Transaction.md) + +[Helpers]() + +* [Crypto](helpers/Crypto.md) +* [Encoding](helpers/Encoding.md) +* [Networks](helpers/Networks.md) +* [Unit](helpers/Unit.md) +* [URI](helpers/URI.md) + +[Examples](examples.md)