BigchainDB DocumentationRelease 0.1.5

BigchainDB Contributors

April 21, 2016

Contents

1 Table of Contents 11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Installing BigchainDB Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2.1 Install and Run RethinkDB Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2.2 Install Python 3.4+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.3 Install BigchainDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

How to Install BigchainDB with pip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2How to Install BigchainDB from Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2How to Install BigchainDB on a VM with Vagrant . . . . . . . . . . . . . . . . . . . . . . . 3

1.2.4 Run BigchainDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.5 Run BigchainDB with Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.3 Getting Started (Tutorial) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.1 Getting Going . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.2 Create a Digital Asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.3 Read the Creation Transaction from the DB . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3.4 Transfer the Digital Asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3.5 Double Spends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4 The BigchainDB Command Line Interfaces (CLIs) . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.5 Server/Cluster Deployment and Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.5.1 Deploying a local cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.5.2 Securing the storage backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.5.3 Monitoring the storage backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.5.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.6 Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.6.1 Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.6.2 Signature algorithm and keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.7 The Transaction, Block and Vote Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.7.1 The Transaction Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.7.2 The Block Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.7.3 The Vote Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.8 JSON Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.9 Developer Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.10 Contributing to the BigchainDB Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.11 Frequently Asked Questions (FAQ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.12 Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.13 Glossary of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2 Indices and Tables 17

i

ii

CHAPTER 1

Table of Contents

1.1 Introduction

BigchainDB is a scalable blockchain database. You can read about its motivations, goals and high-level architecture inthe BigchainDB whitepaper. This document, the BigchainDB Documentation, is intended primarily for three groupsof 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 BigchainDBdrivers. Those things are coming.

What does exist is our in-development BigchainDB server software. Therefore all the documentation is about that, fornow.

If you’re curious about what’s coming in our roadmap, see the ROADMAP.md file and the list of open issues. If youwant to request a feature or file a bug report, see the CONTRIBUTING.md file.

1.2 Installing BigchainDB Server

We’re developing BigchainDB Server (“BigchainDB”) on Ubuntu 14.04, but it should work on any OS that runsRethinkDB Server and Python 3.4+. (BigchainDB is built on top of RethinkDB Server.)

1.2.1 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.

RethinkDB Server doesn’t require any special configuration. You can run it by opening a Terminal and entering:

$ rethinkdb

1

BigchainDB Documentation, Release 0.1.5

1.2.2 Install Python 3.4+

If you don’t already have it, then you should install Python 3.4+ (maybe in a virtual environment, so it doesn’t conflictwith other Python projects you’re working on).

1.2.3 Install BigchainDB

BigchainDB has some OS-level dependencies. In particular, you need to install the OS-level dependencies for thePython cryptography package. Instructions for installing those dependencies on your OS can be found in the cryp-tography package documentation.

On Ubuntu 14.04, we found that the following was enough (YMMV):

$ sudo apt-get update$ sudo apt-get install libffi-dev g++ libssl-dev python3-dev

With OS-level dependencies installed, you can install BigchainDB 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 aversion of pip installed for Python 3.4+:

$ pip -V

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 installa pip version associated with Python 3.4+. See the pip installation instructions. On Ubuntu 14.04, we found thatthis works:

$ sudo apt-get install python3-setuptools$ sudo easy_install3 pip

(Note: Using sudo apt-get python3-pip also installs a Python 3 version of pip (named pip3) but we foundit 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:

sudo pip install bigchaindb

(or maybe sudo pip3 install bigchaindb or sudo pip3.4 install bigchaindb. The sudo maynot be necessary.)

Note: You can use pip to upgrade bigchaindb to the latest version using sudo pip install --upgradebigchaindb

How to Install BigchainDB from Source

BigchainDB is in its early stages and being actively developed on its GitHub repository. Contributions are highlyappreciated.

Clone the public repository:

$ git clone git@github.com:bigchaindb/bigchaindb.git

Install from the source:

2 Chapter 1. Table of Contents

BigchainDB Documentation, Release 0.1.5

$ python setup.py install

How to Install BigchainDB on a VM with Vagrant

One of our community members (@Mec-Is) wrote a page about how to install BigchainDB on a VM with Vagrant.

1.2.4 Run BigchainDB

Once you’ve installed BigchainDB, you can run it. First make sure you have RethinkDB running:

$ rethinkdb

Then open a different terminal and run:

$ bigchaindb start

During its first run, BigchainDB takes care of configuring a single node environment.

1.2.5 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 adocker-compose.yml file to manage a “standalone node”, consisting mainly of two containers: one for Re-thinkDB, and another for bigchaindb.

Assuming you have docker and docker-compose installed, you would proceed as follows.

In a terminal shell:

$ git clone git@github.com:bigchaindb/bigchaindb.git

Build the Docker image:

$ docker-compose build

then do a one-time configuration step to create the config file; it will be stored on your host machine under~/.bigchaindb_docker/config:

$ docker-compose run --rm bigchaindb bigchaindb configure

You can load test transactions via:

$ docker-compose run --rm bigchaindb bigchaindb-benchmark load

You should then be able to start bigchaindb, via:

$ docker-compose run --rm bigchaindb bigchaindb start

or

$ docker-compose up

You should be able to view the RethinkDB dashboard at:

1.2. Installing BigchainDB Server 3

BigchainDB Documentation, Release 0.1.5

http://docker_host:58080/

where docker_host is the IP or hostname of the machine running the Docker engine. If you are developing onLinux, this most likely will be localhost, whereas if you are running docker-machine (e.g.: on Mac OS X) thiswill be the IP of the Docker machine (docker-machine ip machine_name).

1.3 Getting Started (Tutorial)

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.

1.3.1 Getting Going

First, make sure you have RethinkDB and BigchainDB installed and running, i.e. you installed them and you ran:

$ rethinkdb$ bigchaindb start

Don’t shut them down! In a new terminal, open a Python shell:

$ python

Now we can import the Bigchain class and create an instance:

from bigchaindb import Bigchainb = Bigchain()

This instantiates an object b of class Bigchain. When instantiating a Bigchain object without arguments (asabove), it reads the configurations stored in $HOME/.bigchaindb.

In a federation of BigchainDB nodes, each node has its own Bigchain instance.

The Bigchain class is the main API for all BigchainDB interactions, right now. It does things that BigchainDBnodes do, but it also does things that BigchainDB clients do. In the future, it will be broken apart into a node/serverclass and a client class.

The Bigchain class is documented in the Developer Interface section.

1.3.2 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. InBigchainDB, users are identified by their public key, and the data payload in a digital asset is represented using ageneric Python dict.

In BigchainDB, only the federation nodes are allowed to create digital assets, by doing a special kind of transaction: aCREATE transaction.

# create a test usertestuser1_priv, testuser1_pub = b.generate_keys()

# define a digital asset data payloaddigital_asset_payload = {'msg': 'Hello BigchainDB!'}

# a create transaction uses the operation `CREATE` and has no inputstx = b.create_transaction(b.me, testuser1_pub, None, 'CREATE', payload=digital_asset_payload)

4 Chapter 1. Table of Contents

BigchainDB Documentation, Release 0.1.5

# all transactions need to be signed by the user creating the transactiontx_signed = b.sign_transaction(tx, b.me_private)

# write the transaction to the bigchain# the transaction will be stored in a backlog where it will be validated,# included in a block, and written to the bigchainb.write_transaction(tx_signed)

1.3.3 Read the Creation Transaction from the DB

After a couple of seconds, we can check if the transactions was included in the bigchain:

# retrieve a transaction from the bigchaintx_retrieved = b.get_transaction(tx_signed['id'])

'id': '6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd','transaction': { 'current_owner': 'pvGtcm5dvwWMzCqagki1N6CDKYs2J1cCwTNw8CqJic3Q',

'data': { 'hash': '872fa6e6f46246cd44afdb2ee9cfae0e72885fb0910e2bcf9a5a2a4eadb417b8','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 isthe public key of testuser1.

1.3.4 Transfer the Digital Asset

Now that testuser1 has a digital asset assigned to him, he can transfer it to another user. Transfer transactionsrequire an input. The input will be the transaction id of a digital asset that was assigned to testuser1, which in ourcase is 6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd.

# create a second testusertestuser2_priv, testuser2_pub = b.generate_keys()

# create a transfer transactiontx_transfer = b.create_transaction(testuser1_pub, testuser2_pub, tx_retrieved['id'], 'TRANSFER')

# sign the transactiontx_transfer_signed = b.sign_transaction(tx_transfer, testuser1_priv)

# write the transactionb.write_transaction(tx_transfer_signed)

# check if the transaction is already in the bigchaintx_transfer_retrieved = b.get_transaction(tx_transfer_signed['id'])

{ 'id': '1b78c313257540189f27da480152ed8c0b758569cdadd123d9810c057da408c3','signature': '3045022056166de447001db8ef024cfa1eecdba4306f92688920ac24325729d5a5068d47022100fbd495077cb1040c48bd7dc050b2515b296ca215cb5ce3369f094928e31955f6','transaction': { 'current_owner': 'ssQnnjketNYmbU3hwgFMEQsc4JVYAmZyWHnHCtFS8aeA',

'data': None,'input': '6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd','new_owner': 'zVzophT73m4Wvf3f8gFYokddkYe3b9PbaMzobiUK7fmP',

1.3. Getting Started (Tutorial) 5

BigchainDB Documentation, Release 0.1.5

'operation': 'TRANSFER','timestamp': '1455109497.480323'}}

1.3.5 Double Spends

BigchainDB makes sure that a user can’t transfer the same digital asset two or more times (i.e. it prevents doublespends).

If we try to create another transaction with the same input as before, the transaction will be marked invalid and thevalidation will throw a double spend exception:

# create another transfer transaction with the same inputtx_transfer2 = b.create_transaction(testuser1_pub, testuser2_pub, tx_retrieved['id'], 'TRANSFER')

# sign the transactiontx_transfer_signed2 = b.sign_transaction(tx_transfer2, testuser1_priv)

# check if the transaction is validb.validate_transaction(tx_transfer_signed2)Exception: input `6539dded9479c47b3c83385ae569ecaa90bcf387240d1ee2ea3ae0f7986aeddd` was already spent

1.4 The BigchainDB Command Line Interfaces (CLIs)

BigchainDB has some Command Line Interfaces (CLIs). One of them is the bigchaindb command which wealready saw when we first started BigchainDB using:

$ bigchaindb start

The fist time you run bigchaindb start, it creates a default configuration file in $HOME/.bigchaindb. Youcan check that configuration using:

$ bigchaindb show-config

To find out what else you can do with the bigchain command, use:

$ bigchaindb -h

There’s another command named bigchaindb-benchmark. It’s used to run benchmarking tests. You can learnmore about it using:

$ bigchaindb-benchmark -h$ bigchaindb-benchmark load -h

1.5 Server/Cluster Deployment and Administration

This section covers everything which might concern a BigchainDB server/cluster administrator:

• deployment

• security

• monitoring

• troubleshooting

6 Chapter 1. Table of Contents

BigchainDB Documentation, Release 0.1.5

1.5.1 Deploying a local cluster

One of the advantages of RethinkDB as the storage backend is the easy installation. Developers like to have everythinglocally, so let’s install a local storage backend cluster from scratch. Here is an example to run a cluster assumingrethinkdb is already installed in your system:

# preparing two additional nodes# remember, that the user who starts rethinkdb must have write access to the pathsmkdir -p /path/to/node2mkdir -p /path/to/node3

# then start your additional nodesrethinkdb --port-offset 1 --directory /path/to/node2 --join localhost:29015rethinkdb --port-offset 2 --directory /path/to/node3 --join localhost:29015

That’s all, folks! Cluster is up and running. Check it out in your browser at http://localhost:8080, which opens theconsole.

Now you can install BigchainDB and run it against the storage backend!

1.5.2 Securing the storage backend

We have turned on the bind=all option for connecting other nodes and making RethinkDB accessible from outside theserver. Unfortunately this is insecure. So, we will need to block RethinkDB off from the Internet. But we need toallow access to its services from authorized computers.

For the cluster port, we will use a firewall to enclose our cluster. For the web management console and the driver port,we will use SSH tunnels to access them from outside the server. SSH tunnels redirect requests on a client computerto a remote computer over SSH, giving the client access to all of the services only available on the remote server’slocalhost name space.

Repeat these steps on all your RethinkDB servers.

First, block all outside connections:

# the web management consolesudo iptables -A INPUT -i eth0 -p tcp --dport 8080 -j DROPsudo iptables -I INPUT -i eth0 -s 127.0.0.1 -p tcp --dport 8080 -j ACCEPT

# the driver portsudo iptables -A INPUT -i eth0 -p tcp --dport 28015 -j DROPsudo iptables -I INPUT -i eth0 -s 127.0.0.1 -p tcp --dport 28015 -j ACCEPT

# the communication portsudo iptables -A INPUT -i eth0 -p tcp --dport 29015 -j DROPsudo iptables -I INPUT -i eth0 -s 127.0.0.1 -p tcp --dport 29015 -j ACCEPT

Save the iptables config:

sudo apt-get updatesudo apt-get install iptables-persistent

More about iptables you can find in the man pages.

1.5.3 Monitoring the storage backend

Monitoring is pretty simple. You can do this via the monitoring url. Here you see the complete behaviour of all nodes.One annotation: if you play around with replication the number of transaction will increase. So for the real throughput

1.5. Server/Cluster Deployment and Administration 7

BigchainDB Documentation, Release 0.1.5

you should devide the number of transactions by the number of replicas.

1.5.4 Troubleshooting

Since every software may have some minor issues we are not responsible for the storage backend. If your nodes in asharded and replicated cluster are not in sync, it may help if you delete the data of the affected node and restart thenode. If there are no other problems your node will come back and sync within a couple of minutes. You can verifythis by monitoring the cluster via the monitoring url.

1.6 Cryptography

The section documents the cryptographic algorithms and Python implementations that we use.

The implementations that we have chosen for now are just for fast prototyping. Some of them are pure Pythonimplementations which may be slow. As future work, we should look at other alternatives.

1.6.1 Hashes

For hashing we are using the sha3-256 algorithm and pysha3 as the Python implementation. We store the hex encodedhash in the database. For example:

import hashlib# monkey patch hashlib with sha3 functionsimport sha3

data = "message"tx_hash = hashlib.sha3_256(data).hexdigest()

1.6.2 Signature algorithm and keys

The signature algorithm used by BigchainDB is ECDSA with the secp256k1 curve using the python cryptographymodule.

The private key is the base58 encoded hexadecimal representation of private number. The public key is the base58encoded hexadecimal representation of the compressed public numbers.

1.7 The Transaction, Block and Vote Models

Transactions, blocks and votes are represented using JSON documents with the following models (schemas). See thesection on cryptography for more information about how we calculate hashes and signatures.

1.7.1 The Transaction Model

{"id": "<sha3 hash>","transaction": {

"current_owner": "<pub-key>","new_owner": "<pub-key>","input": "<sha3 hash>",

8 Chapter 1. Table of Contents

BigchainDB Documentation, Release 0.1.5

"operation": "<string>","timestamp": "<timestamp>","data": {

"hash": "<SHA3-256 hash hexdigest of payload>","payload": {

"title": "The Winds of Plast","creator": "Johnathan Plunkett","IPFS_key": "QmfQ5QAjvg4GtA3wg3adpnDJug8ktA1BxurVqBD8rtgVjP"

}}

},"signature": "<signature of the transaction>"

}

A transaction is an operation between the current_owner and the new_owner over the digital content describedby 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 theprimary key, we eliminate the problem of duplicated transactions, if for some reason two nodes decide to createthe 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: id (sha3 hash) of the transaction in which the content was transfered to the user (similar to input in theblockchain). 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 willdefine 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 sha3hash of the digital content.

• signature: Signature of the transaction with the current_owner private key

1.7.2 The Block Model

{"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 public keys>"]

},"signature": "<signature of the block>","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 contents of block (i.e. the timestamp, list of transactions, node_pubkey, and voters). Thisis also a RethinkDB primary key; that’s how we ensure that all blocks are unique.

1.7. The Transaction, Block and Vote Models 9

BigchainDB Documentation, Release 0.1.5

• 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 federation may change over timethis will tell us how many nodes existed in the federation when the block was created so that in a laterpoint 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 (i.e. To create it, the node serialized theblock contents and signed that with its private key)

• votes: Initially an empty list. New votes are appended as they come in from the nodes.

1.7.3 The Vote Model

Each node must generate a vote for each block, to be appended to that block’s votes list. A vote has the followingstructure:

{"node_pubkey": "<the pubkey of the voting node>","vote": {

"voting_for_block": "<id of the block the node is voting for>","previous_block": "<id of the block previous to this one>","is_block_valid": "<true|false>","invalid_reason": "<None|DOUBLE_SPEND|TRANSACTIONS_HASH_MISMATCH|NODES_PUBKEYS_MISMATCH","timestamp": "<timestamp of the voting action>"

},"signature": "<signature of vote block>"

}

Note: The invalid_reason was not being used as of v0.1.3.

1.8 JSON Serialization

We needed to clearly define how to serialize a JSON object to calculate the hash.

The serialization should produce the same byte output independently of the architecture running the software. If thereare differences in the serialization, hash validations will fail although the transaction is correct.

For example, consider the following two methods of serializing {’a’: 1}:

# Use a serializer provided by RethinkDBa = r.expr({'a': 1}).to_json().run(b.connection)u'{"a":1}'

# Use the serializer in Python's json moduleb = json.dumps({'a': 1})'{"a": 1}'

a == bFalse

The results are not the same. We want a serialization and deserialization so that the following is always true:

10 Chapter 1. Table of Contents

BigchainDB Documentation, Release 0.1.5

deserialize(serialize(data)) == dataTrue

After looking at this further, we decided that the python json module is still the best bet because it complies with theRFC. We can specify the encoding, separators used and enforce it to order by the keys to make sure that we obtainmaximum interoperability.

import json

json.dumps(data, skipkeys=False, ensure_ascii=False,encoding="utf-8", separators=(',', ':'),sort_keys=True)

• skipkeys: With skipkeys False if the provided keys are not a string the serialization will fail. This way weenforce all keys to be strings

• ensure_ascii: The RFC recommends utf-8 for maximum interoperability. By setting ensure_asciito False we allow unicode characters and force the encoding to utf-8.

• separators: We need to define a standard separator to use in the serialization. We did not do this differentimplementations could use different separators for serialization resulting in a still valid transaction but with adifferent hash e.g. an extra whitespace introduced in the serialization would not still create a valid JSON objectbut the hash would be different.

Every time we need to perform some operation on the data like calculating the hash or signing/verifying the transaction,we need to use the previous criteria to serialize the data and then use the byte representation of the serialized data (ifwe treat the data as bytes we eliminate possible encoding errors e.g. unicode characters). For example:

# calculate the hash of a transaction# the transaction is a dictionarytx_serialized = bytes(serialize(tx))tx_hash = hashlib.sha3_256(tx_serialized).hexdigest()

# signing a transactiontx_serialized = bytes(serialize(tx))signature = sk.sign(tx_serialized)

# verify signaturetx_serialized = bytes(serialize(tx))vk.verify(signature, tx_serialized)

1.9 Developer Interface

The Bigchain class is the top-level API for BigchainDB. If you want to create and initialize a BigchainDB database,you create a Bigchain instance (object). Then you can use its various methods to create transactions, write transactions(to the object/database), read transactions, etc.

class bigchaindb.Bigchain(host=None, port=None, dbname=None, public_key=None, pri-vate_key=None, keyring=[])

Bigchain API

Create, read, sign, write transactions to the database

__init__(host=None, port=None, dbname=None, public_key=None, private_key=None, keyring=[])Initialize the Bigchain instance

There are three ways in which the Bigchain instance can get its parameters. The order by which theparameters are chosen are:

1.9. Developer Interface 11

BigchainDB Documentation, Release 0.1.5

1.Setting them by passing them to the __init__ method itself.

2.Setting them as environment variables

3.Reading them from the config.json file.

Parameters

• host (str) – hostname where the rethinkdb is running.

• port (int) – port in which rethinkb is running (usually 28015).

• dbname (str) – the name of the database to connect to (usually bigchain).

• public_key (str) – the base58 encoded public key for the ECDSA secp256k1 curve.

• private_key (str) – the base58 encoded private key for the ECDSA secp256k1 curve.

• keyring (list[str]) – list of base58 encoded public keys of the federation nodes.

create_transaction(current_owner, new_owner, tx_input, operation, payload=None)Create a new transaction

A transaction in the bigchain is a transfer of a digital asset between two entities represented by public keys.

Currently the bigchain supports two types of operations:

CREATE - Only federation nodes are allowed to use this operation. In a create operation afederation node creates a digital asset in the bigchain and assigns that asset to a public key. Theowner of the private key can then decided to transfer this digital asset by using the transaction idof the transaction as an input in a TRANSFER transaction.

TRANSFER - A transfer operation allows for a transfer of the digital assets between entities.

Parameters

• current_owner (str) – base58 encoded public key of the current owner of the asset.

• new_owner (str) – base58 encoded public key of the new owner of the digital asset.

• tx_input (str) – id of the transaction to use as input.

• operation (str) – Either CREATE or TRANSFER operation.

• payload (Optional[dict]) – dictionary with information about asset.

Returns unsigned transaction.

Return type dict

Raises TypeError – if the optional payload argument is not a dict.

sign_transaction(transaction, private_key)Sign a transaction

A transaction signed with the current_owner corresponding private key.

Parameters

• transaction (dict) – transaction to sign.

• private_key (str) – base58 encoded private key to create a signature of the transac-tion.

Returns transaction with the signature field included.

Return type dict

12 Chapter 1. Table of Contents

BigchainDB Documentation, Release 0.1.5

verify_signature(signed_transaction)Verify the signature of a transaction

A valid transaction should have been signed current_owner corresponding private key.

Parameters signed_transaction (dict) – a transaction with the signature included.

Returns True if the signature is correct, False otherwise.

Return type bool

write_transaction(signed_transaction)Write the transaction to bigchain.

When first writing a transaction to the bigchain the transaction will be kept in a backlog until it has beenvalidated by the nodes of the federation.

Parameters singed_transaction (dict) – transaction with the signature included.

Returns database response

Return type dict

get_transaction(txid)Retrieve a transaction with txid from bigchain.

Queries the bigchain for a transaction that was already included in a block.

Parameters txid (str) – transaction id of the transaction to query

Returns

A dict with the transaction details if the transaction was found.

If no transaction with that txid was found it returns None

get_tx_by_payload_hash(payload_hash)Retrieves transactions related to a digital asset.

When creating a transaction one of the optional arguments is the payload. The payload is a generic dictthat contains information about the digital asset.

To make it easy to query the bigchain for that digital asset we create a sha3-256 hash of the serializedpayload and store it with the transaction. This makes it easy for developers to keep track of their digitalassets in bigchain.

Parameters payload_hash (str) – sha3-256 hash of the serialized payload.

Returns A list of transactions containing that payload. If no transaction exists with that payloadit returns None

get_spent(txid)Check if a txid was already used as an input.

A transaction can be used as an input for another transaction. Bigchain needs to make sure that a giventxid is only used once.

Parameters txid (str) – transaction id.

Returns The transaction that used the txid as an input if it exists else it returns None

get_owned_ids(owner)Retrieve a list of txids that can we used has inputs.

Parameters owner (str) – base58 encoded public key.

Returns list of txids currently owned by owner

1.9. Developer Interface 13

BigchainDB Documentation, Release 0.1.5

Return type list

validate_transaction(transaction)Validate a transaction.

Parameters transaction (dict) – transaction to validate.

Returns The transaction if the transaction is valid else it raises and exception describing thereason why the transaction is invalid.

Raises

• OperationError – if the transaction operation is not supported

• TransactionDoesNotExist – if the input of the transaction is not found

• TransactionOwnerError – if the new transaction is using an input it doesn’t own

• DoubleSpend – if the transaction is a double spend

• InvalidHash – if the hash of the transaction is wrong

• InvalidSignature – if the signature of the transaction is wrong

is_valid_transaction(transaction)Check whether a transacion is valid or invalid.

Similar to validate_transaction but does not raise an exception if the transaction is valid.

Parameters transaction (dict) – transaction to check.

Returns True if the transaction is valid, False otherwise

Return type bool

create_block(validated_transactions)Creates a block given a list of validated_transactions.

Note that this method does not validate the transactions. Transactions should be validated before callingcreate_block.

Parameters validated_transactions (list) – list of validated transactions.

Returns created block.

Return type dict

validate_block(block)Validate a block.

Parameters block (dict) – block to validate.

Returns The block if the block is valid else it raises and exception describing the reason whythe block is invalid.

is_valid_block(block)Check whether a block is valid or invalid.

Similar to validate_block but does not raise an exception if the block is invalid.

Parameters block (dict) – block to check.

Returns True if the block is valid, False otherwise.

Return type bool

write_block(block, durability=’soft’)Write a block to bigchain.

14 Chapter 1. Table of Contents

BigchainDB Documentation, Release 0.1.5

Parameters block (dict) – block to write to bigchain.

create_genesis_block()Create the genesis block

Block created when bigchain is first initialized. This method is not atomic, there might be concurrencyproblems if multiple instances try to write the genesis block when the BigchainDB Federation is started,but it’s a highly unlikely scenario.

vote(block, previous_block_id, decision, invalid_reason=None)Cast your vote on the block given the previous_block_hash and the decision (valid/invalid) return the blockto the updated in the database.

Parameters

• block (dict) – Block to vote.

• previous_block_id (str) – The id of the previous block.

• decision (bool) – Whether the block is valid or invalid.

• invalid_reason (Optional[str]) – Reason the block is invalid

write_vote(block, vote, block_number)Write the vote to the database

get_last_voted_block()Returns the last block that this node voted on

get_unvoted_blocks()Return all the blocks that has not been voted by this node.

static serialize(data)Static method used to serialize a dict into a JSON formatted string.

This method enforces rules like the separator and order of keys. This ensures that all dicts are serialized inthe same way.

This is specially important for hashing data. We need to make sure that everyone serializes their data in thesame way so that we do not have hash mismatches for the same structure due to serialization differences.

Parameters data (dict) – dict to serialize

Returns JSON formatted string

Return type str

static deserialize(data)Static method used to deserialize a JSON formatted string into a dict.

Parameters data (str) – JSON formatted string.

Returns dict resulting from the serialization of a JSON formatted string.

Return type dict

static timestamp()Static method to calculate a UTC timestamp with microsecond precision.

Returns UTC timestamp.

Return type str

static generate_keys()Generates a key pair.

1.9. Developer Interface 15

BigchainDB Documentation, Release 0.1.5

Returns (private_key, public_key). ECDSA key pair using the secp256k1 curve encoded inbase58.

Return type tuple

1.10 Contributing to the BigchainDB Project

If you’re interested in contributing to the BigchainDB project, you can find out how in the CONTRIBUTING.md file(in the root directory of the BigchainDB repository).

1.11 Frequently Asked Questions (FAQ)

coming soon...

1.12 Release Notes

You can find a list of all BigchainDB releases and release notes on GitHub at:

https://github.com/bigchaindb/bigchaindb/releases

We also have a roadmap document in bigchaindb/ROADMAP.md.

1.13 Glossary of Terms

BigchaindB client. A computer that can communicate with a BigchainDB cluster via the BigchainDB client-serverAPI.

BigchainDB cluster. A collection of servers running BigchainDB Server software and communicating with each othervia RethinkDB protocols. a BigchainDB cluster contains one logical RethinkDB datastore.

Block. A collection of up to 1000 transactions, plus other things. They get chained together by votes. See the sectionon the block model.

Federation. 1. An organization with members and some kind of governance structure. 2. The BigchainDB clusterowned and operated by a Federation’s members.

Federation node. A server running BigchainDB Server software, with permission to communicate with other nodesin a federation.

Node. See Federation node.

Transaction. The basic informational unit. A transaction can represent the creation or transfer of a digital asset. Seethe section on the transaction model.

Vote. Each federation node in a federation is required to vote on the validity of every block (i.e. whether the blockvalid or not). A node’s vote on a block also includes the id of the block it considers to be the previous block. See thesection on the vote model.

16 Chapter 1. Table of Contents

CHAPTER 2

Indices and Tables

• genindex

• modindex

• search

17

BigchainDB Documentation, Release 0.1.5

18 Chapter 2. Indices and Tables

Index

Symbols__init__() (bigchaindb.core.Bigchain method), 11

BBigchain (class in bigchaindb), 11

Ccreate_block() (bigchaindb.Bigchain method), 14create_genesis_block() (bigchaindb.Bigchain method), 15create_transaction() (bigchaindb.Bigchain method), 12

Ddeserialize() (bigchaindb.Bigchain static method), 15

Ggenerate_keys() (bigchaindb.Bigchain static method), 15get_last_voted_block() (bigchaindb.Bigchain method), 15get_owned_ids() (bigchaindb.Bigchain method), 13get_spent() (bigchaindb.Bigchain method), 13get_transaction() (bigchaindb.Bigchain method), 13get_tx_by_payload_hash() (bigchaindb.Bigchain

method), 13get_unvoted_blocks() (bigchaindb.Bigchain method), 15

Iis_valid_block() (bigchaindb.Bigchain method), 14is_valid_transaction() (bigchaindb.Bigchain method), 14

Sserialize() (bigchaindb.Bigchain static method), 15sign_transaction() (bigchaindb.Bigchain method), 12

Ttimestamp() (bigchaindb.Bigchain static method), 15

Vvalidate_block() (bigchaindb.Bigchain method), 14validate_transaction() (bigchaindb.Bigchain method), 14verify_signature() (bigchaindb.Bigchain method), 12

vote() (bigchaindb.Bigchain method), 15

Wwrite_block() (bigchaindb.Bigchain method), 14write_transaction() (bigchaindb.Bigchain method), 13write_vote() (bigchaindb.Bigchain method), 15

19