Mirroristas/bigchaindb
2
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-10-13 13:34:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #57 from bigchaindb/documentation-improvements

Browse Source 
Numerous documentation improvements
This commit is contained in:
Troy McConaghy 2016-02-17 11:38:56 +01:00
commit 26fe39df85
6 changed files with 87 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/source/bigchaindb-cli.md Normal file
View File

@ -0,0 +1,22 @@
# The BigchainDB Command Line Interfaces (CLIs)
BigchainDB has some Command Line Interfaces (CLIs). One of them is the `bigchaindb` command which we already saw when we first started BigchainDB using:
```text
$ bigchaindb start
```
The fist time you run `bigchaindb start`, it creates a default configuration file in `$HOME/.bigchaindb`. You can check that configuration using:
```text
$ bigchaindb show-config
```
To find out what else you can do with the `bigchain` command, use:
```text
$ bigchaindb -h
```
There's another command named `bigchaindb-benchmark`. It's used to run benchmarking tests. You can learn more about it using:
```text
$ bigchaindb-benchmark -h
$ bigchaindb-benchmark load -h
```

4
docs/source/conf.py
View File

@ -68,9 +68,9 @@ author = 'BigchainDB Contributors'
# built documents.
#
# The short X.Y version.
version = '0.0.1'
version = '0.1'
# The full version, including alpha/beta/rc tags.
release = '0.0.1'
release = '0.1.3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

80
docs/source/getting-started.md
View File

