diff --git a/README.md b/README.md index 0fd70ad9..e72a55a8 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,10 @@ A scalable blockchain database. [The whitepaper](https://www.bigchaindb.com/whit ## Quick Start -### [Install & Run BigchainDB](http://bigchaindb.readthedocs.org/en/develop/installing.html) -### [Run BigchainDB with Docker](http://bigchaindb.readthedocs.org/en/develop/installing.html#run-bigchaindb-with-docker) -### [Getting Started (Tutorial)](http://bigchaindb.readthedocs.org/en/develop/getting-started.html) +### [Install and Run BigchainDB Server](http://bigchaindb.readthedocs.org/en/develop/installing-server.html) +### [Run BigchainDB with Docker](http://bigchaindb.readthedocs.org/en/develop/installing-server.html#run-bigchaindb-with-docker) +### [The Python Server API by Example](http://bigchaindb.readthedocs.org/en/develop/python-server-api-examples.html) +### [The Python Driver API by Example](http://bigchaindb.readthedocs.org/en/develop/python-driver-api-examples.html) ## Links for Everyone * [BigchainDB.com](https://www.bigchaindb.com/) - the main BigchainDB website, including newsletter signup diff --git a/ROADMAP.md b/ROADMAP.md index 89ea0971..79fadf02 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,13 +1,26 @@ # BigchainDB Roadmap +See also: + +* [Milestones](https://github.com/bigchaindb/bigchaindb/milestones) (i.e. issues to be closed before various releases) +* [Open issues](https://github.com/bigchaindb/bigchaindb/issues) and [open pull requests](https://github.com/bigchaindb/bigchaindb/pulls) + ## BigchainDB Protocols * Validation of other nodes * Fault tolerance * Permissions framework * Protocol audits including security audits +## HTTP Client-Server API +* Validate the structure of the transaction +* Return the correct error code if something goes wrong +* Add an endpoint to query unspents for a given public key +* More endpoints +* See [the relevant open issues](https://github.com/bigchaindb/bigchaindb/issues?q=is%3Aissue+is%3Aopen+label%3Arest-api) + ## Implementation/Code * Node validation framework (inspect and agree or not with what the other nodes are doing) +* Open public testing cluster (for people to try out a BigchainDB cluster and to test client software) * Federation management tools * More tools for benchmarking a cluster * Descriptions and results of more benchmarking tests diff --git a/docs/source/admin.md b/docs/source/admin.md index 0c4b406b..4745ee41 100644 --- a/docs/source/admin.md +++ b/docs/source/admin.md @@ -9,7 +9,7 @@ This section covers everything which might concern a BigchainDB server/cluster a ## Deploying a local cluster One of the advantages of RethinkDB as the storage backend is the easy installation. Developers like to have everything locally, so let's install a local storage backend cluster from scratch. -Here is an example to run a cluster assuming rethinkdb is already [installed](installing.html#installing-and-running-rethinkdb-server-on-ubuntu-12-04) in +Here is an example to run a cluster assuming rethinkdb is already [installed](installing-server.html#installing-and-running-rethinkdb-server-on-ubuntu-12-04) in your system: # preparing two additional nodes diff --git a/docs/source/faq.md b/docs/source/faq.md deleted file mode 100644 index 82d04f72..00000000 --- a/docs/source/faq.md +++ /dev/null @@ -1,2 +0,0 @@ -# Frequently Asked Questions (FAQ) -coming soon... diff --git a/docs/source/http-client-server-api.md b/docs/source/http-client-server-api.md new file mode 100644 index 00000000..367fd440 --- /dev/null +++ b/docs/source/http-client-server-api.md @@ -0,0 +1,5 @@ +# The HTTP Client-Server API + +The preferred way to communicate with a node in a BigchainDB cluster is via HTTP requests. Each node exposes a simple HTTP API (the HTTP Client-Server API) that provides, right now, two endpoints, one to get information about a specific transaction id, and one to push a transaction to the BigchainDB cluster. + +The endpoints are documented using [Apiary](http://docs.bigchaindb.apiary.io/). diff --git a/docs/source/index.rst b/docs/source/index.rst index 837b24f2..44523c7d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,10 +13,11 @@ Table of Contents :numbered: introduction - installing - getting-started + installing-server + python-server-api-examples bigchaindb-cli - python-api-tutorial + http-client-server-api + python-driver-api-examples admin cryptography models @@ -25,7 +26,6 @@ Table of Contents monitoring licenses contributing - faq release-notes glossary diff --git a/docs/source/installing.md b/docs/source/installing-server.md similarity index 58% rename from docs/source/installing.md rename to docs/source/installing-server.md index 3e38013f..18c62d1e 100644 --- a/docs/source/installing.md +++ b/docs/source/installing-server.md @@ -1,18 +1,19 @@ -# Installing BigchainDB Server +# Installing and Running BigchainDB Server -We're developing BigchainDB Server ("BigchainDB") on Ubuntu 14.04, but it should work on any OS that runs RethinkDB Server and Python 3.4+. (BigchainDB is built on top of RethinkDB Server.) +We're developing BigchainDB Server on Ubuntu 14.04, but it should work on any OS that runs RethinkDB Server and Python 3.4+. (BigchainDB Server is built on top of RethinkDB Server.) BigchainDB Server is intended to be run on each server in a large distributed cluster of servers; it's not very useful running by itself on a single computer. That's _why_ we're developing it on Ubuntu 14.04: it's one of the more common server operating systems. -Mac OS X users may get the best results [running BigchainDB Server with Docker](https://bigchaindb.readthedocs.org/en/develop/installing.html#run-bigchaindb-with-docker). +Mac OS X users may get the best results [running BigchainDB Server with Docker](https://bigchaindb.readthedocs.org/en/develop/installing-server.html#run-bigchaindb-with-docker). -Windows users may get the best results [running BigchainDB Server in a VM with Vagrant](https://bigchaindb.readthedocs.org/en/develop/installing.html#how-to-install-bigchaindb-on-a-vm-with-vagrant). +Windows users may get the best results [running BigchainDB Server in a VM with Vagrant](https://bigchaindb.readthedocs.org/en/develop/installing-server.html#how-to-install-bigchaindb-on-a-vm-with-vagrant). + +(BigchainDB clients should run on a much larger array of operating systems.) -(Right now, there are no BigchainDB clients/drivers. Those will be able to run on a much larger array of operating systems. They're coming soon.) ## Install and Run RethinkDB Server -The RethinkDB documentation has instructions for how to install RethinkDB Server on a variety of operating systems. Do that (using their instructions for your OS): [Install RethinkDB Server](http://rethinkdb.com/docs/install/). +If you don't already have RethinkDB Server installed on your server, you must install it. The RethinkDB documentation has instructions for [how to install RethinkDB Server on a variety of operating systems](http://rethinkdb.com/docs/install/). RethinkDB Server doesn't require any special configuration. You can run it by opening a Terminal and entering: ```text @@ -23,9 +24,9 @@ $ rethinkdb If you don't already have it, then you should [install Python 3.4+](https://www.python.org/downloads/) (maybe in a virtual environment, so it doesn't conflict with other Python projects you're working on). -## Install BigchainDB +## Install BigchainDB Server -BigchainDB has some OS-level dependencies. In particular, you need to install the OS-level dependencies for the Python **cryptography** package. Instructions for installing those dependencies on your OS can be found in the [cryptography package documentation](https://cryptography.io/en/latest/installation/). +BigchainDB Server has some OS-level dependencies. In particular, you need to install the OS-level dependencies for the Python **cryptography** package. Instructions for installing those dependencies on your OS can be found in the [cryptography package documentation](https://cryptography.io/en/latest/installation/). On Ubuntu 14.04, we found that the following was enough: ```text @@ -41,11 +42,11 @@ $ sudo dnf install libffi-devel gcc-c++ redhat-rpm-config python3-devel openssl- (If you're using a version of Fedora before version 22, you may have to use `yum` instead of `dnf`.) -With OS-level dependencies installed, you can install BigchainDB with `pip` or from source. +With OS-level dependencies installed, you can install BigchainDB Server with `pip` or from source. ### How to Install BigchainDB with `pip` -BigchainDB is distributed as a Python package on PyPI so you can install it using `pip`. First, make sure you have a version of `pip` installed for Python 3.4+: +BigchainDB (i.e. both the Server and the officially-supported drivers) is distributed as a Python package on PyPI so you can install it using `pip`. First, make sure you have a version of `pip` installed for Python 3.4+: ```text $ pip -V ``` @@ -57,19 +58,19 @@ $ sudo easy_install3 pip ``` (Note: Using `sudo apt-get python3-pip` also installs a Python 3 version of `pip` (named `pip3`) but we found it installed a very old version and there were issues with updating it.) -Once you have a version of `pip` associated with Python 3.4+, then you can install BigchainDB using: +Once you have a version of `pip` associated with Python 3.4+, then you can install BigchainDB Server (and officially-supported BigchainDB drivers) using: ```text 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` +Note: You can use `pip` to upgrade the `bigchaindb` package 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. +BigchainDB (i.e. both the Server and the officially-supported drivers) is in its early stages and being actively developed on its [GitHub repository](https://github.com/bigchaindb/bigchaindb). Contributions are highly appreciated. If you want to help with development, then you'll want to install BigchainDB from source. Here's how. -Clone the public repository: +First, clone the public repository: ```text $ git clone git@github.com:bigchaindb/bigchaindb.git ``` @@ -84,9 +85,9 @@ $ python setup.py install One of our community members ([@Mec-Is](https://github.com/Mec-iS)) wrote [a page about how to install BigchainDB on a VM with Vagrant](https://gist.github.com/Mec-iS/b84758397f1b21f21700). -## Run BigchainDB +## Run BigchainDB Server -Once you've installed BigchainDB, you can run it. First make sure you have RethinkDB running: +Once you've installed BigchainDB Server, you can run it. First make sure you have RethinkDB running: ```text $ rethinkdb ``` @@ -96,21 +97,16 @@ Then open a different terminal and run: $ bigchaindb start ``` -During its first run, BigchainDB takes care of configuring a single node environment. +During its first run, BigchainDB Server takes care of configuring a single node environment. ## Run BigchainDB with Docker **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 -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. +For those who like using Docker and wish to experiment with BigchainDB in 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. -Assuming you have `docker` and `docker-compose` installed, you would proceed as -follows. +Assuming you have `docker` and `docker-compose` installed, you would proceed as follows. In a terminal shell: ```text @@ -142,7 +138,4 @@ If you're on Linux, you can probably view the RethinkDB dashboard at: [http://localhost:58080/](http://localhost:58080/) -If that doesn't work, then replace `localhost` -with the IP or hostname of the machine running the Docker engine. -If you are running docker-machine (e.g.: on Mac OS X) this will be the -IP of the Docker machine (`docker-machine ip machine_name`). +If that doesn't work, then replace `localhost` with the IP or hostname of the machine running the Docker engine. If you are running docker-machine (e.g.: on Mac OS X) this will be the IP of the Docker machine (`docker-machine ip machine_name`). diff --git a/docs/source/introduction.md b/docs/source/introduction.md index e3f5ad75..4583d941 100644 --- a/docs/source/introduction.md +++ b/docs/source/introduction.md @@ -2,12 +2,9 @@ BigchainDB is a scalable blockchain database. You can read about its motivations, goals and high-level architecture in the [BigchainDB whitepaper](https://www.bigchaindb.com/whitepaper/). This document, the _BigchainDB Documentation_, is intended primarily for three groups of people: -1. Developers of BigchainDB server software and related software (e.g. BigchainDB drivers/SDKs). +1. Developers of BigchainDB server software. 2. People deploying and managing BigchainDB clusters. -3. App developers who are developing client apps to talk to one or more live, operational BigchainDB clusters. They would use one of the BigchainDB drivers/SDKs. +3. Developers of BigchainDB driver software (SDKs used to develop client software). +4. App developers who are developing client apps to talk to one or more live, operational BigchainDB clusters. They would use one of the BigchainDB drivers. -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. - -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 +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, file a bug report, or make a pull request, see [the CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/develop/CONTRIBUTING.md). diff --git a/docs/source/models.md b/docs/source/models.md index 267a1a84..a7b0ae4e 100644 --- a/docs/source/models.md +++ b/docs/source/models.md @@ -12,7 +12,7 @@ Transactions, blocks and votes are represented using JSON documents with the fol "new_owner": "", "input": "", "operation": "", - "timestamp": "", + "timestamp": "", "data": { "hash": "", "payload": { @@ -28,13 +28,13 @@ Transactions, blocks and votes are represented using JSON documents with the fol 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. 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 +- `id`: sha3 hash of the transaction. The `id` is also the DB primary key. - `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`: 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 +- `timestamp`: Time of creation of the transaction in UTC. It's provided by the client. - `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`: Signature of the transaction with the `current_owner` private key @@ -45,7 +45,7 @@ sha3 hash of the digital content. { "id": "", "block": { - "timestamp": "", + "timestamp": "", "transactions": [""], "node_pubkey": "", "voters": [""] @@ -62,7 +62,7 @@ A block contains a group of transactions and includes the hash of the hash of th - `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 + - `timestamp`: timestamp when the block was created. It's provided by the node that created the block. - `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 diff --git a/docs/source/monitoring.md b/docs/source/monitoring.md index 4d61cbc4..b5b9ca58 100644 --- a/docs/source/monitoring.md +++ b/docs/source/monitoring.md @@ -20,7 +20,7 @@ then point a browser tab to: [http://localhost:3000/dashboard/script/bigchaindb_dashboard.js](http://localhost:3000/dashboard/script/bigchaindb_dashboard.js) -The login and password are `admin` by default. If BigchainDB is running and processing transactions, you should see analytics—if not, [start BigchainDB](installing.html#run-bigchaindb) and load some test transactions: +The login and password are `admin` by default. If BigchainDB is running and processing transactions, you should see analytics—if not, [start BigchainDB](installing-server.html#run-bigchaindb) and load some test transactions: ```text $ bigchaindb-benchmark load ``` diff --git a/docs/source/python-api-tutorial.md b/docs/source/python-driver-api-examples.md similarity index 61% rename from docs/source/python-api-tutorial.md rename to docs/source/python-driver-api-examples.md index 84c64650..f1e57110 100644 --- a/docs/source/python-api-tutorial.md +++ b/docs/source/python-driver-api-examples.md @@ -1,14 +1,8 @@ -# Getting started with the HTTP API +# The Python Driver API by Example -The preferred way to communicate with a Node in the BigchainDB Federation is via HTTP requests. -Each Node exposes a simple HTTP API that provides, right now, two endpoints, one to get information about a specific -transaction id, one to push transactions to the BigchainDB network. - -The endpoints are documented in [Apiary](http://docs.bigchaindb.apiary.io/). - - -## Usage example using the Python client +The Python driver API is used by app developers to develop client apps which can communicate with one or more BigchainDB clusters. Under the hood, the Python driver API communicates with the BigchainDB cluster using the BigchainDB HTTP client-server API. +Here's an example of how to use the Python driver API. First, launch an interactive Python session, then: ```python In [1]: from bigchaindb.client import temp_client In [2]: c1 = temp_client() @@ -39,15 +33,3 @@ Out[7]: 'operation': 'TRANSFER', 'timestamp': '1456763549.446138'}} ``` - - -# Roadmap - -The development of the API is still at the beginning and you can follow it on -[GitHub](https://github.com/bigchaindb/bigchaindb/issues?q=is%3Aissue+is%3Aopen+label%3Arest-api) - -There are several key features still missing like: - - validating the structure of the transaction - - returns the correct error codes if something goes wrong - - add an endpoint to query unspents for a given public key - diff --git a/docs/source/getting-started.md b/docs/source/python-server-api-examples.md similarity index 88% rename from docs/source/getting-started.md rename to docs/source/python-server-api-examples.md index a6096c57..cfb313ef 100644 --- a/docs/source/getting-started.md +++ b/docs/source/python-server-api-examples.md @@ -1,10 +1,14 @@ -# Getting Started (Tutorial) +# The Python Server API by Example -This section gives an example of using BigchainDB. We create a digital asset, sign it, write it to a BigchainDB instance, read it, transfer it to a different user, and then attempt to transfer it to another user, resulting in a double-spend error. +This section gives an example of using the Python Server API to interact _directly_ with a BigchainDB node running BigchainDB Server. That is, in this example, the Python code and BigchainDB Server run on the same machine. -## Getting Going +(One can also interact with a BigchainDB node via other APIs, including the HTTP Client-Server API.) -First, make sure you have RethinkDB and BigchainDB _installed and running_, i.e. you [installed them](installing.html) and you ran: +We create a digital asset, sign it, write it to a BigchainDB Server instance, read it, transfer it to a different user, and then attempt to transfer it to another user, resulting in a double-spend error. + +## Getting Started + +First, make sure you have RethinkDB and BigchainDB _installed and running_, i.e. you [installed them](installing-server.html) and you ran: ```text $ rethinkdb $ bigchaindb start