diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a76edac2..c0975b0c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,11 +4,11 @@ There are many ways you can contribute to the BigchainDB project, some very easy ## Easy Ways to Contribute -The BigchainDB community has a Google Group and a Slack chat. Our [Community page](https://www.bigchaindb.com/community) has more information about those. +The BigchainDB community has a Google Group and a Gitter chatroom. Our [Community page](https://www.bigchaindb.com/community) has more information about those. -You can also follow us on Twitter [@BigchainDB](https://twitter.com/BigchainDB). +You can also follow us on Twitter [@BigchainDB](https://twitter.com/BigchainDB) or read [our blog on Medium](https://medium.com/the-bigchaindb-blog). -If you want to file a bug report, suggest a feature, or ask a code-related question, please go to the `BigchainDB/bigchaindb` repository on GitHub and [create a new Issue](https://github.com/bigchaindb/bigchaindb/issues/new). (You will need a [GitHub account](https://github.com/signup/free) (free).) Please describe the issue clearly, including steps to reproduce when it is a bug. +If you want to file a bug report, suggest a feature, or ask a code-related question, please go to the `bigchaindb/bigchaindb` repository on GitHub and [create a new Issue](https://github.com/bigchaindb/bigchaindb/issues/new). (You will need a [GitHub account](https://github.com/signup/free) (free).) Please describe the issue clearly, including steps to reproduce when it is a bug. ## How to Contribute Code or Documentation @@ -26,6 +26,8 @@ Familiarize yourself with how we do coding and documentation in the BigchainDB p * Note that we call the main branch `develop` rather than `master` * [semantic versioning](http://semver.org/) +Note: We have a slight variation on the GitHub Flow: we call the default branch `develop` rather than `master`. + ### Step 1 - Fork bigchaindb on GitHub In your web browser, go to [the BigchainDB repository on GitHub](https://github.com/bigchaindb/bigchaindb) and click the `Fork` button in the top right corner. This creates a new Git repository named `bigchaindb` in _your_ GitHub account. @@ -36,7 +38,7 @@ In your web browser, go to [the BigchainDB repository on GitHub](https://github. ```text git clone git@github.com:your-github-username/bigchaindb.git cd bigchaindb -git add upstream git@github.com:BigchainDB/bigchaindb.git +git add upstream git@github.com:bigchaindb/bigchaindb.git ``` ### Step 3 - Fetch and Merge the Latest from `upstream/develop` @@ -93,7 +95,7 @@ git push origin new-branch-name Go to the GitHub website and to _your_ remote bigchaindb repository (i.e. something like https://github.com/your-user-name/bigchaindb). -See [GitHub's documentation on how to initiate and send a pull request](https://help.github.com/articles/using-pull-requests/). Note that the destination repository should be `BigchainDB/bigchaindb` and the destination branch will be `develop` (usually, and if it's not, then we can change that if necessary). +See [GitHub's documentation on how to initiate and send a pull request](https://help.github.com/articles/using-pull-requests/). Note that the destination repository should be `bigchaindb/bigchaindb` and the destination branch will be `develop` (usually, and if it's not, then we can change that if necessary). If this is the first time you've submitted a pull request to BigchainDB, then you must read and accept the Contributor License Agreement (CLA) before we can merge your contributions. That can be found at [https://www.bigchaindb.com/cla](https://www.bigchaindb.com/cla). @@ -103,7 +105,7 @@ Someone will then merge your branch or suggest changes. If we suggsest changes, ## Quick Links -* [BigchainDB Community links](https://www.bigchaindb.com/community) (e.g. mailing list, Slack) +* [BigchainDB Community links](https://www.bigchaindb.com/community) * [General GitHub Documentation](https://help.github.com/) * [Code of Conduct](./CODE_OF_CONDUCT.md) * [BigchainDB Licenses](./LICENSES.md) diff --git a/docs/source/_templates/license-template.html b/docs/source/_templates/license-template.html new file mode 100644 index 00000000..758cbb79 --- /dev/null +++ b/docs/source/_templates/license-template.html @@ -0,0 +1,4 @@ +

License

+

+This documentation is licensed under a Creative Commons Attribution 4.0 International License. +

\ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 4bdfa812..3651eb79 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -168,7 +168,8 @@ html_sidebars = { '**': ['sidebar-title-template.html', 'globaltoc.html', 'sidebar-links-template.html', - 'searchbox.html'], + 'searchbox.html', + 'license-template.html'], } # Additional templates that should be rendered to pages, maps page names to diff --git a/docs/source/installing.md b/docs/source/installing.md index 24053f47..ff51539c 100644 --- a/docs/source/installing.md +++ b/docs/source/installing.md @@ -47,6 +47,8 @@ sudo pip install bigchaindb ``` (or maybe `sudo pip3 install bigchaindb` or `sudo pip3.4 install bigchaindb`. The `sudo` may not be necessary.) +Note: You can use `pip` to upgrade bigchaindb to the latest version using `sudo pip install --upgrade bigchaindb` + ### How to Install BigchainDB from Source BigchainDB is in its early stages and being actively developed on its [GitHub repository](https://github.com/bigchaindb/bigchaindb). Contributions are highly appreciated. @@ -86,58 +88,51 @@ During its first run, BigchainDB takes care of configuring a single node environ **NOT for Production Use** For those who like using Docker and wish to experiment with BigchainDB in -non-production environments, we currently maintain a `Dockerfile` that can be +non-production environments, we currently maintain a `dockerfile` that can be used to build an image for `bigchaindb`, along with a `docker-compose.yml` file to manage a "standalone node", consisting mainly of two containers: one for -rethinkdb, and another for `bigchaindb`. +RethinkDB, and another for `bigchaindb`. Assuming you have `docker` and `docker-compose` installed, you would proceed as follows. In a terminal shell: - -```bash +```text $ git clone git@github.com:bigchaindb/bigchaindb.git ``` -Build the docker image - -```bash +Build the Docker image: +```text $ docker-compose build ``` -then, a one-time configuration step, to create the config file, which will be -stored on your host machine under ` ~/.bigchaindb_docker/config` - -```bash +then do a one-time configuration step to create the config file; it will be +stored on your host machine under ` ~/.bigchaindb_docker/config`: +```text $ docker-compose run --rm bigchaindb bigchaindb configure ``` -you can load test transactions via - -```bash +You can load test transactions via: +```text $ docker-compose run --rm bigchaindb bigchaindb-benchmark load ``` -you should then be able to start `bigchaindb`, via - -```bash +You should then be able to start `bigchaindb`, via: +```text $ docker-compose run --rm bigchaindb bigchaindb start ``` or - -```bash +```text $ docker-compose up ``` -You should be able to view the rethinkdb dashboard at - -``` +You should be able to view the RethinkDB dashboard at: +```text http://docker_host:58080/ ``` -where `docker_host` is the ip or hostname of the machine running the docker -engine. If you are developing on linux this most likely will be `localhost`, +where `docker_host` is the IP or hostname of the machine running the Docker +engine. If you are developing on Linux, this most likely will be `localhost`, whereas if you are running docker-machine (e.g.: on Mac OS X) this will be the -ip of the docher machine (`docker-machine ip machine_name`). +IP of the Docker machine (`docker-machine ip machine_name`). diff --git a/docs/source/introduction.md b/docs/source/introduction.md index 56ec1e07..e3f5ad75 100644 --- a/docs/source/introduction.md +++ b/docs/source/introduction.md @@ -8,4 +8,6 @@ BigchainDB is a scalable blockchain database. You can read about its motivations Right now, BigchainDB is fairly new, so there are no live, operational BigchainDB clusters. There are no BigchainDB drivers. Those things are coming. -What does exist is our in-development BigchainDB server software. Therefore all the documentation is about that, for now. \ No newline at end of file +What does exist is our in-development BigchainDB server software. Therefore all the documentation is about that, for now. + +If you're curious about what's coming in our roadmap, see [the ROADMAP.md file](https://github.com/bigchaindb/bigchaindb/blob/develop/ROADMAP.md) and [the list of open issues](https://github.com/bigchaindb/bigchaindb/issues). If you want to request a feature or file a bug report, see [the CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/develop/CONTRIBUTING.md). \ No newline at end of file diff --git a/docs/source/models.md b/docs/source/models.md index c239cfc8..267a1a84 100644 --- a/docs/source/models.md +++ b/docs/source/models.md @@ -1,6 +1,6 @@ # The Transaction, Block and Vote Models -Transactions, blocks and votes are represented using JSON documents with the following models (schemas). +Transactions, blocks and votes are represented using JSON documents with the following models (schemas). See [the section on cryptography](cryptography.html) for more information about how we calculate hashes and signatures. ## The Transaction Model @@ -22,64 +22,59 @@ Transactions, blocks and votes are represented using JSON documents with the fol } } }, - "signature": "" + "signature": "" } ``` A transaction is an operation between the `current_owner` and the `new_owner` over the digital content described by `hash`. For example if could be a transfer of ownership of the digital content `hash` -- `id`: sha3 hash of the transaction and rethinkdb primary key. By using the hash of the transaction of the -primary key we eliminate the problem of duplicated transactions, if for some reason two nodes decide to create the -same transaction +- `id`: sha3 hash of the transaction. Also the RethinkDB primary key. By using the hash of the transaction as the primary key, we eliminate the problem of duplicated transactions, if for some reason two nodes decide to create the same transaction - `current_owner`: Public key of the current owner of the digital content with hash `hash` - `new_owner`: Public key of the new owner of the digital content with hash `hash` -- `input`: sha3 hash of the transaction in which the content was transfered to the user (similar to input in -the blockchain). Right now we will assume that there is only one input per transaction to simplify the prototype. -This can be changed in the future to allow multiple inputs per transaction. +- `input`: id (sha3 hash) of the transaction in which the content was transfered to the user (similar to input in the blockchain). Right now we will assume that there is only one input per transaction to simplify the prototype. This can be changed in the future to allow multiple inputs per transaction. - `operation`: String representation of the operation being performed (REGISTER, TRANSFER, ...) this will define how the transactions should be validated - `timestamp`: Time of creation of the transaction in UTC - `data`: JSON object describing the asset (digital content). It contains at least the field `hash` which is a sha3 hash of the digital content. -- `signature`: ECDSA signature of the transaction with the `current_owner` private key +- `signature`: Signature of the transaction with the `current_owner` private key ## The Block Model ```json { - "id": "", + "id": "", "block": { "timestamp": "", "transactions": [""], "node_pubkey": "", - "voters": [""] + "voters": [""] }, "signature": "", - "votes": [] + "votes": [""] } ``` Still to be defined when new blocks are created (after x number of transactions, or after x amount of seconds, or both). + A block contains a group of transactions and includes the hash of the hash of the previous block to build the chain. -- `id`: sha3 hash of the current block. This is also a RethinkDB primary key, this way we make sure that all blocks are unique. +- `id`: sha3 hash of the contents of `block` (i.e. the timestamp, list of transactions, node_pubkey, and voters). This is also a RethinkDB primary key; that's how we ensure that all blocks are unique. - `block`: The actual block - `timestamp`: timestamp when the block was created - `transactions`: the list of transactions included in the block - `node_pubkey`: the public key of the node that create the block - - `voters`: list public keys of the federation nodes. Since the size of the + - `voters`: list public keys of the federation nodes. Since the size of the federation may change over time this will tell us how many nodes existed in the federation when the block was created so that in a later point in time we can check that the block received the correct number of votes. -- `signature`: Signature of the block by the node that created the block -- `votes`: Initially an empty list. Nodes in the voters list will append to it - has they vote on the block - +- `signature`: Signature of the block by the node that created the block (i.e. To create it, the node serialized the block contents and signed that with its private key) +- `votes`: Initially an empty list. New votes are appended as they come in from the nodes. ## The Vote Model -This is the structure that each node will append to the block `votes` list. +Each node must generate a vote for each block, to be appended to that block's `votes` list. A vote has the following structure: ```json { @@ -91,6 +86,8 @@ This is the structure that each node will append to the block `votes` list. "invalid_reason": "" }, - "signature": "" + "signature": "" } ``` + +Note: The `invalid_reason` was not being used as of v0.1.3.