From 7d015b1528518ff9029526cdb67f15cd7d11b284 Mon Sep 17 00:00:00 2001 From: Braydon Fuller Date: Fri, 19 Dec 2014 16:43:01 -0500 Subject: [PATCH 1/3] Proofread and fixed typos, etc. in contributing --- CONTRIBUTING.md | 125 +++++++++++++----------------------------------- 1 file changed, 34 insertions(+), 91 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6d5e07f0a..86077c7bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,7 @@ Contributing to Bitcore ======= -We're working hard to make *bitcore* the easier and most powerful javascript -library for working with bitcoin. Our goal is to have *bitcore* be a library -that can be used by anyone interested on bitcoin, and level the expertise -differences with a great design and documentation. - -We have a pretty strict set of guidelines for contributing. +We're working hard to make *bitcore* the easiest and most powerful javascript library for working with bitcoin. Our goal is to have *bitcore* be a library that can be used by anyone interested in bitcoin, and level the expertise differences with agreat design and documentation. ## Quick checklist @@ -18,83 +13,59 @@ Make sure: ## Design Guidelines -These are some global design goals in bitcore that any change must adhere to. +These are some global design goals in bitcore that any change must adhere. ### D1 - Naming Matters -We take our time with picking names. Code is going to be written once, and read -hundreds of times. +We take our time with picking names. Code is going to be written once, and read hundreds of times. -We were inspired to name this rule first due to Uncle Bob's great work *Clean -Code*, which has a whole chapter on this subject. +We were inspired to name this rule first due to Uncle Bob's great work *Clean Code*, which has a whole chapter on this subject. -In particular, you may notice that some names in this library are quite long -for the average javascript user. That's because we better have a long but -comprehensible name rather than an abbreviation that might confuse new users. +In particular, you may notice that some names in this library are quite long for the average JavaScript user. That's because we prefer a long but comprehensible name than an abbreviation that might confuse new users. ### D2 - Tests -Write a test for all your code. We encourage Test Driven Development so we know -when our code is right. We migrated from our original code base with a 80% test -coverage and are targeting 100% as we move towards our 1.0 release. +Write a test for all your code. We encourage Test Driven Development so we know when our code is right. We have increased test coverage from 80% to around 95% and are targeting 100% as we move towards our 1.0 release. ### D3 - Robustness Principle *Be conservative in what you send, be liberal in what you accept.* -Interfaces accept as much types of arguments as possible, so there's no mental -tax on using them: we want to avoid questions such as "should I use a string -here or a buffer?", "what happens if I'm not sure if the type of this variable -is an Address instance or a string with it encoded in base-58?" or "what kind -of object will I receive after calling this function?". +Interfaces should accept as many types of arguments as possible, so there's no mental tax on using them: we want to avoid questions such as "should I use a string here or a buffer?", "what happens if I'm not sure if the type of this variable is an Address instance or a string with it encoded in base-58?" or "what kind of object will I receive after calling this function?". -Accept a wide variety of usages and arguments, always return an internal kind -of object. For example, the class `PublicKey` can accept strings or buffers -with a DER encoded public key (either compressed or uncompressed), another -PublicKey, a PrivateKey, or a Point, an instance of the `elliptic.js` library -with the point in bitcoin's elliptic curve that represents the public key. +Accept a wide variety of use cases and arguments, always return an internal form of an object. For example, the class `PublicKey` can accept strings or buffers with a DER encoded public key (either compressed or uncompressed), another PublicKey, a PrivateKey, or a Point, an instance of the `elliptic.js` library with the point in bitcoin's elliptic curve that represents the public key. ### D4 - Consistency Everywhere -Consistency on the way classes are used is paramount to allow an easier -understanding of the library. +Consistency on the way classes are used is paramount to allow an easier understanding of the library. ## Style Guidelines -The design guidelines have quite a high abstraction level. These style -guidelines are easier to detect and 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 on any software project). +The design guidelines have quite a high abstraction level. These style guidelines are more concreate 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 +### G0 - General: Default to Felixge's Style Guide -Follow this Node.js style guide: https://github.com/felixge/node-style-guide#nodejs-style-guide +Follow this Node.js Style Guide: https://github.com/felixge/node-style-guide#nodejs-style-guide ### G1 - General: No Magic Numbers -Avoid constants in the code as much as possible. Magic strings are also magic -numbers. +Avoid constants in the code as much as possible. Magic strings are also magic numbers. ### G2 - General: Internal Objects should be Instances -If a class has a `publicKey` member, for instance, that should be a `PublicKey` -instance. +If a class has a `publicKey` member, for instance, that should be a `PublicKey` instance. ### G3 - General: Internal amounts must be integers representing Satoshis -Avoid representation errors by always dealing with satoshis. For conversion for -frontends, use the `Unit` class. +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 -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. +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 -Write a `.inspect()` method so an instance can be easily debugged in the -console. +Write a `.inspect()` method so an instance can be easily debugged in the console. ### G6 - General: Naming Utility Namespaces @@ -127,27 +98,18 @@ These should have a matching static method that can be used for instantiation: We've designed a structure for Errors to follow and are slowly migrating to it. Usage: -* Errors are generated in the file `lib/errors/index.js` by invoking `gulp - errors`. +* Errors are generated in the file `lib/errors/index.js` by invoking `gulp errors`. * The specification for errors is written in the `lib/errors/spec.js` file. -* 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 +* 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 ### I1 - Interface: Make 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. +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. -There's a module called `util/preconditions`, loosely based on -`preconditions.js`, based on `guava`, that we use for state and argument -checking. It should be trivial to use. We recommend using it on all methods, in -order to improve robustness and consistency. +There's a module called `util/preconditions`, loosely based on `preconditions.js`, based on `guava`, that we use for state and argument checking. It should be trivial to use. We recommend using it on all methods, in order to improve robustness and consistency. ```javascript $.checkState(something === anotherthing, 'Expected something to be anotherthing'); @@ -158,15 +120,11 @@ $.checkArgumentType(something, PrivateKey); // but it's optional (will show up a ### I2 - Interface: 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. +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 -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: +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: ```javascript var transaction = new Transaction() @@ -200,8 +158,7 @@ function ImmutableClass(arg) { ### I5 - Interface: 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". +Constructors should not require to be called with `new`. This rule is not heavily enforced, but is a "nice to have". ```javascript function NoNewRequired(args) { @@ -214,23 +171,17 @@ function NoNewRequired(args) { ### T1 - Testing: 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. +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. +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 -Inputs for tests should not be generated randomly. Also, the type and structure -of outputs should be checked. +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 -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. +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. DO: ```javascript @@ -244,9 +195,7 @@ var PublicKey = require('../lib/publickey'); ## 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: +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: ```sh git checkout -b test/some-module git checkout -b feature/some-new-stuff @@ -260,8 +209,7 @@ git remote add bitpay git@github.com:bitpay/bitcore.git git pull --rebase bitpay master ``` -Note that we require rebasing your branch instead of mergeing it, for commit -readability reasons. +Note that we require rebasing your branch instead of merging it, for commit readability reasons. After that, you can push the changes to your fork, by doing: ```sh @@ -269,14 +217,9 @@ git push origin your_branch_name git push origin feature/some-new-stuff git push origin fix/some-bug ``` -Finally go to [github.com/bitpay/bitcore](https://github.com/bitpay/bitcore) in -your web browser and issue a new pull request. +Finally go to [github.com/bitpay/bitcore](https://github.com/bitpay/bitcore) in your web browser and issue a new pull request. -Main contributors will review your code and possibly ask for changes before -your code is pulled in to the main repository. We'll check that all tests -pass, review the coding style, and check for general code correctness. If -everything is OK, we'll merge your pull request and your code will be part of -bitcore. +Main contributors will review your code and possibly ask for changes before your code is pulled in to the main repository. We'll check that all tests pass, review the coding style, and check for general code correctness. If everything is OK, we'll merge your pull request and your code will be part of bitcore. If you have any questions feel free to post them to [github.com/bitpay/bitcore/issues](https://github.com/bitpay/bitcore/issues). From 3e1ca2be42f5ba5ae75f5faf7153aad079fc4d93 Mon Sep 17 00:00:00 2001 From: Braydon Fuller Date: Fri, 19 Dec 2014 17:23:48 -0500 Subject: [PATCH 2/3] Proofread Documentation --- .gitignore | 1 + CONTRIBUTING.md | 6 ++--- README.md | 8 +++---- docs/{guide/examples.md => api/index.md} | 6 ++--- docs/guide/address.md | 10 ++++---- docs/guide/block.md | 4 ++-- docs/guide/crypto.md | 6 ++--- docs/guide/ecies.md | 4 ++-- docs/guide/encoding.md | 2 +- docs/guide/hierarchical.md | 2 +- docs/guide/index.md | 28 ---------------------- docs/guide/jsonrpc.md | 4 ++-- docs/guide/navigation.md | 30 ------------------------ docs/guide/networks.md | 8 +++---- docs/guide/paymentprotocol.md | 2 +- docs/guide/peer.md | 2 +- docs/guide/pool.md | 2 +- docs/guide/privatekey.md | 4 ++-- docs/guide/publickey.md | 2 +- docs/guide/script.md | 13 ++++------ docs/guide/transaction.md | 15 +++++------- docs/guide/unit.md | 6 ++--- docs/guide/uri.md | 6 ++--- 23 files changed, 53 insertions(+), 118 deletions(-) rename docs/{guide/examples.md => api/index.md} (92%) delete mode 100644 docs/guide/index.md delete mode 100644 docs/guide/navigation.md diff --git a/.gitignore b/.gitignore index f58ee8206..4ed7f3304 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ coverage node_modules browser/bitcore.js browser/tests.js +docs/api lib/errors/index.js diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 86077c7bd..d547cb3bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,9 @@ Contributing to Bitcore ======= -We're working hard to make *bitcore* the easiest and most powerful javascript library for working with bitcoin. Our goal is to have *bitcore* be a library that can be used by anyone interested in bitcoin, and level the expertise differences with agreat design and documentation. +We're working hard to make *bitcore* the most powerful JavaScript library for working with bitcoin. Our goal is to have *bitcore* be a library that can be used by anyone interested in bitcoin, and to level expertise differences with great design and documentation. -## Quick checklist +## Quick Checklist Make sure: @@ -41,7 +41,7 @@ Consistency on the way classes are used is paramount to allow an easier understa ## Style Guidelines -The design guidelines have quite a high abstraction level. These style guidelines are more concreate 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. +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 diff --git a/README.md b/README.md index eac10cabe..b74bfb1e2 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Bitcore [![Build Status](https://img.shields.io/travis/bitpay/bitcore.svg?branch=master&style=flat-square)](https://travis-ci.org/bitpay/bitcore) [![Coverage Status](https://img.shields.io/coveralls/bitpay/bitcore.svg?style=flat-square)](https://coveralls.io/r/bitpay/bitcore) -A pure and simple javascript bitcoin API. +A pure and simple JavaScript bitcoin API. ## Principles @@ -13,13 +13,11 @@ Bitcoin is a powerful new peer-to-peer platform for the next generation of finan ## Get Started -You can run bitcore on any javascript engine. It's distributed through npm, and you can also find compiled single files here: [bitcore.js](https://bitcore.io/bitcore/dist/bitcore.js) and [bitcore.min.js](https://bitcore.io/bitcore/dist/bitcore.min.js). - ``` npm install bitcore ``` -Using it on node.js: +Using it in Node.js: ```javascript var bitcore = require('bitcore'); @@ -46,7 +44,7 @@ Bitcore is still under heavy development and not quite ready for "drop-in" produ Please send pull requests for bug fixes, code optimization, and ideas for improvement. -## Building the browser bundle +## Building the Browser Bundle To build bitcore full bundle for the browser: diff --git a/docs/guide/examples.md b/docs/api/index.md similarity index 92% rename from docs/guide/examples.md rename to docs/api/index.md index e774f4b58..e5ea8b91a 100644 --- a/docs/guide/examples.md +++ b/docs/api/index.md @@ -1,6 +1,6 @@ # Examples -## Create a private key +## Create a Private Key ``` var privKey = new bitcore.PrivateKey(); @@ -27,7 +27,7 @@ var paymentInfo = { var uri = new bitcore.URI(paymentInfo).toString(); ``` -## Create a transaction +## Create a Transaction ``` var transaction = new Transaction() .from(utxos) // Feed information about what unspend outputs one can use @@ -36,7 +36,7 @@ var transaction = new Transaction() .sign(privkeySet) // Signs all the inputs it can ``` -## Connect to the network +## Connect to the Network ``` var peer = new Peer('5.9.85.34'); diff --git a/docs/guide/address.md b/docs/guide/address.md index 54cbc45f9..331311982 100644 --- a/docs/guide/address.md +++ b/docs/guide/address.md @@ -1,19 +1,19 @@ -# > `bitcore.Address` +# 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. +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 -To be able to receive bitcoins an address is needed, but in order to spend them a private key is necessary. Take a look at the [`PrivateKey`](PrivateKey.md) docs for more information about exporting and saving a key. +To be able to receive bitcoins an address is needed, but in order to spend them a private key is necessary. Please take a look at the [`PrivateKey`](PrivateKey.md) docs for more information about exporting and saving a key. ```javascript var privateKey = new PrivateKey(); var address = privateKey.toAddress(); ``` -You can also instantiate an address from a String, [PublicKey](PublicKey.md), or [HDPublicKey](Hierarchical.md), in case you are not the owner of the private key. +You can also instantiate an Address from a String, [PublicKey](PublicKey.md), or [HDPublicKey](Hierarchical.md), in case you are not the owner of the private key. ```javascript // from a string @@ -32,7 +32,7 @@ var address = new Address(publicKey, Networks.testnet); ## Validating an Address -The main use that we expect you'll have for the `Address` class in bitcore is validating that an address is a valid one, what type of address it is (you may be interested on knowing if the address is a simple "pay to public key hash" address or a "pay to script hash" address) and what network does the address belong to. +The main use that we expect you'll have for the `Address` class in Bitcore is validating that an address is a valid one, what type of address it is (you may be interested on knowing if the address is a simple "pay to public key hash" address or a "pay to script hash" address) and what network does the address belong to. The code to do these validations looks like this: diff --git a/docs/guide/block.md b/docs/guide/block.md index 148fb970f..5d4d18971 100644 --- a/docs/guide/block.md +++ b/docs/guide/block.md @@ -1,8 +1,8 @@ -# > `bitcore.Block` +# 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. +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. ```javascript diff --git a/docs/guide/crypto.md b/docs/guide/crypto.md index 8dee79c21..ac09d3281 100644 --- a/docs/guide/crypto.md +++ b/docs/guide/crypto.md @@ -1,4 +1,4 @@ -# > `bitcore.crypto` +# Crypto ## Description @@ -14,7 +14,7 @@ The `bitcore.Crypto.BN` class contains a wrapper around [bn.js](https://github.c ## 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. +The `bitcore.Crypto.Point` class contains a wrapper around the class Point of [elliptic.js](https://github.com/indutny/elliptic), the elliptic curve library used internally in bitcore. ## Hash @@ -22,4 +22,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. diff --git a/docs/guide/ecies.md b/docs/guide/ecies.md index ac0d497fa..da60a4022 100644 --- a/docs/guide/ecies.md +++ b/docs/guide/ecies.md @@ -1,8 +1,8 @@ -# > `bitcore-ecies` +# ECIES ## Description -Bitcore implements [Elliptic Curve Integrated Encryption Scheme (ECIES)](http://en.wikipedia.org/wiki/Integrated_Encryption_Scheme), which is a public key encryption system that performs bulk encryption on data usinc a symmetric cipher and a random key. +Bitcore implements [Elliptic Curve Integrated Encryption Scheme (ECIES)](http://en.wikipedia.org/wiki/Integrated_Encryption_Scheme), which is a public key encryption system that performs bulk encryption on data using a symmetric cipher and a random key. For more information refer to the [bitcore-ecies](https://github.com/bitpay/bitcore-ecies) github repo. diff --git a/docs/guide/encoding.md b/docs/guide/encoding.md index bb86d7854..3c21de1c6 100644 --- a/docs/guide/encoding.md +++ b/docs/guide/encoding.md @@ -1,4 +1,4 @@ -# > `bitcore.encoding` +# Encoding ## Description diff --git a/docs/guide/hierarchical.md b/docs/guide/hierarchical.md index 2c2a7de87..8a572fa2c 100644 --- a/docs/guide/hierarchical.md +++ b/docs/guide/hierarchical.md @@ -1,4 +1,4 @@ -# > `bitcore.HDKeys` +# HDKeys ## Hierarichically Derived Keys diff --git a/docs/guide/index.md b/docs/guide/index.md deleted file mode 100644 index 524671c02..000000000 --- a/docs/guide/index.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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) diff --git a/docs/guide/jsonrpc.md b/docs/guide/jsonrpc.md index 33a87d025..d5f11fbcb 100644 --- a/docs/guide/jsonrpc.md +++ b/docs/guide/jsonrpc.md @@ -1,8 +1,8 @@ -# > `bitcore.transport.RPC` +# JSON-RPC ## Description -Bitcoind provides a direct interface to the bitcoin network and it also exposes a `JSON-RPC` API. This class allows to connect to a local instance of a bitcoind server and make simple or batch RPC calls to it. +Bitcoind provides a direct interface to the bitcoin network and it also exposes a `JSON-RPC` API. This class will connect to a local instance of a bitcoind server and make simple or batch RPC calls to it. ## Connection to bitcoind diff --git a/docs/guide/navigation.md b/docs/guide/navigation.md deleted file mode 100644 index 88668397f..000000000 --- a/docs/guide/navigation.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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) diff --git a/docs/guide/networks.md b/docs/guide/networks.md index 3c66807c5..8598af27e 100644 --- a/docs/guide/networks.md +++ b/docs/guide/networks.md @@ -1,14 +1,14 @@ -# > `bitcore.Networks` +# 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. +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. 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). -## Setting the default network +## Setting the Default Network -Most project will only need to work in one of either networks. The value of `Networks.defaultNetwork` can be set to `Networks.testnet` if the project will needs only to work on testnet (the default is `Networks.livenet`). +Most projects will only need to work with one of the networks. The value of `Networks.defaultNetwork` can be set to `Networks.testnet` if the project will need to only to work on testnet (the default is `Networks.livenet`). ## Network constants diff --git a/docs/guide/paymentprotocol.md b/docs/guide/paymentprotocol.md index 79f184785..1b16acf61 100644 --- a/docs/guide/paymentprotocol.md +++ b/docs/guide/paymentprotocol.md @@ -1,4 +1,4 @@ -# > `bitcore.PaymentProtocol` +# Payment Protocol ## Description diff --git a/docs/guide/peer.md b/docs/guide/peer.md index b0f920194..5bb0278aa 100644 --- a/docs/guide/peer.md +++ b/docs/guide/peer.md @@ -1,4 +1,4 @@ -# > `bitcore.transport.Peer` +# Peer ## Description diff --git a/docs/guide/pool.md b/docs/guide/pool.md index 16221421e..93b733d20 100644 --- a/docs/guide/pool.md +++ b/docs/guide/pool.md @@ -1,4 +1,4 @@ -# > `bitcore.transport.Pool` +# Pool ## Pool diff --git a/docs/guide/privatekey.md b/docs/guide/privatekey.md index bf7b09627..d2ec5aa5a 100644 --- a/docs/guide/privatekey.md +++ b/docs/guide/privatekey.md @@ -1,4 +1,4 @@ -# > `bitcore.PrivateKey` +# Private Key ## Description @@ -6,7 +6,7 @@ Represents a bitcoin private key and is needed to be able to spend bitcoin and s ## Instantiate a Private Key -Here is how to create a new private key. It will generate a new random number using `window.crypto` or the Node.js 'crypto' library. +Here is how to create a new private key. It will generate a new random number using `window.crypto` or the Node.js `crypto` library. ```javascript var privateKey = new PrivateKey(); diff --git a/docs/guide/publickey.md b/docs/guide/publickey.md index 442e27c58..5557dcb16 100644 --- a/docs/guide/publickey.md +++ b/docs/guide/publickey.md @@ -1,4 +1,4 @@ -# > `bitcore.PublicKey` +# Public Key ## Description diff --git a/docs/guide/script.md b/docs/guide/script.md index 8149b63b5..c69192837 100644 --- a/docs/guide/script.md +++ b/docs/guide/script.md @@ -1,4 +1,4 @@ -# > `bitcore.Script` +# Script ## Description @@ -83,7 +83,7 @@ var script = Script.buildDataOut(data); assert(script.toString() === 'OP_RETURN 14 0x68656c6c6f20776f726c64212121' ``` -### Custom scripts +### Custom Scripts To create a custom `Script` instance, you must rely on the lower-level methods `add` and `prepend`. Both methods accept the same parameter types, and insert an opcode or data at the beginning (`prepend`) or end (`add`) of the `Script`. @@ -97,10 +97,9 @@ var script = Script() assert(script.toString() === 'OP_2SWAP OP_IF OP_NOT 4 0xbacacafe'); ``` +## Script Parsing and Identification -## Script parsing and identification - -`Script` has an easy interface to parse raw scripts from the newtwork or bitcoind, and to extract useful information. An illustrative example (for more options check the API reference) +`Script` has an easy interface to parse raw scripts from the network or bitcoind, and to extract useful information. An illustrative example (for more options check the API reference) ```javascript var raw_script = new Buffer('5221022df8750480ad5b26950b25c7ba79d3e37d75f640f8e5d9bcd5b150a0f85014da2103e3818b65bcc73a7d64064106a859cc1a5a728c4345ff0b641209fba0d90de6e921021f2f6e1e50cb6a953935c3601284925decd3fd21bc445712576873fb8c6ebc1853ae', 'hex'); @@ -113,8 +112,7 @@ s.isScriptHashOut() // false s.isMultisigOut() // true ``` - -## Script interpreting and validation +## Script Interpreting and Validation To validate a transaction, the bitcoin network validates all of its inputs and outputs. To validate an input, the input's script is concatenated with the referenced output script, and the result is executed. If at the end of execution the stack contains a 'true' value, then the transaction is valid. You can do this in `bitcore` by using the `Interpreter` class. The entry point (and probably the only interface you'll need for most applications) is the method `Interpreter#verify()`. @@ -147,4 +145,3 @@ var scriptSig = Script.buildPublicKeyHashIn(publicKey, signature); var flags = Interpreter.SCRIPT_VERIFY_P2SH | Interpreter.SCRIPT_VERIFY_STRICTENC; var verified = Interpreter().verify(scriptSig, scriptPubkey, tx, inputIndex, flags); ``` - diff --git a/docs/guide/transaction.md b/docs/guide/transaction.md index 3869bc3b7..82b6aee30 100644 --- a/docs/guide/transaction.md +++ b/docs/guide/transaction.md @@ -1,4 +1,4 @@ -# > `bitcore.Transaction` +# Transaction ## Description @@ -34,15 +34,13 @@ var transaction = new Transaction().fee(1e8); // Generous fee of 1 BTC ## Transaction API -You can take a look at the javadocs for the [Transaction class here](link missing). - ## Input -Transaction inputs are instances of either [Input](https://github.com/bitpay/bitcore/tree/master/lib/transaction/input) or its subclasses. The internal workings of it can be understood from the [API reference](link missing). +Transaction inputs are instances of either [Input](https://github.com/bitpay/bitcore/tree/master/lib/transaction/input) or its subclasses. ## Output -Transaction outputs are a very thin wrap around the information provided by a transaction output: its script and its output amount. +Transaction outputs are a very thin wrapper around the information provided by a transaction output: its script and its output amount. ## Multisig Transactions @@ -57,13 +55,12 @@ To send a transaction to a multisig address, the API is the same as in the above var serialized = multiSigTx.serialize(); ``` -This can be serialized and sent to another party, to complete with the needed -signatures: +This can be serialized and sent to another party, to complete with the needed signatures: ```javascript var multiSigTx = new Transaction(serialized) .from(utxo, publicKeys, threshold) // provide info about the multisig output - // (lost on serialization) + // (lost on serialization) .sign(anotherSetOfKeys); assert(multiSigTx.isFullySigned()); @@ -86,7 +83,7 @@ There are a number of data structures being stored internally in a `Transaction` If you have a larger set of unspent outputs, only some of them will be selected to fulfill the amount. This is done by storing a cache of unspent outputs in a protected member called `_utxos`. When the `to()` method is called, some of these outputs will be selected to pay the requested amount to the appropriate address. -A nit that you should have in mind is that when the transaction is serialized, this cache can't be included in the serialized form. +A detail that you should have in mind is that when the transaction is serialized, this cache can't be included in the serialized form. ## Upcoming changes diff --git a/docs/guide/unit.md b/docs/guide/unit.md index b6684d278..3a3344fdb 100644 --- a/docs/guide/unit.md +++ b/docs/guide/unit.md @@ -1,8 +1,8 @@ -# > `bitcore.Unit` +# 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. +Unit is an utility for handling and converting bitcoin units. We strongly recommend to always use satoshis to represent amount inside your application and only convert them to other units in the front-end. ## Supported units @@ -37,7 +37,7 @@ 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. +Once you have a unit instance, you can check its 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 var unit; diff --git a/docs/guide/uri.md b/docs/guide/uri.md index 719d51e42..0f431a18c 100644 --- a/docs/guide/uri.md +++ b/docs/guide/uri.md @@ -1,8 +1,8 @@ -# > `bitcore.URI` +# 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. +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. URI Examples: ``` @@ -24,7 +24,7 @@ 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. +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. From 3255cef96b8e8057ae8b873b3dc85d2f2a52b699 Mon Sep 17 00:00:00 2001 From: Braydon Fuller Date: Sun, 21 Dec 2014 10:21:11 -0500 Subject: [PATCH 3/3] Docs: Fix capitalization in links --- docs/guide/address.md | 4 ++-- docs/guide/block.md | 2 +- docs/guide/hierarchical.md | 2 +- docs/guide/pool.md | 4 ++-- docs/guide/publickey.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/guide/address.md b/docs/guide/address.md index 331311982..94225afe3 100644 --- a/docs/guide/address.md +++ b/docs/guide/address.md @@ -6,14 +6,14 @@ Represents a bitcoin Address. Addresses are the most popular way to make bitcoin ## Instantiate an Address -To be able to receive bitcoins an address is needed, but in order to spend them a private key is necessary. Please take a look at the [`PrivateKey`](PrivateKey.md) docs for more information about exporting and saving a key. +To be able to receive bitcoins an address is needed, but in order to spend them a private key is necessary. Please take a look at the [`PrivateKey`](privatekey.md) docs for more information about exporting and saving a key. ```javascript var privateKey = new PrivateKey(); var address = privateKey.toAddress(); ``` -You can also instantiate an Address from a String, [PublicKey](PublicKey.md), or [HDPublicKey](Hierarchical.md), in case you are not the owner of the private key. +You can also instantiate an Address from a String, [PublicKey](publickey.md), or [HDPublicKey](hierarchical.md), in case you are not the owner of the private key. ```javascript // from a string diff --git a/docs/guide/block.md b/docs/guide/block.md index 5d4d18971..2055202a1 100644 --- a/docs/guide/block.md +++ b/docs/guide/block.md @@ -47,7 +47,7 @@ For more information about the specific properties of a block header please visi ## Transactions -The set of transactions in a block is an array of instances of [Transaction](Transaction.md) and can be explored by iterating on the block's `transactions` member. +The set of transactions in a block is an array of instances of [Transaction](transaction.md) and can be explored by iterating on the block's `transactions` member. ```javascript for (var i in block.txs) { diff --git a/docs/guide/hierarchical.md b/docs/guide/hierarchical.md index 8a572fa2c..2806dfb80 100644 --- a/docs/guide/hierarchical.md +++ b/docs/guide/hierarchical.md @@ -6,7 +6,7 @@ Bitcore provides full support for [BIP32](https://github.com/bitcoin/bips/blob/m ## HDPrivateKey -An instance of a [PrivateKey](PrivateKey.md) that also contains information required to derive child keys. +An instance of a [PrivateKey](privatekey.md) that also contains information required to derive child keys. Sample usage: diff --git a/docs/guide/pool.md b/docs/guide/pool.md index 93b733d20..49ecd6798 100644 --- a/docs/guide/pool.md +++ b/docs/guide/pool.md @@ -2,7 +2,7 @@ ## 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. +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. The quickest way to get connected is to run the following: @@ -27,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. diff --git a/docs/guide/publickey.md b/docs/guide/publickey.md index 5557dcb16..b93063c49 100644 --- a/docs/guide/publickey.md +++ b/docs/guide/publickey.md @@ -2,7 +2,7 @@ ## 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). +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). ## Instantiate a Public Key