bigchaindb/bigchaindb
1
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-06-28 00:27:45 +02:00
Code Releases Activity

Merge pull request #75 from bigchaindb/assorted-docs-improvements

Browse Source 
Assorted docs improvements
This commit is contained in:
Troy McConaghy 2016-02-23 13:41:29 +01:00
commit d7145b04bf
6 changed files with 54 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
CONTRIBUTING.md
View File

@ -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)

4
docs/source/_templates/license-template.html Normal file
View File

@ -0,0 +1,4 @@
<h3>License</h3>
<p>
This documentation is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
</p>

3
docs/source/conf.py
View File

@ -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

45
docs/source/installing.md
View File

@ -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`).

4
docs/source/introduction.md
View File

@ -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.
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).

37
docs/source/models.md
View File

@ -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": "<ECDSA signature of the transaction>"
"signature": "<signature of the transaction>"
}
```
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": "<sha3 hash of the list of transactions + timestamp + nodes_pubkeys>",
"id": "<sha3 hash of the serialized block contents>",
"block": {
"timestamp": "<RethinkDB timestamp>",
"transactions": ["<list of transactions>"],
"node_pubkey": "<public key of the node creating the block>",
"voters": ["<list of federation nodes pulic keys>"]
"voters": ["<list of federation nodes public keys>"]
},
"signature": "<signature of the block>",
"votes": []
"votes": ["<list of 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": "<None|DOUBLE_SPEND|TRANSACTIONS_HASH_MISMATCH|NODES_PUBKEYS_MISMATCH",
"timestamp": "<timestamp of the voting action>"
},
"signature": "<ECDSA signature of vote block>"
"signature": "<signature of vote block>"
}
```
Note: The `invalid_reason` was not being used as of v0.1.3.