diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..efc9cae --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ + +[//]: # (This is partially derived from https://github.com/bitcoin/bitcoin/blob/6579d80572d2d33aceabbd3db45a6a9f809aa5e3/CONTRIBUTING.md) + +# Contributing to bitcoinjs-lib +Firstly in terms of structure, there is no particular concept of "bitcoinjs developers" in a sense of privileged people. +Open source revolves around a meritocracy where contributors who help gain trust from the community. + +For practical purpose, there are repository "maintainers" who are responsible for merging pull requests. + +We are always accepting of pull requests, but we do adhere to specific standards in regards to coding style, test driven development and commit messages. + + +## Communication Channels +GitHub is the preferred method of communication between members. + +Otherwise, in order of preference: +* bitcoinjs.slack.com +* #bitcoinjs-dev on Freenode IRC + + +## Workflow +The codebase is maintained using the "contributor workflow" where everyone without exception contributes patch proposals using "pull requests". +This facilitates social contribution, easy testing and peer review. + +To contribute a patch, the workflow is as follows: + + 1. Fork repository + 1. Create topic branch + 1. Commit patches + 1. Push changes to your fork + 1. Submit a pull request to https://github.com/bitcoinjs/bitcoinjs-lib + +[Commits should be atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention) and diffs easy to read. + +If your pull request is accepted for merging, you may be asked by a maintainer to squash and or [rebase](https://git-scm.com/docs/git-rebase) your commits before it is merged. + +Please refrain from creating several pull requests for the same change. + +Patchsets should be focused: + + * Adding a feature, or + * Fixing a bug, or + * Refactoring code. + +If you combine these, the PR may be rejected or asked to be split up. + +The length of time required for peer review is unpredictable and will vary from pull request to pull request. + +Refer to the [Git manual](https://git-scm.com/doc) for any information about `git`. + + +## We adhere to Bitcoin-Core policy +Bitcoin script payment/script templates are based on community consensus, but typically adhere to bitcoin-core node policy by default. + +- `bitcoinjs.script.decompile` is consensus bound only, it does not reject based on policy. +- `bitcoinjs.script.compile` will try to adhere to bitcoin-core `IsStandard` policies rules. (eg. minimalpush in https://github.com/bitcoinjs/bitcoinjs-lib/pull/638) + +Any elliptic curve `sign` operations should adhere to `IsStandard` policies, like `LOW_S`, but `verify` should not reject them [by default]. + +If you need non-standard rejecting `decoding`, you should use an external module, not this library. + +#### TLDR +Where "standards compliant" refers to the default policies of bitcoin-core, we adhere to the following: +- Any "creation" event must create standards-compliant data (standards bound) +- Any "validation" event must allow for non-standards compliant data (consensus bound) + +For stricter validation, use an external module which we [may have] provided. diff --git a/README.md b/README.md index 14faf3d..d2d500e 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,78 @@ # BitcoinJS (bitcoinjs-lib) [![Build Status](https://travis-ci.org/bitcoinjs/bitcoinjs-lib.png?branch=master)](https://travis-ci.org/bitcoinjs/bitcoinjs-lib) [![NPM](https://img.shields.io/npm/v/bitcoinjs-lib.svg)](https://www.npmjs.org/package/bitcoinjs-lib) -[![tip for next commit](https://tip4commit.com/projects/735.svg)](http://tip4commit.com/projects/735) [![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard) -The pure JavaScript Bitcoin library for node.js and browsers. -Estimated to be in use by over 15 million wallet users and is the backbone for almost all Bitcoin web wallets in production today. - - -## Features -- Clean: Pure JavaScript, concise code, easy to read. -- Tested: Coverage > 90%, third-party integration tests. -- Careful: Two person approval process for small, focused pull requests. -- Compatible: Works on Node.js and all modern browsers. -- Powerful: Support for advanced features, such as multi-sig, HD Wallets. -- Secure: Strong random number generation, PGP signed releases, trusted developers. -- Principled: No support for browsers with crap RNG (IE < 11) -- Standardized: Node community coding style, Browserify, Node's stdlib and Buffers. -- Fast: Optimized code, uses typed arrays instead of byte arrays for performance. -- Experiment-friendly: Bitcoin Mainnet and Testnet support. -- Altcoin-ready: Capable of working with bitcoin-derived cryptocurrencies (such as Dogecoin). +A javascript Bitcoin library for node.js and browsers. +Released under the terms of the [MIT LICENSE](LICENSE). ## Should I use this in production? -If you are thinking of using the master branch of this library in production, **stop**. +If you are thinking of using the *master* branch of this library in production, **stop**. Master is not stable; it is our development branch, and [only tagged releases may be classified as stable](https://github.com/bitcoinjs/bitcoinjs-lib/tags). +## Can I trust this code? +> Don't trust. Verify. + +We recommend every user of this library and the [bitcoinjs](https://github.com/bitcoinjs) ecosystem audit and verify any underlying code for its validity and suitability. + +Mistakes and bugs happen, but with your help in resolving and reporting [issues](https://github.com/bitcoinjs/bitcoinjs-lib/issues), together we can produce open source software that is: + +- Easy to audit and verify, +- Tested, with test coverage >95%, +- Advanced and feature rich, +- Standardized, using [standard](http://github.com/standard/standard) and Node `Buffer`'s throughout, and +- Friendly, with a strong and helpful community, ready to answer questions. + + ## Installation ``` bash npm install bitcoinjs-lib ``` -## Setup -### Node.js -``` javascript -var bitcoin = require('bitcoinjs-lib') -``` +Typically we support the [Node Maintenance LTS version](https://github.com/nodejs/Release). +If in doubt, see the [.travis.yml](.travis.yml) for what versions are used by our continuous integration tests. + +**WARNING**: We presently don't provide any tooling to verify that the release on `npm` matches GitHub. As such, you should verify anything downloaded by `npm` against your own verified copy. + + +## Usage ### Browser -If you're familiar with how to use browserify, ignore this and proceed normally. -These steps are advisory only, and may not be suitable for your application. +The recommended method of using `bitcoinjs-lib` in your browser is through [Browserify](https://github.com/substack/node-browserify). +If you're familiar with how to use browserify, ignore this and carry on, otherwise, it is recommended to read the tutorial at http://browserify.org/. -[Browserify](https://github.com/substack/node-browserify) is assumed to be installed for these steps. - -For your project, create an `index.js` file -``` javascript -let bitcoin = require('bitcoinjs-lib') - -// your code here -function myFunction () { - return bitcoin.ECPair.makeRandom().toWIF() -} - -module.exports = { - myFunction -} -``` - -Now, to compile for the browser: -``` bash -browserify index.js --standalone foo > app.js -``` - -You can now put `