@ -1,58 +1,62 @@
# Getting Started
# Getting Started (Tutorial)
With BigchainDB and rethinkDB [installed and running](intalling.html) we can start creating and
transferring digital assets.
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.
##### Importing BigchainDB
## Getting Going
First, lets open a python shell
```shell
First, make sure you have RethinkDB and BigchainDB _installed and running_, i.e. you [installed them](installing.html) and you ran:
```text
$ rethinkdb
$ bigchaindb start
```
Don't shut them down! In a new terminal, open a Python shell:
```text
$ python
```
Then we can import and instantiate BigchainDB
Now we can import the `Bigchain` class and create an instance:
```python
from bigchaindb import Bigchain
b = Bigchain()
```
When instantiating `Bigchain` witouth arguments it reads the configurations
stored in `$HOME/.bigchaindb`
This instantiates an object `b` of class `Bigchain`. When instantiating a `Bigchain` object without arguments (as above), it reads the configurations stored in `$HOME/.bigchaindb`.
In a federation of BigchainDB nodes, each node has its own `Bigchain` instance.
##### Creating digital assets
In BigchainDB only the federation nodes are allowed to create digital assets
using the `CREATE` operation on the transaction.
Digital assets are usually created and assigned to a user, which in BigchainDB
is represented by a public key.
The `Bigchain` class is the main API for all BigchainDB interactions, right now. It does things that BigchainDB nodes do, but it also does things that BigchainDB clients do. In the future, it will be broken apart into a node/server class and a client class.
BigchainDB allows you to define your digital asset as a generic python dict that
will be used has a payload of the transaction.
The `Bigchain` class is documented in the [Developer Interface](developer-interface.html) section.
## Create a Digital Asset
At a high level, a "digital asset" is something which can be represented digitally and can be assigned to a user. In BigchainDB, users are identified by their public key, and the data payload in a digital asset is represented using a generic [Python dict](https://docs.python.org/3.4/tutorial/datastructures.html#dictionaries).
In BigchainDB, only the federation nodes are allowed to create digital assets, by doing a special kind of transaction: a `CREATE` transaction.
```python
# create a test user
testuser1_priv, testuser1_pub = b.generate_keys()
# define a digital asset
digital_asset = {'msg': 'Hello BigchainDB!'}
# define a digital asset data payload
digital_asset_payload = {'msg': 'Hello BigchainDB!'}
# a create transaction uses the operation `CREATE` has no inputs
tx = b.create_transaction(b.me, testuser1_pub, None, 'CREATE', payload=digital_asset)
# a create transaction uses the operation `CREATE` and has no inputs
tx = b.create_transaction(b.me, testuser1_pub, None, 'CREATE', payload=digital_asset_payload)
# all transactions need to be signed by the user creating the transaction
tx_signed = b.sign_transaction(tx, b.me_private)
# write the transaction to the bigchain
# the transaction will be store in a backlog where it will be validated,
# included in a block and written to the bigchain
# the transaction will be stored in a backlog where it will be validated,
# included in a block, and written to the bigchain
b.write_transaction(tx_signed)
```
##### Reading transactions from the bigchain
After a couple of seconds we can check if the transactions was included in the
bigchain.
## Read the Creation Transaction from the DB
After a couple of seconds, we can check if the transactions was included in the bigchain:
```python
# retrieve a transaction from the bigchain
tx_retrieved = b.get_transaction(tx_signed['id'])
@ -60,24 +64,18 @@ tx_retrieved = b.get_transaction(tx_signed['id'])
'id': '6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd',
'transaction': { 'current_owner': 'pvGtcm5dvwWMzCqagki1N6CDKYs2J1cCwTNw8CqJic3Q',
'data': { 'hash': '872fa6e6f46246cd44afdb2ee9cfae0e72885fb0910e2bcf9a5a2a4eadb417b8',
'payload': {'msg': 'Hello BigchainDB!'}},
'payload': {'msg': 'Hello BigchainDB!'}},
'input': None,
'new_owner': 'ssQnnjketNYmbU3hwgFMEQsc4JVYAmZyWHnHCtFS8aeA',
'operation': 'CREATE',
'timestamp': '1455108421.753908'}}
```
The new owner of the digital asset is now
`ssQnnjketNYmbU3hwgFMEQsc4JVYAmZyWHnHCtFS8aeA` which is the public key of
`testuser1`
The new owner of the digital asset is now `ssQnnjketNYmbU3hwgFMEQsc4JVYAmZyWHnHCtFS8aeA`, which is the public key of `testuser1`.
## Transfer the Digital Asset
##### Transferring digital assets
Now that `testuser1` has a digital asset assigned to him he can now transfered it
to another user. Transfer transactions now require an input. The input will a
transaction id of a digital asset that was assigned to `testuser1` which in our
case is `6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd`
Now that `testuser1` has a digital asset assigned to him, he can transfer it to another user. Transfer transactions require an input. The input will be the transaction id of a digital asset that was assigned to `testuser1`, which in our case is `6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd`.
```python
# create a second testuser
@ -105,14 +103,11 @@ tx_transfer_retrieved = b.get_transaction(tx_transfer_signed['id'])
'timestamp': '1455109497.480323'}}
```
##### Double Spends
## Double Spends
BigchainDB makes sure that a digital asset assigned to a user cannot be
transfered multiple times.
BigchainDB makes sure that a user can't transfer the same digital asset two or more times (i.e. it prevents double spends).
If we try to create another transaction with the same input as before the
transaction will be marked invalid and the validation will trow a double spend
exception
If we try to create another transaction with the same input as before, the transaction will be marked invalid and the validation will throw a double spend exception:
```python
# create another transfer transaction with the same input
@ -124,5 +119,4 @@ tx_transfer_signed2 = b.sign_transaction(tx_transfer2, testuser1_priv)
# check if the transaction is valid
b.validate_transaction(tx_transfer_signed2)
Exception: input `6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd` was already spent
```

2
docs/source/index.rst
View File

@ -12,8 +12,10 @@ Table of Contents
:maxdepth: 5
:numbered:
introduction
installing
getting-started
bigchaindb-cli
admin
cryptography
models

17
docs/source/installing.md
View File

@ -1,6 +1,6 @@
# Installing BigchainDB
# Installing BigchainDB Server
We're developing 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 ("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.)
## Install and Run RethinkDB Server
@ -34,7 +34,7 @@ BigchainDB is distributed as a Python package on PyPI so you can install it usin
$ pip -V
```
If it says that `pip` isn't installed, or it says `pip` is associated with a Python version less then 3.4, then you must install a `pip` version associated with Python 3.4+. See [the `pip` installation instructions](https://pip.pypa.io/en/stable/installing/). On Ubuntu 14.04, we found that this works:
If it says that `pip` isn't installed, or it says `pip` is associated with a Python version less than 3.4, then you must install a `pip` version associated with Python 3.4+. See [the `pip` installation instructions](https://pip.pypa.io/en/stable/installing/). On Ubuntu 14.04, we found that this works:
```text
$ sudo apt-get install python3-setuptools
$ sudo easy_install3 pip
@ -61,13 +61,22 @@ Install from the source:
$ python setup.py install
```
### How to Install BigchainDB on a VM with Vagrant
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).
### How to Install BigchainDB Using Docker
Coming soon...
## Run BigchainDB
After installing BigchainDB, run it with:
Once you've installed BigchainDB, you can run it. First make sure you have RethinkDB running:
```text
$ rethinkdb
```
Then open a different terminal and run:
```text
$ bigchaindb start
```

11
docs/source/introduction.md Normal file
View File

@ -0,0 +1,11 @@
# Introduction
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).
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.
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.