BigchainDB Documentation¶

Install Terraform¶

The Terraform documentation has installation instructions for all common operating systems.

If you don’t want to run Terraform on your local machine, you can install it on a cloud machine under your control (e.g. on AWS).

Note: Hashicorp has an enterprise version of Terraform called “Terraform Enterprise.” You can license it by itself or get it as part of Atlas. If you decide to license Terraform Enterprise or Atlas, be sure to install it on your own hosting (i.e. “on premise”), not on the hosting provided by Hashicorp. The reason is that BigchainDB clusters are supposed to be decentralized. If everyone used Hashicorp’s hosted Atlas, then that would be a point of centralization.

Ubuntu Installation Tips

If you want to install Terraform on Ubuntu, first download the .zip file. Then install it in /opt:

sudo mkdir -p /opt/terraform
sudo unzip path/to/zip-file.zip -d /opt/terraform

Why install it in /opt? See the answers at Ask Ubuntu.

Next, add /opt/terraform to your path. If you use bash for your shell, then you could add this line to ~/.bashrc:

export PATH="/opt/terraform:$PATH"

After doing that, relaunch your shell or force it to read ~/.bashrc again, e.g. by doing source ~/.bashrc. You can verify that terraform is installed and in your path by doing:

terraform --version

It should say the current version of Terraform.

Use Terraform to Provision a One-Machine Node on AWS¶

We have an example Terraform configuration (set of files) to provision all the resources needed to run a one-machine BigchainDB node on AWS:

• An instance on EC2 (based on an Ubuntu 14.04 AMI)
• A security group
• An EBS volume
• An elastic IP address

Get Set Up to Use Terraform¶

First, do the basic AWS setup steps outlined in the Appendices.

Then go to the .../bigchaindb/ntools/one-m/aws/ directory and open the file variables.tf. Most of the variables have sensible default values, but you can change them if you like. In particular, you may want to change aws_region. (Terraform looks in ~/.aws/credentials to get your AWS credentials, so you don’t have to enter those anywhere.)

The ssh_key_name has no default value, so Terraform will prompt you every time it needs it.

To see what Terraform will do, run:

terraform plan

It should ask you the value of ssh_key_name.

It figured out the plan by reading all the .tf Terraform files in the directory.

If you don’t want to be asked for the ssh_key_name, you can change the default value of ssh_key_name (in the file variables.tf) or you can set an environmen variable named TF_VAR_ssh_key_name.

Use Terraform to Provision Resources¶

To provision all the resources specified in the plan, do the following. Note: This will provision actual resources on AWS, and those cost money. Be sure to shut down the resources you don’t want to keep running later, otherwise the cost will keep growing.

terraform apply

Terraform will report its progress as it provisions all the resources. Once it’s done, you can go to the Amazon EC2 web console and see the instance, its security group, its elastic IP, and its attached storage volumes (one for the root directory and one for RethinkDB storage).

At this point, there is no software installed on the instance except for Ubuntu 14.04 and whatever else came with the Amazon Machine Image (AMI) specified in the Terraform configuration (files). The next step is to use Ansible to install, configure and run all the necessary software.

Optional: “Destroy” the Resources¶

If you want to shut down all the resources just provisioned, you must first disable termination protection on the instance:

1. Go to the EC2 console and select the instance you just launched. It should be named BigchainDB_node.
2. Click Actions > Instance Settings > Change Termination Protection > Yes, Disable
3. Back in your terminal, do terraform destroy

Terraform should “destroy” (i.e. terminate or delete) all the AWS resources you provisioned above.

If it fails (e.g. because of an attached and mounted EBS volume), then you can terminate the instance using the EC2 console: Actions > Instance State > Terminate > Yes, Terminate. Once the instance is terminated, you should still do terraform destroy to make sure that all the other resources are destroyed.

Install Ansible¶

The Ansible documentation has installation instructions. Note the control machine requirements: at the time of writing, Ansible required Python 2.6 or 2.7. (Support for Python 3 is a goal of Ansible 2.2.)

For example, you could create a special Python 2.x virtualenv named ansenv and then install Ansible in it:

cd repos/bigchaindb/ntools
virtualenv -p /usr/local/lib/python2.7.11/bin/python ansenv
source ansenv/bin/activate
pip install ansible

About Out Example Ansible Playbook¶

We have an example Ansible playbook to install, configure and run a basic BigchainDB node on Ubuntu 14.04. It’s in .../bigchaindb/ntools/one-m/ansible/one-m-node.yml.

When you run the playbook (as per the instructions below), it ensures all the necessary software is installed, configured and running. It can be used to get a BigchainDB node set up on a bare Ubuntu 14.04 machine, but it can also be used to ensure that everything is okay on a running BigchainDB node. (If you run the playbook against a host where everything is okay, then it won’t change anything on that host.)

Create an Ansible Inventory File¶

An Ansible “inventory” file is a file which lists all the hosts (machines) you want to manage using Ansible. (Ansible will communicate with them via SSH.) Right now, we only want to manage one host.

First, determine the public IP address of the host (i.e. something like 192.0.2.128).

Then create a one-line text file named hosts by doing this:

# cd to the directory .../bigchaindb/ntools/one-m/ansible
echo "192.0.2.128" > hosts

but replace 192.0.2.128 with the IP address of the host.

Run the Ansible Playbook¶

The next step is to run the Ansible playbook named one-m-node.yml:

# cd to the directory .../bigchaindb/ntools/one-m/ansible
ansible-playbook -i hosts --private-key ~/.ssh/<key-name> one-m-node.yml

where <key-name> should be replaced by the name of the SSH private key you created earlier (for SSHing to the host machine at your cloud hosting provider).

What did you just do? Running that playbook ensures all the software necessary for a one-machine BigchainDB node is installed, configured, and running properly. You can run that playbook on a regular schedule to ensure that the system stays properly configured. If something is okay, it does nothing; it only takes action when something is not as-desired.

Some Notes on the One-Machine Node You Just Got Running¶

• It ensures that the installed version of RethinkDB is 2.3.4~0trusty. You can change that by changing the installation task.
• It uses a very basic RethinkDB configuration file based on bigchaindb/ntools/one-m/ansible/roles/rethinkdb/templates/rethinkdb.conf.j2.
• If you edit the RethinkDB configuration file, then running the Ansible playbook will not restart RethinkDB for you. You must do that manually. (You could just stop it using sudo killall -9 rethinkdb and then run the playbook to get it started again.)
• It generates and uses a default BigchainDB configuration file, which is stores in ~/.bigchaindb (the default location).
• If you edit the BigchainDB configuration file, then running the Ansible playbook will **not* restart BigchainDB for you. You must do that manually. (You could just stop it using sudo killall -9 bigchaindb and then run the playbook to get it started again.)

Optional: Create an Ansible Config File¶

The above command (ansible-playbook -i ...) is fairly long. You can omit the optional arguments if you put their values in an Ansible configuration file (config file) instead. There are many places where you can put a config file, but to make one specifically for the “one-m” case, you should put it in .../bigchaindb/ntools/one-m/ansible/. In that directory, create a file named ansible.cfg with the following contents:

[defaults]
private_key_file = $HOME/.ssh/<key-name>
inventory = hosts

where, as before, <key-name> must be replaced.

Next Steps¶

You could make changes to the Terraform configuration and the Ansible playbook to make the node more production-worthy. See the section on production node assumptions, components and requirements.

OS Requirements¶

• RethinkDB Server will run on any modern OS. Note that the Fedora package isn’t officially supported. Also, official support for Windows is fairly recent (April 2016).
• BigchainDB Server requires Python 3.4+ and Python 3.4+ will run on any modern OS.
• BigchaindB Server uses the Python multiprocessing package and some functionality in the multiprocessing package doesn’t work on OS X. You can still use Mac OS X if you use Docker or a virtual machine.

The BigchainDB core dev team uses Ubuntu 14.04, Ubuntu 16.04, Fedora 23, and Fedora 24.

We don’t test BigchainDB on Windows or Mac OS X, but you can try.

• If you run into problems on Windows, then you may want to try using Vagrant. One of our community members (@Mec-Is) wrote a page about how to install BigchainDB on a VM with Vagrant.
• If you have Mac OS X and want to experiment with BigchainDB, then you could do that using Docker.

Storage Requirements¶

When it comes to storage for RethinkDB, there are many things that are nice to have (e.g. SSDs, high-speed input/output [IOPS], replication, reliability, scalability, pay-for-what-you-use), but there are few requirements other than:

1. have enough storage to store all your data (and its replicas), and
2. make sure your storage solution (hardware and interconnects) can handle your expected read & write rates.

For RethinkDB’s failover mechanisms to work, every RethinkDB table must have at least three replicas (i.e. a primary replica and two others). For example, if you want to store 10 GB of unique data, then you need at least 30 GB of storage. (Indexes and internal metadata are stored in RAM.)

As for the read & write rates, what do you expect those to be for your situation? It’s not enough for the storage system alone to handle those rates: the interconnects between the nodes must also be able to handle them.

Memory (RAM) Requirements¶

In their FAQ, RethinkDB recommends that, “RethinkDB servers have at least 2GB of RAM...” (source)

In particular: “RethinkDB requires data structures in RAM on each server proportional to the size of the data on that server’s disk, usually around 1% of the size of the total data set.” (source) We asked what they meant by “total data set” and they said it’s “referring to only the data stored on the particular server.”

Also, “The storage engine is used in conjunction with a custom, B-Tree-aware caching engine which allows file sizes many orders of magnitude greater than the amount of available memory. RethinkDB can operate on a terabyte of data with about ten gigabytes of free RAM.” (source) (In this case, it’s the cluster which has a total of one terabyte of data, and it’s the cluster which has a total of ten gigabytes of RAM. That is, if you add up the RethinkDB RAM on all the servers, it’s ten gigabytes.)

In reponse to our questions about RAM requirements, @danielmewes (of RethinkDB) wrote:

... If you replicate the data, the amount of data per server increases accordingly, because multiple copies of the same data will be held by different servers in the cluster.

For example, if you increase the data replication factor from 1 to 2 (i.e. the primary plus one copy), then that will double the RAM needed for metadata. Also from @danielmewes:

For reasonable performance, you should probably aim at something closer to 5-10% of the data size. [Emphasis added] The 1% is the bare minimum and doesn’t include any caching. If you want to run near the minimum, you’ll also need to manually lower RethinkDB’s cache size through the --cache-size parameter to free up enough RAM for the metadata overhead...

RethinkDB has documentation about its memory requirements. You can use that page to get a better estimate of how much memory you’ll need. In particular, note that RethinkDB automatically configures the cache size limit to be about half the available memory, but it can be no lower than 100 MB. As @danielmewes noted, you can manually change the cache size limit (e.g. to free up RAM for queries, metadata, or other things).

If a RethinkDB process (on a server) runs out of RAM, the operating system will start swapping RAM out to disk, slowing everything down. According to @danielmewes:

Going into swap is usually pretty bad for RethinkDB, and RethinkDB servers that have gone into swap often become so slow that other nodes in the cluster consider them unavailable and terminate the connection to them. I recommend adjusting RethinkDB’s cache size conservatively to avoid this scenario. RethinkDB will still make use of additional RAM through the operating system’s block cache (though less efficiently than when it can keep data in its own cache).

Filesystem Requirements¶

RethinkDB “supports most commonly used file systems” (source) but it has issues with BTRFS (B-tree file system).

It’s best to use a filesystem that supports direct I/O, because that will improve RethinkDB performance (if you tell RethinkDB to use direct I/O). Many compressed or encrypted filesystems don’t support direct I/O.

Get a Server¶

The first step is to get a server (or equivalent) which meets the requirements for a BigchainDB node.

Secure Your Server¶

The steps that you must take to secure your server depend on your server OS and where your server is physically located. There are many articles and books about how to secure a server. Here we just cover special considerations when securing a BigchainDB node.

There are some notes on BigchainDB-specific firewall setup in the Appendices.

Sync Your System Clock¶

A BigchainDB node uses its system clock to generate timestamps for blocks and votes, so that clock should be kept in sync with some standard clock(s). The standard way to do that is to run an NTP daemon (Network Time Protocol daemon) on the node. (You could also use tlsdate, which uses TLS timestamps rather than NTP, but don’t: it’s not very accurate and it will break with TLS 1.3, which removes the timestamp.)

NTP is a standard protocol. There are many NTP daemons implementing it. We don’t recommend a particular one. On the contrary, we recommend that different nodes in a federation run different NTP daemons, so that a problem with one daemon won’t affect all nodes.

Please see the notes on NTP daemon setup in the Appendices.

Set Up Storage for RethinkDB Data¶

Below are some things to consider when setting up storage for the RethinkDB data. The Appendices have a section with concrete examples.

We suggest you set up a separate storage “device” (partition, RAID array, or logical volume) to store the RethinkDB data. Here are some questions to ask:

• How easy will it be to add storage in the future? Will I have to shut down my server?
• How big can the storage get? (Remember that RAID can be used to make several physical drives look like one.)
• How fast can it read & write data? How many input/output operations per second (IOPS)?
• How does IOPS scale as more physical hard drives are added?
• What’s the latency?
• What’s the reliability? Is there replication?
• What’s in the Service Level Agreement (SLA), if applicable?
• What’s the cost?

There are many options and tradeoffs. Don’t forget to look into Amazon Elastic Block Store (EBS) and Amazon Elastic File System (EFS), or their equivalents from other providers.

Storage Notes Specific to RethinkDB

• The RethinkDB storage engine has a number of SSD optimizations, so you can benefit from using SSDs. (source)
• If you want a RethinkDB cluster to store an amount of data D, with a replication factor of R (on every table), and the cluster has N nodes, then each node will need to be able to store R×D/N data.
• RethinkDB tables can have at most 64 shards. For example, if you have only one table and more than 64 nodes, some nodes won’t have the primary of any shard, i.e. they will have replicas only. In other words, once you pass 64 nodes, adding more nodes won’t provide more storage space for new data. If the biggest single-node storage available is d, then the most you can store in a RethinkDB cluster is < 64×d: accomplished by putting one primary shard in each of 64 nodes, with all replica shards on other nodes. (This is assuming one table. If there are T tables, then the most you can store is < 64×d×T.)
• When you set up storage for your RethinkDB data, you may have to select a filesystem. (Sometimes, the filesystem is already decided by the choice of storage.) We recommend using a filesystem that supports direct I/O (Input/Output). Many compressed or encrypted file systems don’t support direct I/O. The ext4 filesystem supports direct I/O (but be careful: if you enable the data=journal mode, then direct I/O support will be disabled; the default is data=ordered). If your chosen filesystem supports direct I/O and you’re using Linux, then you don’t need to do anything to request or enable direct I/O. RethinkDB does that.

What is direct I/O? It allows RethinkDB to write directly to the storage device (or use its own in-memory caching mechanisms), rather than relying on the operating system's file read and write caching mechanisms. (If you're using Linux, a write-to-file normally writes to the in-memory Page Cache first; only later does that Page Cache get flushed to disk. The Page Cache is also used when reading files.)

• RethinkDB stores its data in a specific directory. You can tell RethinkDB which directory using the RethinkDB config file, as explained below. In this documentation, we assume the directory is /data. If you set up a separate device (partition, RAID array, or logical volume) to store the RethinkDB data, then mount that device on /data.

Install RethinkDB Server¶

If you don’t already have RethinkDB Server installed, you must install it. The RethinkDB documentation has instructions for how to install RethinkDB Server on a variety of operating systems.

Configure RethinkDB Server¶

Create a RethinkDB configuration file (text file) named instance1.conf with the following contents (explained below):

directory=/data
bind=all
direct-io
# Replace node?_hostname with actual node hostnames below, e.g. rdb.examples.com
join=node0_hostname:29015
join=node1_hostname:29015
join=node2_hostname:29015
# continue until there's a join= line for each node in the federation

• directory=/data tells the RethinkDB node to store its share of the database data in /data.
• bind=all binds RethinkDB to all local network interfaces (e.g. loopback, Ethernet, wireless, whatever is available), so it can communicate with the outside world. (The default is to bind only to local interfaces.)
• direct-io tells RethinkDB to use direct I/O (explained earlier). Only include this line if your file system supports direct I/O.
• join=hostname:29015 lines: A cluster node needs to find out the hostnames of all the other nodes somehow. You could designate one node to be the one that every other node asks, and put that node’s hostname in the config file, but that wouldn’t be very decentralized. Instead, we include every node in the list of nodes-to-ask.

If you’re curious about the RethinkDB config file, there’s a RethinkDB documentation page about it. The explanations of the RethinkDB command-line options are another useful reference.

See the RethinkDB documentation on securing your cluster.

Install Python 3.4+¶

If you don’t already have it, then you should install Python 3.4+.

If you’re testing or developing BigchainDB on a stand-alone node, then you should probably create a Python 3.4+ virtual environment and activate it (e.g. using virtualenv or conda). Later we will install several Python packages and you probably only want those installed in the virtual environment.

Install BigchainDB Server¶

BigchainDB Server has some OS-level dependencies that must be installed.

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

sudo apt-get update
sudo apt-get install g++ python3-dev

On Fedora 23, we found that the following was enough (tested in February 2015):

sudo dnf update
sudo dnf install gcc-c++ redhat-rpm-config python3-devel

(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 Server with pip or from source.

pip -V

sudo apt-get install python3-pip

pip3 install --upgrade pip setuptools
pip3 -V

pip3 install bigchaindb

git clone git@github.com:bigchaindb/bigchaindb.git
python setup.py install

Configure BigchainDB Server¶

Start by creating a default BigchainDB config file:

bigchaindb -y configure

(There’s documentation for the bigchaindb command is in the section on the BigchainDB Command Line Interface (CLI).)

Edit the created config file:

• Open $HOME/.bigchaindb (the created config file) in your text editor.
• Change "server": {"bind": "localhost:9984", ... } to "server": {"bind": "0.0.0.0:9984", ... }. This makes it so traffic can come from any IP address to port 9984 (the HTTP Client-Server API port).
• Change "api_endpoint": "http://localhost:9984/api/v1" to "api_endpoint": "http://your_api_hostname:9984/api/v1"
• Change "keyring": [] to "keyring": ["public_key_of_other_node_A", "public_key_of_other_node_B", "..."] i.e. a list of the public keys of all the other nodes in the federation. The keyring should not include your node’s public key.

For more information about the BigchainDB config file, see Configuring a BigchainDB Node.

Run RethinkDB Server¶

Start RethinkDB using:

rethinkdb --config-file path/to/instance1.conf

except replace the path with the actual path to instance1.conf.

Note: It’s possible to make RethinkDB start at system startup.

You can verify that RethinkDB is running by opening the RethinkDB web interface in your web browser. It should be at http://rethinkdb-hostname:8080/. If you’re running RethinkDB on localhost, that would be http://localhost:8080/.

Run BigchainDB Server¶

After all node operators have started RethinkDB, but before they start BigchainDB, one designated node operator must configure the RethinkDB database by running the following commands:

bigchaindb init
bigchaindb set-shards numshards
bigchaindb set-replicas numreplicas

where:

• bigchaindb init creates the database within RethinkDB, the tables, the indexes, and the genesis block.
• numshards should be set to the number of nodes in the initial cluster.
• numreplicas should be set to the database replication factor decided by the federation. It must be 3 or more for RethinkDB failover to work.

Once the RethinkDB database is configured, every node operator can start BigchainDB using:

bigchaindb start

Using docker-compose to Run the Tests¶

You can also use docker-compose to run the unit tests.

Start RethinkDB in the background:

$ docker-compose up -d rdb

then run the unit tests using:

$ docker-compose run --rm bdb py.test -v

keypair.public & keypair.private¶

The cryptographic keypair used by the node. The public key is how the node idenifies itself to the world. The private key is used to generate cryptographic signatures. Anyone with the public key can verify that the signature was generated by whoever had the corresponding private key.

Example using environment variables

export BIGCHAINDB_KEYPAIR_PUBLIC=8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw
export BIGCHAINDB_KEYPAIR_PRIVATE=5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D

Example config file snippet

"keypair": {
  "public": "8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw",
  "private": "5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D"
}

Internally (i.e. in the Python code), both keys have a default value of None, but that’s not a valid key. Therefore you can’t rely on the defaults for the keypair. If you want to run BigchainDB, you must provide a valid keypair, either in the environment variables or in the local config file. You can generate a local config file with a valid keypair (and default everything else) using bigchaindb -y configure.

keyring¶

A list of the public keys of all the nodes in the cluster, excluding the public key of this node.

Example using an environment variable

export BIGCHAINDB_KEYRING=BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB:4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ

Note how the keys in the list are separated by colons.

Example config file snippet

"keyring": ["BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB", 
            "4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ"]

Default value (from a config file)

"keyring": []

database.host, database.port & database.name¶

The RethinkDB database hostname, port and name.

Example using environment variables

export BIGCHAINDB_DATABASE_HOST=localhost
export BIGCHAINDB_DATABASE_PORT=28015
export BIGCHAINDB_DATABASE_NAME=bigchain

Example config file snippet

"database": {
    "host": "localhost",
    "port": 28015,
    "name": "bigchain"
}

Default values (a snippet from bigchaindb/__init__.py)

'database': {
    'host': os.environ.get('BIGCHAINDB_DATABASE_HOST', 'localhost'),
    'port': 28015,
    'name': 'bigchain',
}

server.bind, server.workers & server.threads¶

These settings are for the Gunicorn HTTP server, which is used to serve the HTTP client-server API.

server.bind is where to bind the Gunicorn HTTP server socket. It’s a string. It can be any valid value for Gunicorn’s bind setting. If you want to allow IPv4 connections from anyone, on port 9984, use ‘0.0.0.0:9984’. In a production setting, we recommend you use Gunicorn behind a reverse proxy server. If Gunicorn and the reverse proxy are running on the same machine, then use ‘localhost:PORT’ where PORT is not 9984 (because the reverse proxy needs to listen on port 9984). Maybe use PORT=9983 in that case because we know 9983 isn’t used. If Gunicorn and the reverse proxy are running on different machines, then use ‘A.B.C.D:9984’ where A.B.C.D is the IP address of the reverse proxy. There’s more information about deploying behind a reverse proxy in the Gunicorn documentation. (They call it a proxy.)

server.workers is the number of worker processes for handling requests. If None (the default), the value will be (cpu_count * 2 + 1). server.threads is the number of threads-per-worker for handling requests. If None (the default), the value will be (cpu_count * 2 + 1). The HTTP server will be able to handle server.workers * server.threads requests simultaneously.

Example using environment variables

export BIGCHAINDB_SERVER_BIND=0.0.0.0:9984
export BIGCHAINDB_SERVER_WORKERS=5
export BIGCHAINDB_SERVER_THREADS=5

Example config file snippet

"server": {
    "bind": "0.0.0.0:9984",
    "workers": 5,
    "threads": 5
}

Default values (from a config file)

"server": {
    "bind": "localhost:9984",
    "workers": null,
    "threads": null
}

api_endpoint¶

api_endpoint is the URL where a BigchainDB client can get access to the HTTP client-server API.

Example using an environment variable

export BIGCHAINDB_API_ENDPOINT="http://localhost:9984/api/v1"

Example config file snippet

"api_endpoint": "http://webserver.blocks587.net:9984/api/v1"

Default value (from a config file)

"api_endpoint": "http://localhost:9984/api/v1"

consensus_plugin¶

The consensus plugin to use.

Example using an environment variable

export BIGCHAINDB_CONSENSUS_PLUGIN=default

Example config file snippet: the default

"consensus_plugin": "default"

statsd.host, statsd.port & statsd.rate¶

These settings are used to configure where, and how often, StatsD should send data for cluster monitoring purposes. statsd.host is the hostname of the monitoring server, where StatsD should send its data. stats.port is the port. statsd.rate is the fraction of transaction operations that should be sampled. It’s a float between 0.0 and 1.0.

Example using environment variables

export BIGCHAINDB_STATSD_HOST="http://monitor.monitors-r-us.io"
export BIGCHAINDB_STATSD_PORT=8125
export BIGCHAINDB_STATSD_RATE=0.01

Example config file snippet: the default

"statsd": {"host": "localhost", "port": 8125, "rate": 0.01}

bigchaindb --help¶

Show help for the bigchaindb command. bigchaindb -h does the same thing.

bigchaindb --version¶

Show the version number. bigchaindb -v does the same thing.

bigchaindb configure¶

Generate a local config file (which can be used to set some or all BigchainDB node configuration settings). It will auto-generate a public-private keypair and then ask you for the values of other configuration settings. If you press Enter for a value, it will use the default value.

If you use the -c command-line option, it will generate the file at the specified path:

bigchaindb -c path/to/new_config.json configure

If you don’t use the -c command-line option, the file will be written to $HOME/.bigchaindb (the default location where BigchainDB looks for a config file, if one isn’t specified).

If you use the -y command-line option, then there won’t be any interactive prompts: it will just generate a keypair and use the default values for all the other configuration settings.

bigchaindb -y configure

bigchaindb show-config¶

Show the values of the BigchainDB node configuration settings.

bigchaindb export-my-pubkey¶

Write the node’s public key (i.e. one of its configuration values) to standard output (stdout).

bigchaindb init¶

Create a RethinkDB database, all RethinkDB database tables, various RethinkDB database indexes, and the genesis block.

Note: The bigchaindb start command (see below) always starts by trying a bigchaindb init first. If it sees that the RethinkDB database already exists, then it doesn’t re-initialize the database. One doesn’t have to do bigchaindb init before bigchaindb start. bigchaindb init is useful if you only want to initialize (but not start).

bigchaindb drop¶

Drop (erase) the RethinkDB database. You will be prompted to make sure. If you want to force-drop the database (i.e. skipping the yes/no prompt), then use bigchaindb -y drop

bigchaindb start¶

Start BigchainDB. It always begins by trying a bigchaindb init first. See the note in the documentation for bigchaindb init. You can also use the --experimental-start-rethinkdb command line option to automatically start rethinkdb with bigchaindb if rethinkdb is not already running, e.g. bigchaindb --experimental-start-rethinkdb start. Note that this will also shutdown rethinkdb when the bigchaindb process stops.

bigchaindb load¶

Write transactions to the backlog (for benchmarking tests). You can learn more about it using:

$ bigchaindb load -h

bigchaindb set-shards¶

Set the number of shards in the underlying datastore. For example, the following command will set the number of shards to four:

$ bigchaindb set-shards 4

bigchaindb set-replicas¶

Set the number of replicas (of each shard) in the underlying datastore. For example, the following command will set the number of replicas to three (i.e. it will set the replication factor to three):

$ bigchaindb set-replicas 3

Getting Started¶

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

$ rethinkdb
$ bigchaindb configure
$ 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 Bigchain
b = Bigchain()

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.

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 refactored into different parts. The Bigchain class is documented elsewhere (link).

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.

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

from bigchaindb import crypto

# Create a test user
testuser1_priv, testuser1_pub = crypto.generate_key_pair()

# Define a digital asset data payload
digital_asset_payload = {'msg': 'Hello BigchainDB!'}

# 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 stored in a backlog where it will be validated,
# included in a block, and written to the bigchain 
b.write_transaction(tx_signed)

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 bigchain
tx_retrieved = b.get_transaction(tx_signed['id'])
tx_retrieved

{
    "id":"933cd83a419d2735822a2154c84176a2f419cbd449a74b94e592ab807af23861",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:oqXTWvR3afHHX8OaOO84kZxS6nH4GEBXD4Vw8Mc5iBo:96"
                },
                "owners_after":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs"
                ]
            }
        ],
        "data":{
            "hash":"872fa6e6f46246cd44afdb2ee9cfae0e72885fb0910e2bcf9a5a2a4eadb417b8",
            "payload":{
                "msg":"Hello BigchainDB!"
            }
        },
        "fulfillments":[
            {
                "owners_before":[
                    "3LQ5dTiddXymDhNzETB1rEkp4mA7fEV1Qeiu5ghHiJm9"
                ],
                "fid":0,
                "fulfillment":"cf:4:Iq-BcczwraM2UpF-TDPdwK8fQ6IXkD_6uJaxBZd984yxCGX7Csx-S2FBVe8LVyW2sAtmjsOSV0oiw9-s_9qSJB0dDUl_x8YQk5yxNdQyNVWVM1mWSGQL68gMngdmFG8O",
                "input":None
            }
        ],
        "operation":"CREATE",
        "timestamp":"1460981667.449279"
    },
    "version":1
}

The new owner of the digital asset is now BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs, which is the public key of testuser1.

Note that the current owner (with public key 3LQ5dTiddXymDhNzETB1rEkp4mA7fEV1Qeiu5ghHiJm9) is the federation node which created the asset and assigned it to testuser1.

Transfer the Digital Asset¶

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 933cd83a419d2735822a2154c84176a2f419cbd449a74b94e592ab807af23861.

BigchainDB makes use of the crypto-conditions library to both cryptographically lock and unlock transactions. The locking script is refered to as a condition and a corresponding fulfillment unlocks the condition of the input_tx.

Since a transaction can have multiple outputs with each its own (crypto)condition, each transaction input should also refer to the condition index cid.

# Create a second testuser
testuser2_priv, testuser2_pub = crypto.generate_key_pair()

# Retrieve the transaction with condition id
tx_retrieved_id = b.get_owned_ids(testuser1_pub).pop()
tx_retrieved_id

{
    "cid":0,
    "txid":"933cd83a419d2735822a2154c84176a2f419cbd449a74b94e592ab807af23861"
}

# Create a transfer transaction
tx_transfer = b.create_transaction(testuser1_pub, testuser2_pub, tx_retrieved_id, 'TRANSFER')

# Sign the transaction
tx_transfer_signed = b.sign_transaction(tx_transfer, testuser1_priv)

# Write the transaction
b.write_transaction(tx_transfer_signed)

# Check if the transaction is already in the bigchain
tx_transfer_retrieved = b.get_transaction(tx_transfer_signed['id'])
tx_transfer_retrieved

{
    "id":"aa11365317cb89bfdae2375bae76d6b8232008f8672507080e3766ca06976dcd",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:DIfyalZvV_9ukoO01mxmK3nxsfAWSKYYF33XDYkbY4E:96"
                },
                "owners_after":[
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ]
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs"
                ],
                "fid":0,
                "fulfillment":"cf:4:oqXTWvR3afHHX8OaOO84kZxS6nH4GEBXD4Vw8Mc5iBqzkVR6cFJhRvMGKa-Lc81sdYWVu0ZSMPGht-P7s6FZLkRXDqrwwInabLhjx14eABY34oHb6IyWcB-dyQnlVNEI",
                "input":{
                    "cid":0,
                    "txid":"933cd83a419d2735822a2154c84176a2f419cbd449a74b94e592ab807af23861"
                }
            }
        ],
        "operation":"TRANSFER",
        "timestamp":"1460981677.472037"
    },
    "version":1
}

Double Spends¶

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 throw a double spend exception:

# Create another transfer transaction with the same input
tx_transfer2 = b.create_transaction(testuser1_pub, testuser2_pub, tx_retrieved_id, 'TRANSFER')

# Sign the transaction
tx_transfer_signed2 = b.sign_transaction(tx_transfer2, testuser1_priv)

# Check if the transaction is valid
b.validate_transaction(tx_transfer_signed2)

DoubleSpend: input `{'cid': 0, 'txid': '933cd83a419d2735822a2154c84176a2f419cbd449a74b94e592ab807af23861'}` was already spent

Multiple Owners¶

To create a new digital asset with multiple owners, one can simply provide a list of owners_after:

# Create a new asset and assign it to multiple owners
tx_multisig = b.create_transaction(b.me, [testuser1_pub, testuser2_pub], None, 'CREATE')

# Have the federation node sign the transaction
tx_multisig_signed = b.sign_transaction(tx_multisig, b.me_private)

# Write the transaction
b.write_transaction(tx_multisig_signed)

# Check if the transaction is already in the bigchain
tx_multisig_retrieved = b.get_transaction(tx_multisig_signed['id'])
tx_multisig_retrieved

{
    "id":"a9a6e5c74ea02b8885c83125f1b74a2ba8ca42236ec5e1c358aa1053ec721ccb",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":41,
                        "subfulfillments":[
                            {
                                "bitmask":32,
                                "public_key":"BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs",
                                "signature":None,
                                "type":"fulfillment",
                                "type_id":4,
                                "weight":1
                            },
                            {
                                "bitmask":32,
                                "public_key":"qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor",
                                "signature":None,
                                "type":"fulfillment",
                                "type_id":4,
                                "weight":1
                            }
                        ],
                        "threshold":2,
                        "type":"fulfillment",
                        "type_id":2
                    },
                    "uri":"cc:2:29:DpflJzUSlnTUBx8lD8QUolOA-M9nQnrGwvWSk7f3REc:206"
                },
                "owners_after":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs",
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ]
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[
                    "3LQ5dTiddXymDhNzETB1rEkp4mA7fEV1Qeiu5ghHiJm9"
                ],
                "fid":0,
                "fulfillment":"cf:4:Iq-BcczwraM2UpF-TDPdwK8fQ6IXkD_6uJaxBZd984z5qdHRz9Jag68dkOyZS5_YoTR_0WpwiUnBGoNgwjwEuIn5JNm7Kksi0nUnHsWssyXISkmqRnHH-30HQhKjznIH",
                "input":None
            }
        ],
        "operation":"CREATE",
        "timestamp":"1460981687.501433"
    },
    "version":1
}

The asset can be transfered as soon as each of the owners_after signs the transaction.

To do so, simply provide a list of all private keys to the signing routine:

# Create a third testuser
testuser3_priv, testuser3_pub = crypto.generate_key_pair()

# Retrieve the multisig transaction
tx_multisig_retrieved_id = b.get_owned_ids(testuser2_pub).pop()

# Transfer the asset from the 2 owners to the third testuser 
tx_multisig_transfer = b.create_transaction([testuser1_pub, testuser2_pub], testuser3_pub, tx_multisig_retrieved_id, 'TRANSFER')

# Sign with both private keys
tx_multisig_transfer_signed = b.sign_transaction(tx_multisig_transfer, [testuser1_priv, testuser2_priv])

# Write the transaction
b.write_transaction(tx_multisig_transfer_signed)

# Check if the transaction is already in the bigchain
tx_multisig_transfer_retrieved = b.get_transaction(tx_multisig_transfer_signed['id'])
tx_multisig_transfer_retrieved

{
    "id":"e689e23f774e7c562eeb310c7c712b34fb6210bea5deb9175e48b68810029150",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"8YN9fALMj9CkeCcmTiM2kxwurpkMzHg9RkwSLJKMasvG",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:cAq6JQJXtwlxURqrksiyqLThB9zh08ZxSPLTDSaReYE:96"
                },
                "owners_after":[
                    "8YN9fALMj9CkeCcmTiM2kxwurpkMzHg9RkwSLJKMasvG"
                ]
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs",
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ],
                "fid":0,
                "fulfillment":"cf:4:oqXTWvR3afHHX8OaOO84kZxS6nH4GEBXD4Vw8Mc5iBrcuiGDNVgpH9SwiuNeYZ-nugSTbxykH8W1eH5UJiunmnBSlKnJb8_QYOQsMAXl3MyLq2pWAyI45ZSG1rr2CksI",
                "input":{
                    "cid":0,
                    "txid":"aa11365317cb89bfdae2375bae76d6b8232008f8672507080e3766ca06976dcd"
                }
            }
        ],
        "operation":"TRANSFER",
        "timestamp":"1460981697.526878"
    },
    "version":1
}

Multiple Inputs and Outputs¶

With BigchainDB it is possible to send multiple assets to someone in a single transfer.

The transaction will create a fulfillment - condition pair for each input, which can be refered to by fid and cid respectively.

# Create some assets for bulk transfer
for i in range(3):
    tx_mimo_asset = b.create_transaction(b.me, testuser1_pub, None, 'CREATE')
    tx_mimo_asset_signed = b.sign_transaction(tx_mimo_asset, b.me_private)
    b.write_transaction(tx_mimo_asset_signed)

# Wait until they appear on the bigchain and get the inputs
owned_mimo_inputs = b.get_owned_ids(testuser1_pub)

# Check the number of assets
print(len(owned_mimo_inputs))

# Create a signed TRANSFER transaction with all the assets
tx_mimo = b.create_transaction(testuser1_pub, testuser2_pub, owned_mimo_inputs, 'TRANSFER')
tx_mimo_signed = b.sign_transaction(tx_mimo, testuser1_priv)

# Write the transaction
b.write_transaction(tx_mimo_signed)

# Check if the transaction is already in the bigchain
tx_mimo_retrieved = b.get_transaction(tx_mimo_signed['id'])
tx_mimo_retrieved

{
    "id":"8b63689691a3c2e8faba89c6efe3caa0661f862c14d88d1e63ebd65d49484de2",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:2AXg2JJ7mQ8o2Q9-hafP-XmFh3YR7I2_Sz55AubfxIc:96"
                },
                "owners_after":[
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ]
            },
            {
                "cid":1,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:2AXg2JJ7mQ8o2Q9-hafP-XmFh3YR7I2_Sz55AubfxIc:96"
                },
                "owners_after":[
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ]
            },
            {
                "cid":2,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:2AXg2JJ7mQ8o2Q9-hafP-XmFh3YR7I2_Sz55AubfxIc:96"
                },
                "owners_after":[
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ]
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs"
                ],
                "fid":0,
                "fulfillment":"cf:4:sTzo4fvm8U8XrlXcgcGkNZgkfS9QHg2grgrJiX-c0LT_a83V0wbNRVbmb0eOy6tLyRw0kW1FtsN29yTcTAILX5-fyBITrPUqPzIzF85l8yIAMSjVfH-h6YNcUQBj0o4B",
                "input":{
                    "cid":0,
                    "txid":"9a99f3c82aea23fb344acb1505926365e2c6b722761c4be6ab8916702c94c024"
                }
            },
            {
                "owners_before":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs"
                ],
                "fid":1,
                "fulfillment":"cf:4:sTzo4fvm8U8XrlXcgcGkNZgkfS9QHg2grgrJiX-c0LSJe3B_yjgXd1JHPBJhAdywCzR_ykEezi3bPNucGHl5mgPvpsLpHWrdIvZa3arFD91AepXILaNCF0y8cxIBOyEE",
                "input":{
                    "cid":0,
                    "txid":"783014b92f35da0c2526e1db6f81452c61853d29eda50d057fd043d507d03ef9"
                }
            },
            {
                "owners_before":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs"
                ],
                "fid":2,
                "fulfillment":"cf:4:sTzo4fvm8U8XrlXcgcGkNZgkfS9QHg2grgrJiX-c0LReUQd-vDMseuVi03qY5Fxetv81fYpy3z1ncHIGc2bX7R69aS-yH5_deV9qaKjc1ZZFN5xXsB9WFpQkf9VQ-T8B",
                "input":{
                    "cid":0,
                    "txid":"9ab6151334b06f3f3aab282597ee8a7c12b9d7a0c43f356713f7ef9663375f50"
                }
            }
        ],
        "operation":"TRANSFER",
        "timestamp":"1461049149.568927"
    },
    "version":1
}

Crypto-Conditions (Advanced)¶

import copy

import cryptoconditions as cc
from bigchaindb import util, crypto

# Create some new testusers
thresholduser1_priv, thresholduser1_pub = crypto.generate_key_pair()
thresholduser2_priv, thresholduser2_pub = crypto.generate_key_pair()
thresholduser3_priv, thresholduser3_pub = crypto.generate_key_pair()

# Retrieve the last transaction of testuser2
tx_retrieved_id = b.get_owned_ids(testuser2_pub).pop()

# Create a base template for a 1-input/2-output transaction
threshold_tx = b.create_transaction(testuser2_pub, [thresholduser1_pub, thresholduser2_pub, thresholduser3_pub], tx_retrieved_id, 'TRANSFER')

# Create a Threshold Cryptocondition
threshold_condition = cc.ThresholdSha256Fulfillment(threshold=2)
threshold_condition.add_subfulfillment(cc.Ed25519Fulfillment(public_key=thresholduser1_pub))
threshold_condition.add_subfulfillment(cc.Ed25519Fulfillment(public_key=thresholduser2_pub))
threshold_condition.add_subfulfillment(cc.Ed25519Fulfillment(public_key=thresholduser3_pub))

# Update the condition in the newly created transaction
threshold_tx['transaction']['conditions'][0]['condition'] = {
    'details': threshold_condition.to_dict(),
    'uri': threshold_condition.condition.serialize_uri()
}

# Conditions have been updated, so the transaction hash (ID) needs updating
threshold_tx['id'] = util.get_hash_data(threshold_tx)

# Sign the transaction
threshold_tx_signed = b.sign_transaction(threshold_tx, testuser2_priv)

# Write the transaction
b.write_transaction(threshold_tx_signed)

# Check if the transaction is already in the bigchain
tx_threshold_retrieved = b.get_transaction(threshold_tx_signed['id'])
tx_threshold_retrieved

{
    "id":"0057d29ff735d91505decf5e7195ea8da675b01676165abf23ea774bbb469383",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":41,
                        "subfulfillments":[
                            {
                                "bitmask":32,
                                "public_key":"8NaGq26YMcEvj8Sc5MnqspKzFTQd1eZBAuuPDw4ERHpz",
                                "signature":None,
                                "type":"fulfillment",
                                "type_id":4,
                                "weight":1
                            },
                            {
                                "bitmask":32,
                                "public_key":"ALE9Agojob28D1fHWCxFXJwpqrYPkcsUs26YksBVj27z",
                                "signature":None,
                                "type":"fulfillment",
                                "type_id":4,
                                "weight":1
                            },
                            {
                                "bitmask":32,
                                "public_key":"Cx4jWSGci7fw6z5QyeApCijbwnMpyuhp4C1kzuFc3XrM",
                                "signature":None,
                                "type":"fulfillment",
                                "type_id":4,
                                "weight":1
                            }
                        ],
                        "threshold":2,
                        "type":"fulfillment",
                        "type_id":2
                    },
                    "uri":"cc:2:29:FoElId4TE5TU2loonT7sayXhxwcmaJVoCeIduh56Dxw:246"
                },
                "owners_after":[
                    "8NaGq26YMcEvj8Sc5MnqspKzFTQd1eZBAuuPDw4ERHpz",
                    "ALE9Agojob28D1fHWCxFXJwpqrYPkcsUs26YksBVj27z",
                    "Cx4jWSGci7fw6z5QyeApCijbwnMpyuhp4C1kzuFc3XrM"
                ]
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ],
                "fid":0,
                "fulfillment":"cf:4:DIfyalZvV_9ukoO01mxmK3nxsfAWSKYYF33XDYkbY4EbD7-_neXJJEe_tVTDc1_EqldlP_ulysFMprcW3VG4gzLzCMMpxA8kCr_pvywSFIEVYJHnI1csMvPivvBGHvkD",
                "input":{
                    "cid":0,
                    "txid":"aa11365317cb89bfdae2375bae76d6b8232008f8672507080e3766ca06976dcd"
                }
            }
        ],
        "operation":"TRANSFER",
        "timestamp":"1460981707.559401"
    },
    "version":1
}

# Create a new testuser to receive
thresholduser4_priv, thresholduser4_pub = crypto.generate_key_pair()

# Retrieve the last transaction of thresholduser1_pub
tx_retrieved_id = b.get_owned_ids(thresholduser1_pub).pop()

# Create a base template for a 2-input/1-output transaction
threshold_tx_transfer = b.create_transaction([thresholduser1_pub, thresholduser2_pub, thresholduser3_pub], thresholduser4_pub, tx_retrieved_id, 'TRANSFER')

# Parse the threshold cryptocondition
threshold_fulfillment = cc.Fulfillment.from_dict(threshold_tx['transaction']['conditions'][0]['condition']['details'])

subfulfillment1 = threshold_fulfillment.get_subcondition_from_vk(thresholduser1_pub)[0]
subfulfillment2 = threshold_fulfillment.get_subcondition_from_vk(thresholduser2_pub)[0]
subfulfillment3 = threshold_fulfillment.get_subcondition_from_vk(thresholduser3_pub)[0]


# Get the fulfillment message to sign
threshold_tx_fulfillment_message = util.get_fulfillment_message(threshold_tx_transfer,
                                                                threshold_tx_transfer['transaction']['fulfillments'][0],
                                                                serialized=True)

# Clear the subconditions of the threshold fulfillment, they will be added again after signing
threshold_fulfillment.subconditions = []

# Sign and add the subconditions until threshold of 2 is reached
subfulfillment1.sign(threshold_tx_fulfillment_message, crypto.SigningKey(thresholduser1_priv))
threshold_fulfillment.add_subfulfillment(subfulfillment1)
subfulfillment2.sign(threshold_tx_fulfillment_message, crypto.SigningKey(thresholduser2_priv))
threshold_fulfillment.add_subfulfillment(subfulfillment2)

# Add remaining (unfulfilled) fulfillment as a condition
threshold_fulfillment.add_subcondition(subfulfillment3.condition)

# Update the fulfillment
threshold_tx_transfer['transaction']['fulfillments'][0]['fulfillment'] = threshold_fulfillment.serialize_uri()

# Optional validation checks
assert threshold_fulfillment.validate(threshold_tx_fulfillment_message) == True
assert b.validate_fulfillments(threshold_tx_transfer) == True
assert b.validate_transaction(threshold_tx_transfer)

b.write_transaction(threshold_tx_transfer)
threshold_tx_transfer

{
    "id":"a45b2340c59df7422a5788b3c462dee708a18cdf09d1a10bd26be3f31af4b8d7",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"ED2pyPfsbNRTHkdMnaFkAwCSpZWRmbaM1h8fYzgRRMmc",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:xDz3NhRG-3eVzIB9sgnd99LKjOyDF-KlxWuf1TgNT0s:96"
                },
                "owners_after":[
                    "ED2pyPfsbNRTHkdMnaFkAwCSpZWRmbaM1h8fYzgRRMmc"
                ]
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[
                    "8NaGq26YMcEvj8Sc5MnqspKzFTQd1eZBAuuPDw4ERHpz",
                    "ALE9Agojob28D1fHWCxFXJwpqrYPkcsUs26YksBVj27z",
                    "Cx4jWSGci7fw6z5QyeApCijbwnMpyuhp4C1kzuFc3XrM"
                ],
                "fid":0,
                "fulfillment":"cf:2:AQIBAwEBACcABAEgILGLuLLaNHo-KE59tkrpYmlVeucu16Eg9TcSuBqnMVwmAWABAWMABGBtiKCT8NBtSdnxJNdGYkyWqoRy2qOeNZ5UdUvpALcBD4vGRaohuVP9pQYNHpAA5GjTNNQT9CVMB67D8QL_DJsRU8ICSIVIG2P8pRqX6oia-304Xqq67wY-wLh_3IKlUg0AAQFjAARgiqYTeWkT6-jRMriCK4i8ceE2TwPys0JXgIrbw4kbwElVNnc7Aqw5c-Ts8-ymLp3d9_xTIb3-mPaV4JjhBqcobKuq2msJAjrxZOEeuYuAyC0tpduwTajOyp_Kmwzhdm8PAA",
                "input":{
                    "cid":0,
                    "txid":"0057d29ff735d91505decf5e7195ea8da675b01676165abf23ea774bbb469383"
                }
            }
        ],
        "operation":"TRANSFER",
        "timestamp":"1460981717.579700"
    },
    "version":1
}

# Create a hash-locked asset without any owners_after
hashlock_tx = b.create_transaction(b.me, None, None, 'CREATE')

# Define a secret that will be hashed - fulfillments need to guess the secret
secret = b'much secret! wow!'
first_tx_condition = cc.PreimageSha256Fulfillment(preimage=secret)

# The conditions list is empty, so we need to append a new condition
hashlock_tx['transaction']['conditions'].append({
    'condition': {
        'uri': first_tx_condition.condition.serialize_uri()
    },
    'cid': 0,
    'owners_after': None
})

# Conditions have been updated, so the hash needs updating
hashlock_tx['id'] = util.get_hash_data(hashlock_tx)

# The asset needs to be signed by the owner_before
hashlock_tx_signed = b.sign_transaction(hashlock_tx, b.me_private)

# Some validations
assert b.validate_transaction(hashlock_tx_signed) == hashlock_tx_signed

b.write_transaction(hashlock_tx_signed)
hashlock_tx_signed

{
    "id":"604c520244b7ff63604527baf269e0cbfb887122f503703120fd347d6b99a237",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "uri":"cc:0:3:nsW2IiYgk9EUtsg4uBe3pBnOgRoAEX2IIsPgjqZz47U:17"
                },
                "owners_after":None
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[
                    "FmLm6MxCABc8TsiZKdeYaZKo5yZWMM6Vty7Q1B6EgcP2"
                ],
                "fid":0,
                "fulfillment":"cf:4:21-D-LfNhIQhvY5914ArFTUGpgPKc7EVC1ZtJqqOTHGx1p9FuRr9tRfkbdqtX2MZWh7sRVUmMnwp7I1-xZbCnCkeADf69IwDHbZvNS6aTr1CpekREsV9ZG8m_wjlZiUN",
                "input":None
            }
        ],
        "operation":"CREATE",
        "timestamp":"1461250387.910102"
    },
    "version":1
}

hashlockuser_priv, hashlockuser_pub = crypto.generate_key_pair()

# Create hashlock fulfillment tx
hashlock_fulfill_tx = b.create_transaction(None, hashlockuser_pub, {'txid': hashlock_tx['id'], 'cid': 0}, 'TRANSFER')

# Provide a wrong secret
hashlock_fulfill_tx_fulfillment = cc.PreimageSha256Fulfillment(preimage=b'')
hashlock_fulfill_tx['transaction']['fulfillments'][0]['fulfillment'] = \
    hashlock_fulfill_tx_fulfillment.serialize_uri()
    
assert b.is_valid_transaction(hashlock_fulfill_tx) == False

# Provide the right secret
hashlock_fulfill_tx_fulfillment = cc.PreimageSha256Fulfillment(preimage=secret)
hashlock_fulfill_tx['transaction']['fulfillments'][0]['fulfillment'] = \
    hashlock_fulfill_tx_fulfillment.serialize_uri()

assert b.validate_transaction(hashlock_fulfill_tx) == hashlock_fulfill_tx

b.write_transaction(hashlock_fulfill_tx)
hashlock_fulfill_tx

{
    "id":"fe6871bf3ca62eb61c52c5555cec2e07af51df817723f0cb76e5cf6248f449d2",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":32,
                        "public_key":"EiqCKxnBCmmNb83qyGch48tULK9RLaEt4xFA43UVCVDb",
                        "signature":None,
                        "type":"fulfillment",
                        "type_id":4
                    },
                    "uri":"cc:4:20:y9884Md2YI_wdnGSTJGhwvFaNsKLe8sqwimqk-2JLSI:96"
                },
                "owners_after":[
                    "EiqCKxnBCmmNb83qyGch48tULK9RLaEt4xFA43UVCVDb"
                ]
            }
        ],
        "data":None,
        "fulfillments":[
            {
                "owners_before":[],
                "fid":0,
                "fulfillment":"cf:0:bXVjaCBzZWNyZXQhIHdvdyE",
                "input":{
                    "cid":0,
                    "txid":"604c520244b7ff63604527baf269e0cbfb887122f503703120fd347d6b99a237"
                }
            }
        ],
        "operation":"TRANSFER",
        "timestamp":"1461250397.944510"
    },
    "version":1
}

# Create a timeout asset without any owners_after
tx_timeout = b.create_transaction(b.me, None, None, 'CREATE')

# Set expiry time - the asset needs to be transfered before expiration
time_sleep = 12
time_expire = str(float(util.timestamp()) + time_sleep)  # 12 secs from now
condition_timeout = cc.TimeoutFulfillment(expire_time=time_expire)

# The conditions list is empty, so we need to append a new condition
tx_timeout['transaction']['conditions'].append({
    'condition': {
        'details': condition_timeout.to_dict(),
        'uri': condition_timeout.condition.serialize_uri()
    },
    'cid': 0,
    'owners_after': None
})

# Conditions have been updated, so the hash needs updating
tx_timeout['id'] = util.get_hash_data(tx_timeout)

# The asset needs to be signed by the owner_before
tx_timeout_signed = b.sign_transaction(tx_timeout, b.me_private)

# Some validations
assert b.validate_transaction(tx_timeout_signed) == tx_timeout_signed

b.write_transaction(tx_timeout_signed)
tx_timeout_signed

{
    "id":"78145396cd368f7168fb01c97aaf1df6f85244d7b544073dfcb42397dae38f90",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":9,
                        "expire_time":"1464167910.643431",
                        "type":"fulfillment",
                        "type_id":99
                    },
                    "uri":"cc:63:9:sceU_NZc3cAjAvaR1TVmgj7am5y8hJEBoqLm-tbqGbQ:17"
                },
                "owners_after":null
            }
        ],
        "data":null,
        "fulfillments":[
            {
                "owners_before":[
                    "FmLm6MxCABc8TsiZKdeYaZKo5yZWMM6Vty7Q1B6EgcP2"
                ],
                "fid":0,
                "fulfillment":null,
                "input":null
            }
        ],
        "operation":"CREATE",
        "timestamp":"1464167898.643353"
    },
    "version":1
}

from time import sleep

# Create a timeout fulfillment tx
tx_timeout_transfer = b.create_transaction(None, testuser1_pub, {'txid': tx_timeout['id'], 'cid': 0}, 'TRANSFER')

# Parse the timeout condition and create the corresponding fulfillment
timeout_fulfillment = cc.Fulfillment.from_dict(
    tx_timeout['transaction']['conditions'][0]['condition']['details'])
tx_timeout_transfer['transaction']['fulfillments'][0]['fulfillment'] = timeout_fulfillment.serialize_uri()

# No need to sign transaction, like with hashlocks

# Small test to see the state change
for i in range(time_sleep - 4):
    tx_timeout_valid = b.is_valid_transaction(tx_timeout_transfer) == tx_timeout_transfer
    seconds_to_timeout = int(float(time_expire) - float(util.timestamp()))
    print('tx_timeout valid: {} ({}s to timeout)'.format(tx_timeout_valid, seconds_to_timeout))
    sleep(1)

tx_timeout valid: True (3s to timeout)
tx_timeout valid: True (2s to timeout)
tx_timeout valid: True (1s to timeout)
tx_timeout valid: True (0s to timeout)
tx_timeout valid: False (0s to timeout)
tx_timeout valid: False (-1s to timeout)
tx_timeout valid: False (-2s to timeout)
tx_timeout valid: False (-3s to timeout)

Escrow¶

Escrow is a mechanism for conditional release of assets.

This means that a the assets are locked up by a trusted party until an execute condition is presented. In order not to tie up the assets forever, the escrow foresees an abort condition, which is typically an expiry time.

BigchainDB and cryptoconditions provides escrow out-of-the-box, without the need of a trusted party.

A threshold condition is used to represent the escrow, since BigchainDB transactions cannot have a pending state.

The logic for switching between execute and abort conditions is conceptually simple:

if timeout_condition.validate(utcnow()):
    execute_fulfillment.validate(msg) == True
    abort_fulfillment.validate(msg) == False
else:
    execute_fulfillment.validate(msg) == False
    abort_fulfillment.validate(msg) == True

The above switch can be implemented as follows using threshold cryptoconditions:

The inverted timeout is denoted by a -1 threshold, which negates the output of the fulfillment.

inverted_fulfillment.validate(msg) == not fulfillment.validate(msg)

Note: inverted thresholds are BigchainDB-specific and not supported by the ILP standard. The main reason is that it’s difficult to tell whether the fulfillment was negated, or just omitted.

The following code snippet shows how to create an escrow condition:

# Retrieve the last transaction of testuser2_pub (or create a new asset)
tx_retrieved_id = b.get_owned_ids(testuser2_pub).pop()

# Create a base template with the execute and abort address
tx_escrow = b.create_transaction(testuser2_pub, [testuser2_pub, testuser1_pub], tx_retrieved_id, 'TRANSFER')

# Set expiry time - the execute address needs to fulfill before expiration
time_sleep = 12
time_expire = str(float(util.timestamp()) + time_sleep)  # 12 secs from now

# Create the escrow and timeout condition
condition_escrow = cc.ThresholdSha256Fulfillment(threshold=1)  # OR Gate
condition_timeout = cc.TimeoutFulfillment(expire_time=time_expire)  # only valid if now() <= time_expire
condition_timeout_inverted = cc.InvertedThresholdSha256Fulfillment(threshold=1)
condition_timeout_inverted.add_subfulfillment(condition_timeout)  # invert the timeout condition

# Create the execute branch
condition_execute = cc.ThresholdSha256Fulfillment(threshold=2)  # AND gate
condition_execute.add_subfulfillment(cc.Ed25519Fulfillment(public_key=testuser1_pub))  # execute address
condition_execute.add_subfulfillment(condition_timeout)  # federation checks on expiry
condition_escrow.add_subfulfillment(condition_execute)

# Create the abort branch
condition_abort = cc.ThresholdSha256Fulfillment(threshold=2)  # AND gate
condition_abort.add_subfulfillment(cc.Ed25519Fulfillment(public_key=testuser2_pub))  # abort address
condition_abort.add_subfulfillment(condition_timeout_inverted)
condition_escrow.add_subfulfillment(condition_abort)

# Update the condition in the newly created transaction
tx_escrow['transaction']['conditions'][0]['condition'] = {
    'details': condition_escrow.to_dict(),
    'uri': condition_escrow.condition.serialize_uri()
}

# Conditions have been updated, so the hash needs updating
tx_escrow['id'] = util.get_hash_data(tx_escrow)

# The asset needs to be signed by the owner_before
tx_escrow_signed = b.sign_transaction(tx_escrow, testuser2_priv)

# Some validations
assert b.validate_transaction(tx_escrow_signed) == tx_escrow_signed

b.write_transaction(tx_escrow_signed)
tx_escrow_signed

{
    "id":"1a281da2b9bc3d2beba92479058d440de3353427fd64045a61737bad0d0c809c",
    "transaction":{
        "conditions":[
            {
                "cid":0,
                "condition":{
                    "details":{
                        "bitmask":41,
                        "subfulfillments":[
                            {
                                "bitmask":41,
                                "subfulfillments":[
                                    {
                                        "bitmask":32,
                                        "public_key":"qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor",
                                        "signature":null,
                                        "type":"fulfillment",
                                        "type_id":4,
                                        "weight":1
                                    },
                                    {
                                        "bitmask":9,
                                        "expire_time":"1464242352.227917",
                                        "type":"fulfillment",
                                        "type_id":99,
                                        "weight":1
                                    }
                                ],
                                "threshold":2,
                                "type":"fulfillment",
                                "type_id":2,
                                "weight":1
                            },
                            {
                                "bitmask":41,
                                "subfulfillments":[
                                    {
                                        "bitmask":32,
                                        "public_key":"BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs",
                                        "signature":null,
                                        "type":"fulfillment",
                                        "type_id":4,
                                        "weight":1
                                    },
                                    {
                                        "bitmask":9,
                                        "subfulfillments":[
                                            {
                                                "bitmask":9,
                                                "expire_time":"1464242352.227917",
                                                "type":"fulfillment",
                                                "type_id":99,
                                                "weight":1
                                            }
                                        ],
                                        "threshold":1,
                                        "type":"fulfillment",
                                        "type_id":98,
                                        "weight":1
                                    }
                                ],
                                "threshold":2,
                                "type":"fulfillment",
                                "type_id":2,
                                "weight":1
                            }
                        ],
                        "threshold":1,
                        "type":"fulfillment",
                        "type_id":2
                    },
                    "uri":"cc:2:29:sg08ERtppQrGxot7mu7XMdNkZTc29xCbWE1r8DgxuL8:181"
                },
                "owners_after":[
                    "BwuhqQX8FPsmqYiRV2CSZYWWsSWgSSQQFHjqxKEuqkPs",
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ]
            }
        ],
        "data":null,
        "fulfillments":[
            {
                "owners_before":[
                    "qv8DvdNG5nZHWCP5aPSqgqxAvaPJpQj19abRvFCntor"
                ],
                "fid":0,
                "fulfillment":"cf:4:B6VAa7KAMD1v-pyvDx9RuBLb6l2Qs3vhucgXqzU_RbuRucOp6tNY8AoNMoC-HAOZBJSnHXZsdJ7pLCZ6aDTwUHXf0zxyLaCgy1NpES3h8qcuxbfv4Nchw3BtUcVSY3AM",
                "input":{
                    "cid":1,
                    "txid":"d3f5e78f6d4346466178745f1c01cbcaf1c1dce1932a16cd653051b16ee29bac"
                }
            }
        ],
        "operation":"TRANSFER",
        "timestamp":"1464242340.227787"
    },
    "version":1
}

At any given moment testuser1 and testuser2 can try to fulfill the execute and abort branch respectively. Whether the fulfillment will validate depends on the timeout condition.

We’ll illustrate this by example.

In the case of testuser1, we create the execute fulfillment:

# Create a base template for execute fulfillment
tx_escrow_execute = b.create_transaction([testuser2_pub, testuser1_pub], testuser1_pub, {'txid': tx_escrow_signed['id'], 'cid': 0}, 'TRANSFER')

# Parse the Escrow cryptocondition
escrow_fulfillment = cc.Fulfillment.from_dict(
    tx_escrow['transaction']['conditions'][0]['condition']['details'])

subfulfillment_testuser1 = escrow_fulfillment.get_subcondition_from_vk(testuser1_pub)[0]
subfulfillment_testuser2 = escrow_fulfillment.get_subcondition_from_vk(testuser2_pub)[0]
subfulfillment_timeout = escrow_fulfillment.subconditions[0]['body'].subconditions[1]['body']
subfulfillment_timeout_inverted = escrow_fulfillment.subconditions[1]['body'].subconditions[1]['body']

# Get the fulfillment message to sign
tx_escrow_execute_fulfillment_message = \
    util.get_fulfillment_message(tx_escrow_execute,
                                 tx_escrow_execute['transaction']['fulfillments'][0],
                                 serialized=True)

# Clear the subconditions of the escrow fulfillment
escrow_fulfillment.subconditions = []

# Fulfill the execute branch
fulfillment_execute = cc.ThresholdSha256Fulfillment(threshold=2)
subfulfillment_testuser1.sign(tx_escrow_execute_fulfillment_message, crypto.SigningKey(testuser1_priv))
fulfillment_execute.add_subfulfillment(subfulfillment_testuser1)
fulfillment_execute.add_subfulfillment(subfulfillment_timeout)
escrow_fulfillment.add_subfulfillment(fulfillment_execute)

# Do not fulfill the abort branch
condition_abort = cc.ThresholdSha256Fulfillment(threshold=2)
condition_abort.add_subfulfillment(subfulfillment_testuser2)
condition_abort.add_subfulfillment(subfulfillment_timeout_inverted)
escrow_fulfillment.add_subcondition(condition_abort.condition)  # Adding only the condition here

# Update the execute transaction with the fulfillment
tx_escrow_execute['transaction']['fulfillments'][0]['fulfillment'] = escrow_fulfillment.serialize_uri()

In the case of testuser2, we create the abort fulfillment:

# Create a base template for execute fulfillment
tx_escrow_abort = b.create_transaction([testuser2_pub, testuser1_pub], testuser2_pub, {'txid': tx_escrow_signed['id'], 'cid': 0}, 'TRANSFER')

# Parse the threshold cryptocondition
escrow_fulfillment = cc.Fulfillment.from_dict(
    tx_escrow['transaction']['conditions'][0]['condition']['details'])

subfulfillment_testuser1 = escrow_fulfillment.get_subcondition_from_vk(testuser1_pub)[0]
subfulfillment_testuser2 = escrow_fulfillment.get_subcondition_from_vk(testuser2_pub)[0]
subfulfillment_timeout = escrow_fulfillment.subconditions[0]['body'].subconditions[1]['body']
subfulfillment_timeout_inverted = escrow_fulfillment.subconditions[1]['body'].subconditions[1]['body']

# Get the fulfillment message to sign
tx_escrow_abort_fulfillment_message = \
    util.get_fulfillment_message(tx_escrow_abort,
                                 tx_escrow_abort['transaction']['fulfillments'][0],
                                 serialized=True)
                                 
# Clear the subconditions of the escrow fulfillment
escrow_fulfillment.subconditions = []

# Do not fulfill the execute branch
condition_execute = cc.ThresholdSha256Fulfillment(threshold=2)
condition_execute.add_subfulfillment(subfulfillment_testuser1)
condition_execute.add_subfulfillment(subfulfillment_timeout)
escrow_fulfillment.add_subcondition(condition_execute.condition) # Adding only the condition here

# Fulfill the abort branch
fulfillment_abort = cc.ThresholdSha256Fulfillment(threshold=2)
subfulfillment_testuser2.sign(tx_escrow_abort_fulfillment_message, crypto.SigningKey(testuser2_priv))
fulfillment_abort.add_subfulfillment(subfulfillment_testuser2)
fulfillment_abort.add_subfulfillment(subfulfillment_timeout_inverted)
escrow_fulfillment.add_subfulfillment(fulfillment_abort)

# Update the abort transaction with the fulfillment
tx_escrow_abort['transaction']['fulfillments'][0]['fulfillment'] = escrow_fulfillment.serialize_uri()

The following demonstrates that the transaction validation switches once the timeout occurs:

for i in range(time_sleep - 4):
    valid_execute = b.is_valid_transaction(tx_escrow_execute) == tx_escrow_execute
    valid_abort = b.is_valid_transaction(tx_escrow_abort) == tx_escrow_abort

    seconds_to_timeout = int(float(time_expire) - float(util.timestamp()))
    print('tx_execute valid: {} - tx_abort valid {} ({}s to timeout)'.format(valid_execute, valid_abort, seconds_to_timeout))
    sleep(1)

If you execute in a timely fashion, you should see the following:

tx_execute valid: True - tx_abort valid False (3s to timeout)
tx_execute valid: True - tx_abort valid False (2s to timeout)
tx_execute valid: True - tx_abort valid False (1s to timeout)
tx_execute valid: True - tx_abort valid False (0s to timeout)
tx_execute valid: False - tx_abort valid True (0s to timeout)
tx_execute valid: False - tx_abort valid True (-1s to timeout)
tx_execute valid: False - tx_abort valid True (-2s to timeout)
tx_execute valid: False - tx_abort valid True (-3s to timeout)

Of course, when the execute transaction was accepted in-time by bigchaindb, then writing the abort transaction after expiry will yield a Doublespend error.

Initial Checklist¶

• Do you have a governance process for making federation-level decisions, such as how to admit new members?
• What will you store in creation transactions (data payload)? Is there a data schema?
• Will you use transfer transactions? Will they include a non-empty data payload?
• Who will be allowed to submit transactions? Who will be allowed to read or query transactions? How will you enforce the access rules?

Set Up the Initial Cluster¶

The federation must decide some things before setting up the initial cluster (initial set of BigchainDB nodes):

1. Who will operate a node in the initial cluster?
2. What will the replication factor be? (It must be 3 or more for RethinkDB failover to work.)
3. Which node will be responsible for sending the commands to configure the RethinkDB database?

Once those things have been decided, each node operator can begin setting up their BigchainDB (production) node.

Each node operator will eventually need two pieces of information from all other nodes in the federation:

1. Their RethinkDB hostname, e.g. rdb.farm2.organization.org
2. Their BigchainDB public key, e.g. Eky3nkbxDTMgkmiJC8i5hKyVFiAQNmPP4a2G4JdDxJCK

RethinkDB’s Replication as a form of Backup¶

RethinkDB already has internal replication: every document is stored on R different nodes, where R is the replication factor (set using bigchaindb set-replicas R). Those replicas can be thought of as “live backups” because if one node goes down, the cluster will continue to work and no data will be lost.

At this point, there should be someone saying, “But replication isn’t backup!“

It’s true. Replication alone isn’t enough, because something bad might happen inside the database, and that could affect the replicas. For example, what if someone logged in as a RethinkDB admin and did a “drop table”? We currently plan for each node to be protected by a next-generation firewall (or something similar) to prevent such things from getting very far. For example, see issue #240.

Nevertheless, you should still consider having normal, “cold” backups, because bad things can still happen.

Live Replication of RethinkDB Data Files¶

Each BigchainDB node stores its subset of the RethinkDB data in one directory. You could set up the node’s file system so that directory lives on its own hard drive. Furthermore, you could make that hard drive part of a RAID array, so that a second hard drive would always have a copy of the original. If the original hard drive fails, then the second hard drive could take its place and the node would continue to function. Meanwhile, the original hard drive could be replaced.

That’s just one possible way of setting up the file system so as to provide extra reliability.

Another way to get similar reliability would be to mount the RethinkDB data directory on an Amazon EBS volume. Each Amazon EBS volume is, “automatically replicated within its Availability Zone to protect you from component failure, offering high availability and durability.”

See the section on setting up storage for RethinkDB for more details.

As with shard replication, live file-system replication protects against many failure modes, but it doesn’t protect against them all. You should still consider having normal, “cold” backups.

rethinkdb dump (to a File)¶

RethinkDB can create an archive of all data in the cluster (or all data in specified tables), as a compressed file. According to the RethinkDB blog post when that functionality became available:

Since the backup process is using client drivers, it automatically takes advantage of the MVCC [multiversion concurrency control] functionality built into RethinkDB. It will use some cluster resources, but will not lock out any of the clients, so you can safely run it on a live cluster.

To back up all the data in a BigchainDB cluster, the RethinkDB admin user must run a command like the following on one of the nodes:

rethinkdb dump -e bigchain.bigchain -e bigchain.votes

That should write a file named rethinkdb_dump_<date>_<time>.tar.gz. The -e option is used to specify which tables should be exported. You probably don’t need to export the backlog table, but you definitely need to export the bigchain and votes tables. bigchain.votes means the votes table in the RethinkDB database named bigchain. It’s possible that your database has a different name: the database name is a BigchainDB configuration setting. The default name is bigchain. (Tip: you can see the values of all configuration settings using the bigchaindb show-config command.)

There’s more information about the rethinkdb dump command in the RethinkDB documentation. It also explains how to restore data to a cluster from an archive file.

Notes

• If the rethinkdb dump subcommand fails and the last line of the Traceback says “NameError: name ‘file’ is not defined”, then you need to update your RethinkDB Python driver; do a pip install --upgrade rethinkdb
• It might take a long time to backup data this way. The more data, the longer it will take.
• You need enough free disk space to store the backup file.
• If a document changes after the backup starts but before it ends, then the changed document may not be in the final backup. This shouldn’t be a problem for BigchainDB, because blocks and votes can’t change anyway.
• rethinkdb dump saves data and secondary indexes, but does not save cluster metadata. You will need to recreate your cluster setup yourself after you run rethinkdb restore.
• RethinkDB also has subcommands to import/export collections of JSON or CSV files. While one could use those for backup/restore, it wouldn’t be very practical.

Client-Side Backup¶

In the future, it will be possible for clients to query for the blocks containing the transactions they care about, and for the votes on those blocks. They could save a local copy of those blocks and votes.

How could we be sure blocks and votes from a client are valid?

All blocks and votes are signed by federation nodes. Only federation nodes can produce valid signatures because only federation nodes have the necessary private keys. A client can’t produce a valid signature for a block or vote.

Could we restore an entire BigchainDB database using client-saved blocks and votes?

Yes, in principle, but it would be difficult to know if you’ve recovered every block and vote. Votes link to the block they’re voting on and to the previous block, so one could detect some missing blocks. It would be difficult to know if you’ve recovered all the votes.

Backup by Copying RethinkDB Data Files¶

It’s possible to back up a BigchainDB database by creating a point-in-time copy of the RethinkDB data files (on all nodes, at roughly the same time). It’s not a very practical approach to backup: the resulting set of files will be much larger (collectively) than what one would get using rethinkdb dump, and there are no guarantees on how consistent that data will be, especially for recently-written data.

If you’re curious about what’s involved, see the MongoDB documentation about “Backup by Copying Underlying Data Files”. (Yes, that’s documentation for MongoDB, but the principles are the same.)

See the last subsection of this page for a better way to use this idea.

Incremental or Continuous Backup¶

Incremental backup is where backup happens on a regular basis (e.g. daily), and each one only records the changes since the last backup.

Continuous backup might mean incremental backup on a very regular basis (e.g. every ten minutes), or it might mean backup of every database operation as it happens. The latter is also called transaction logging or continuous archiving.

At the time of writing, RethinkDB didn’t have a built-in incremental or continuous backup capability, but the idea was raised in RethinkDB issues #89 and #5890. On July 5, 2016, Daniel Mewes (of RethinkDB) wrote the following comment on issue #5890: “We would like to add this feature [continuous backup], but haven’t started working on it yet.”

To get a sense of what continuous backup might look like for RethinkDB, one can look at the continuous backup options available for MongoDB. MongoDB, the company, offers continuous backup with Ops Manager (self-hosted) or Cloud Manager (fully managed). Features include:

• It “continuously maintains backups, so if your MongoDB deployment experiences a failure, the most recent backup is only moments behind...”
• It “offers point-in-time backups of replica sets and cluster-wide snapshots of sharded clusters. You can restore to precisely the moment you need, quickly and safely.”
• “You can rebuild entire running clusters, just from your backups.”
• It enables, “fast and seamless provisioning of new dev and test environments.”

The MongoDB documentation has more details about how Ops Manager Backup works.

Considerations for BigchainDB:

• We’d like the cost of backup to be low. To get a sense of the cost, MongoDB Cloud Manager backup costed $30 / GB / year prepaid. One thousand gigabytes backed up (i.e. about a terabyte) would cost 30 thousand US dollars per year. (That’s just for the backup; there’s also a cost per server per year.)
• We’d like the backup to be decentralized, with no single point of control or single point of failure. (Note: some file systems have a single point of failure. For example, HDFS has one Namenode.)
• We only care to back up blocks and votes, and once written, those never change. There are no updates or deletes, just new blocks and votes.

Combining RethinkDB Replication with Storage Snapshots¶

Although it’s not advertised as such, RethinkDB’s built-in replication feature is similar to continous backup, except the “backup” (i.e. the set of replica shards) is spread across all the nodes. One could take that idea a bit farther by creating a set of backup-only servers with one full backup:

• Give all the original BigchainDB nodes (RethinkDB nodes) the server tag original. This is the default if you used the RethinkDB config file suggested in the section titled Configure RethinkDB Server.
• Set up a group of servers running RethinkDB only, and give them the server tag backup. The backup servers could be geographically separated from all the original nodes (or not; it’s up to the federation).
• Clients shouldn’t be able to read from or write to servers in the backup set.
• Send a RethinkDB reconfigure command to the RethinkDB cluster to make it so that the original set has the same number of replicas as before (or maybe one less), and the backup set has one replica. Also, make sure the primary_replica_tag='original' so that all primary shards live on the original nodes.

The RethinkDB documentation on sharding and replication has the details of how to set server tags and do RethinkDB reconfiguration.

Once you’ve set up a set of backup-only RethinkDB servers, you could make a point-in-time snapshot of their storage devices, as a form of backup.

You might want to disconnect the backup set from the original set first, and then wait for reads and writes in the backup set to stop. (The backup set should have only one copy of each shard, so there’s no opportunity for inconsistency between shards of the backup set.)

You will want to re-connect the backup set to the original set as soon as possible, so it’s able to catch up.

If something bad happens to the entire original BigchainDB cluster (including the backup set) and you need to restore it from a snapshot, you can, but before you make BigchainDB live, you should 1) delete all entries in the backlog table, 2) delete all blocks after the last voted-valid block, 3) delete all votes on the blocks deleted in part 2, and 4) rebuild the RethinkDB indexes.

NOTE: Sometimes snapshots are incremental. For example, Amazon EBS snapshots are incremental, meaning “only the blocks on the device that have changed after your most recent snapshot are saved. This minimizes the time required to create the snapshot and saves on storage costs.” [Emphasis added]

Why?¶

Why would anyone want to deploy a centrally-controlled BigchainDB cluster? Isn’t BigchainDB supposed to be decentralized, where each node is controlled by a different person or organization?

Yes! These scripts are for deploying a testing cluster, not a production cluster.

How?¶

We use some Bash and Python scripts to launch several instances (virtual servers) on Amazon Elastic Compute Cloud (EC2). Then we use Fabric to install RethinkDB and BigchainDB on all those instances.

Python Setup¶

The instructions that follow have been tested on Ubuntu 14.04, but may also work on similar distros or operating systems.

Note: Our Python scripts for deploying to AWS use Python 2 because Fabric doesn’t work with Python 3.

Maybe create a Python 2 virtual environment and activate it. Then install the following Python packages (in that virtual environment):

pip install fabric fabtools requests boto3 awscli

What did you just install?

• “Fabric is a Python (2.5-2.7) library and command-line tool for streamlining the use of SSH for application deployment or systems administration tasks.”
• fabtools are “tools for writing awesome Fabric files”
• requests is a Python package/library for sending HTTP requests
• “Boto is the Amazon Web Services (AWS) SDK for Python, which allows Python developers to write software that makes use of Amazon services like S3 and EC2.” (boto3 is the name of the latest Boto package.)
• The aws-cli package, which is an AWS Command Line Interface (CLI).

Basic AWS Setup¶

See the page about basic AWS Setup in the Appendices.

Get Enough Amazon Elastic IP Addresses¶

The AWS cluster deployment scripts use elastic IP addresses (although that may change in the future). By default, AWS accounts get five elastic IP addresses. If you want to deploy a cluster with more than five nodes, then you will need more than five elastic IP addresses; you may have to apply for those; see the AWS documentation on elastic IP addresses.

Create an Amazon EC2 Security Group¶

Go to the AWS EC2 Console and select “Security Groups” in the left sidebar. Click the “Create Security Group” button. Name it bigchaindb. The description probably doesn’t matter; you can also put bigchaindb for that.

Add these rules for Inbound traffic:

• Type = All TCP, Protocol = TCP, Port Range = 0-65535, Source = 0.0.0.0/0
• Type = SSH, Protocol = SSH, Port Range = 22, Source = 0.0.0.0/0
• Type = All UDP, Protocol = UDP, Port Range = 0-65535, Source = 0.0.0.0/0
• Type = All ICMP, Protocol = ICMP, Port Range = 0-65535, Source = 0.0.0.0/0

Note: These rules are extremely lax! They’re meant to make testing easy. For example, Source = 0.0.0.0/0 is CIDR notation for “allow this traffic to come from any IP address.”

Deploy a BigchainDB Monitor¶

This step is optional.

One way to monitor a BigchainDB cluster is to use the monitoring setup described in the Monitoring section of this documentation. If you want to do that, then you may want to deploy the monitoring server first, so you can tell your BigchainDB nodes where to send their monitoring data.

You can deploy a monitoring server on AWS. To do that, go to the AWS EC2 Console and launch an instance:

1. Choose an AMI: select Ubuntu Server 14.04 LTS.
2. Choose an Instance Type: a t2.micro will suffice.
3. Configure Instance Details: you can accept the defaults, but feel free to change them.
4. Add Storage: A “Root” volume type should already be included. You could store monitoring data there (e.g. in a folder named /influxdb-data) but we will attach another volume and store the monitoring data there instead. Select “Add New Volume” and an EBS volume type.
5. Tag Instance: give your instance a memorable name.
6. Configure Security Group: choose your bigchaindb security group.
7. Review and launch your instance.

When it asks, choose an existing key pair: the one you created earlier (named bigchaindb).

Give your instance some time to launch and become able to accept SSH connections. You can see its current status in the AWS EC2 Console (in the “Instances” section). SSH into your instance using something like:

cd deploy-cluster-aws
ssh -i pem/bigchaindb.pem ubuntu@ec2-52-58-157-229.eu-central-1.compute.amazonaws.com

where ec2-52-58-157-229.eu-central-1.compute.amazonaws.com should be replaced by your new instance’s EC2 hostname. (To get that, go to the AWS EC2 Console, select Instances, click on your newly-launched instance, and copy its “Public DNS” name.)

Next, create a file system on the attached volume, make a directory named /influxdb-data, and set the attached volume’s mount point to be /influxdb-data. For detailed instructions on how to do that, see the AWS documentation for Making an Amazon EBS Volume Available for Use.

Then install Docker and Docker Compose:

# in a Python 2.5-2.7 virtual environment where fabric, boto3, etc. are installed
fab --fabfile=fabfile-monitor.py --hosts=<EC2 hostname> install_docker

After Docker is installed, we can run the monitor with:

fab --fabfile=fabfile-monitor.py --hosts=<EC2 hostname> run_monitor

For more information about monitoring (e.g. how to view the Grafana dashboard in your web browser), see the Monitoring section of this documentation.

To configure a BigchainDB node to send monitoring data to the monitoring server, change the statsd host in the configuration of the BigchainDB node. The section on Configuring a BigchainDB Node explains how you can do that. (For example, you can change the statsd host in $HOME/.bigchaindb.)

Deploy a BigchainDB Cluster¶

# in a Python 3 virtual environment where bigchaindb is installed
cd bigchaindb
cd deploy-cluster-aws
./make_confiles.sh confiles 3

NUM_NODES=3
BRANCH="master"
WHAT_TO_DEPLOY="servers"
SSH_KEY_NAME="not-set-yet"
USE_KEYPAIRS_FILE=False
IMAGE_ID="ami-accff2b1"
INSTANCE_TYPE="m3.2xlarge"
USING_EBS=False
EBS_VOLUME_SIZE=30
EBS_OPTIMIZED=False

# in a Python 3 virtual environment where bigchaindb is installed
cd bigchaindb
cd deploy-cluster-aws
python3 write_keypairs_file.py 100

# in a Python 2.5-2.7 virtual environment where fabric, boto3, etc. are installed
cd bigchaindb
cd deploy-cluster-aws
./awsdeploy.sh my_deploy_conf.py
# Only if you want to set the replication factor to 3
fab set_replicas:3
# Only if you want to start BigchainDB on all the nodes:
fab start_bigchaindb

ssh -i pem/bigchaindb.pem ubuntu@ec2-52-29-197-211.eu-central-1.compute.amazonaws.com

ip addr show
sudo service rethinkdb status
bigchaindb --help
bigchaindb show-config

Server Monitoring with New Relic¶

New Relic is a business that provides several monitoring services. One of those services, called Server Monitoring, can be used to monitor things like CPU usage and Network I/O on BigchainDB instances. To do that:

1. Sign up for a New Relic account
2. Get your New Relic license key
3. Put that key in an environment variable named NEWRELIC_KEY. For example, you might add a line like the following to your ~/.bashrc file (if you use Bash): export NEWRELIC_KEY=<insert your key here>
4. Once you’ve deployed a BigchainDB cluster on AWS as above, you can install a New Relic system monitor (agent) on all the instances using:

# in a Python 2.5-2.7 virtual environment where fabric, boto3, etc. are installed
fab install_newrelic

Once the New Relic system monitor (agent) is installed on the instances, it will start sending server stats to New Relic on a regular basis. It may take a few minutes for data to show up in your New Relic dashboard (under New Relic Servers).

Shutting Down a Cluster¶

There are fees associated with running instances on EC2, so if you’re not using them, you should terminate them. You can do that using the AWS EC2 Console.

The same is true of your allocated elastic IP addresses. There’s a small fee to keep them allocated if they’re not associated with a running instance. You can release them using the AWS EC2 Console, or by using a handy little script named release_eips.py. For example:

$ python release_eips.py
You have 2 allocated elactic IPs which are not associated with instances
0: Releasing 52.58.110.110
(It has Domain = vpc.)
1: Releasing 52.58.107.211
(It has Domain = vpc.)

Known Deployment Issues¶

NetworkError: Host key for ec2-xx-xx-xx-xx.eu-central-1.compute.amazonaws.com 
did not match pre-existing key! Server's key was changed recently, or possible 
man-in-the-middle attack.

mv ~/.ssh/known_hosts ~/.ssh/old_known_hosts

BigchainDB Integration with Other Blockchains¶

BigchainDB works with the Interledger protocol, enabling the transfer of assets between BigchainDB and other blockchains, ledgers, and payment systems.

We’re actively exploring ways that BigchainDB can be used with other blockchains and platforms.

Some Words of Caution¶

BigchainDB is still in the early stages of development. The data models described below may change substantially before BigchainDB reaches a production-ready state (i.e. version 1.0 and higher).

Transaction Concepts¶

Transactions are the most basic kind of record stored by BigchainDB. There are two kinds: creation transactions and transfer transactions.

A creation transaction can be used to register, issue, create or otherwise initiate the history of a single thing (or asset) in BigchainDB. For example, one might register an identity or a creative work. The things are often called “assets” but they might not be literal assets. A creation transaction also establishes the initial owner or owners of the asset. Only a federation node can create a valid creation transaction (but it’s usually made based on a message from a client).

Currently, BigchainDB only supports indivisible assets. You can’t split an asset apart into multiple assets, nor can you combine several assets together into one. Issue #129 is an enhancement proposal to support divisible assets.

A transfer transaction can transfer one or more assets to new owners.

BigchainDB works with the Interledger Protocol (ILP), a protocol for transferring assets between different ledgers, blockchains or payment systems.

The owner(s) of an asset can specifiy conditions (ILP crypto-conditions) which others must fulfill (satisfy) in order to become the new owner(s) of the asset. For example, a crypto-condition might require a signature from the owner, or from m-of-n owners (a threshold condition, e.g. 3-of-4).

When someone creates a transfer transaction with the goal of changing an asset’s owners, they must fulfill the asset’s current crypto-conditions (i.e. in a fulfillment), and they must provide new conditions (including the list of new owners).

Every create transaction contains exactly one fulfillment-condition pair. A transfer transaction can contain multiple fulfillment-condition pairs: one per asset transferred. Every fulfillment in a transfer transaction (input) must correspond to a condition (output) in a previous transaction. The diagram below illustrates some of these concepts: transactions are represented by light grey boxes, fulfillments have a label like f:0, and conditions have a label like c:0.

To determine the current owner(s) of an asset, find the most recent valid transaction involving it, and then look at the list of owners in the conditions (not the fulfillments).

The Transaction Model¶

{
    "id": "<hash of transaction, excluding signatures (see explanation)>",
    "transaction": {
        "version": "<version number of the transaction model>",
        "fulfillments": ["<list of fulfillments>"],
        "conditions": ["<list of conditions>"],
        "operation": "<string>",
        "timestamp": "<timestamp from client>",
        "data": {
            "uuid": "<uuid4>",
            "payload": "<any JSON document>"
        }
    }
}

Here’s some explanation of the contents of a transaction:

• id: The hash of everything inside the serialized transaction body (i.e. fulfillments, conditions, operation, timestamp and data; see below), with one wrinkle: for each fulfillment in fulfillments, fulfillment is set to null. The id is also the database primary key.
• transaction:
  • version: Version number of the transaction model, so that software can support different transaction models.
  • fulfillments: List of fulfillments. Each fulfillment contains a pointer to an unspent asset and a crypto fulfillment that satisfies a spending condition set on the unspent asset. A fulfillment is usually a signature proving the ownership of the asset. See Conditions and Fulfillments below.
  • conditions: List of conditions. Each condition is a crypto-condition that needs to be fulfilled by a transfer transaction in order to transfer ownership to new owners. See Conditions and Fulfillments below.
  • operation: String representation of the operation being performed (currently either “CREATE” or “TRANSFER”). It determines how the transaction should be validated.
  • timestamp: The Unix time when the transaction was created. It’s provided by the client. See the section on timestamps.
  • data:
    • uuid: UUID version 4 (random) converted to a string of hex digits in standard form.
    • payload: Can be any JSON document. It may be empty in the case of a transfer transaction.

Later, when we get to the models for the block and the vote, we’ll see that both include a signature (from the node which created it). You may wonder why transactions don’t have signatures... The answer is that they do! They’re just hidden inside the fulfillment string of each fulfillment. A creation transaction is signed by the node that created it. A transfer transaction is signed by whoever currently controls or owns it.

What gets signed? For each fulfillment in the transaction, the “fullfillment message” that gets signed includes the operation, timestamp, data, version, id, corresponding condition, and the fulfillment itself, except with its fulfillment string set to null. The computed signature goes into creating the fulfillment string of the fulfillment.

One other note: Currently, transactions contain only the public keys of asset-owners (i.e. who own an asset or who owned an asset in the past), inside the conditions and fulfillments. A transaction does not contain the public key of the client (computer) which generated and sent it to a BigchainDB node. In fact, there’s no need for a client to have a public/private keypair. In the future, each client may also have a keypair, and it may have to sign each sent transaction (using its private key); see Issue #347 on GitHub. In practice, a person might think of their keypair as being both their “ownership-keypair” and their “client-keypair,” but there is a difference, just like there’s a difference between Joe and Joe’s computer.

Conditions and Fulfillments¶

To create a transaction that transfers an asset to new owners, one must fulfill the asset’s current conditions (crypto-conditions). The most basic kinds of conditions are:

• A hashlock condition: One can fulfill a hashlock condition by providing the correct “preimage” (similar to a password or secret phrase)
• A simple signature condition: One can fulfill a simple signature condition by a providing a valid cryptographic signature (i.e. corresponding to the public key of an owner, usually)
• A timeout condition: Anyone can fulfill a timeout condition before the condition’s expiry time. After the expiry time, nobody can fulfill the condition. Another way to say this is that a timeout condition’s fulfillment is valid (TRUE) before the expiry time and invalid (FALSE) after the expiry time. Note: at the time of writing, timeout conditions are BigchainDB-specific (i.e. not part of the Interledger specs).

A more complex condition can be composed by using n of the above conditions as inputs to an m-of-n threshold condition (a logic gate which outputs TRUE iff m or more inputs are TRUE). If there are n inputs to a threshold condition:

• 1-of-n is the same as a logical OR of all the inputs
• n-of-n is the same as a logical AND of all the inputs

For example, one could create a condition requiring that m (of n) owners provide signatures before their asset can be transferred to new owners.

One can also put different weights on the inputs to threshold condition, along with a threshold that the weighted-sum-of-inputs must pass for the output to be TRUE. Weights could be used, for example, to express the number of shares that someone owns in an asset.

The (single) output of a threshold condition can be used as one of the inputs of other threshold conditions. This means that one can combine threshold conditions to build complex logical expressions, e.g. (x OR y) AND (u OR v).

Aside: In BigchainDB, the output of an m-of-n threshold condition can be inverted on the way out, so an output that would have been TRUE would get changed to FALSE (and vice versa). This enables the creation of NOT, NOR and NAND gates. At the time of writing, this “inverted threshold condition” is BigchainDB-specific (i.e. not part of the Interledger specs). It should only be used in combination with a timeout condition.

When one creates a condition, one can calculate its fulfillment length (e.g. 96). The more complex the condition, the larger its fulfillment length will be. A BigchainDB federation can put an upper limit on the allowed fulfillment length, as a way of capping the complexity of conditions (and the computing time required to validate them).

If someone tries to make a condition where the output of a threshold condition feeds into the input of another “earlier” threshold condition (i.e. in a closed logical circuit), then their computer will take forever to calculate the (infinite) “condition URI”, at least in theory. In practice, their computer will run out of memory or their client software will timeout after a while.

Aside: In what follows, the list of owners_after (in a condition) is always who owned the asset at the time the transaction completed, but before the next transaction started. The list of owners_before (in a fulfillment) is always equal to the list of owners_after in that asset’s previous transaction.

{
    "cid": "<condition index>",
    "condition": {
        "details": {
            "bitmask": "<base16 int>",
            "public_key": "<new owner public key>",
            "signature": null,
            "type": "fulfillment",
            "type_id": "<base16 int>"
        },
        "uri": "<string>"
    },
    "owners_after": ["<new owner public key>"]
}

{
    "cid": "<condition index>",
    "condition": {
        "details": {
            "bitmask": 41,
            "subfulfillments": [
                {
                    "bitmask": 32,
                    "public_key": "<new owner 1 public key>",
                    "signature": null,
                    "type": "fulfillment",
                    "type_id": 4,
                    "weight": 1
                },
                {
                    "bitmask": 32,
                    "public_key": "<new owner 2 public key>",
                    "signature": null,
                    "type": "fulfillment",
                    "type_id": 4,
                    "weight": 1
                }
            ],
            "threshold": 2,
            "type": "fulfillment",
            "type_id": 2
        },
        "uri": "cc:2:29:ytNK3X6-bZsbF-nCGDTuopUIMi1HCyCkyPewm6oLI3o:206"},
        "owners_after": [
            "owner 1 public key>",
            "owner 2 public key>"
        ]
}

{
    "owners_before": ["<public key of the owner before the transaction happened>"],
    "fid": 0,
    "fulfillment": "cf:4:RxFzIE679tFBk8zwEgizhmTuciAylvTUwy6EL6ehddHFJOhK5F4IjwQ1xLu2oQK9iyRCZJdfWAefZVjTt3DeG5j2exqxpGliOPYseNkRAWEakqJ_UrCwgnj92dnFRAEE",
    "input": {
        "cid": 0,
        "txid": "11b3e7d893cc5fdfcf1a1706809c7def290a3b10b0bef6525d10b024649c42d3"
    }
}

The Block Model¶

{
    "id": "<hash of block>",
    "block": {
        "timestamp": "<block-creation 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 block>",
}

• id: The hash of the serialized block (i.e. the timestamp, transactions, node_pubkey, and voters). This is also a database primary key; that’s how we ensure that all blocks are unique.
• block:
  • timestamp: The Unix time when the block was created. It’s provided by the node that created the block. See the section on timestamps.
  • transactions: A list of the transactions included in the block.
  • node_pubkey: The public key of the node that create the block.
  • voters: A list of public keys of 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 at 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. (To create the signature, the node serializes the block contents and signs that with its private key.)

The Vote Model¶

Each node must generate a vote for each block, to be appended the votes table. A vote has the following structure:

{
    "id": "<RethinkDB-generated ID for the vote>",
    "node_pubkey": "<the public key 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": "<Unix time when the vote was generated, provided by the voting node>"
    },
    "signature": "<signature of vote>",
}

Note: The invalid_reason was not being used as of v0.1.3 and may be dropped in a future version of BigchainDB.

Timestamp Sources & Accuracy¶

A transaction’s timestamp is provided by the client which created and submitted the transaction to a BigchainDB node. A block’s timestamp is provided by the BigchainDB node which created the block. A vote’s timestamp is provided by the BigchainDB node which created the vote.

When a BigchainDB client or node needs a timestamp, it calls a BigchainDB utility function named timestamp(). There’s a detailed explanation of how that function works below, but the short version is that it gets the Unix time from its system clock, rounded to the nearest second.

We can’t say anything about the accuracy of the system clock on clients. Timestamps from clients are still potentially useful, however, in a statistical sense. We say more about that below.

We advise BigchainDB nodes to run special software (an “NTP daemon”) to keep their system clock in sync with standard time servers. (NTP stands for Network Time Protocol.)

Converting Timestamps to UTC¶

To convert a BigchainDB timestamp (a Unix time) to UTC, you need to know how the node providing the timestamp was set up. That’s because different setups will report a different “Unix time” value around leap seconds! There’s a nice Red Hat Developer Blog post about the various setup options. If you want more details, see David Mills’ pages about leap seconds, NTP, etc. (David Mills designed NTP.)

We advise BigchainDB nodes to run an NTP daemon with particular settings, so that their timestamps are consistent.

If a timestamp comes from a node that’s set up as we advise, it can be converted to UTC as follows:

1. Use a standard “Unix time to UTC” converter to get a UTC timestamp.
2. Is the UTC timestamp a leap second, or the second before/after a leap second? There’s a list of all the leap seconds on Wikipedia.
3. If no, then you are done.
4. If yes, then it might not be possible to convert it to a single UTC timestamp. Even if it can’t be converted to a single UTC timestamp, it can be converted to a list of two possible UTC timestamps. Showing how to do that is beyond the scope of this documentation. In all likelihood, you will never have to worry about leap seconds because they are very rare. (There were only 26 between 1972 and the end of 2015.)

Calculating Elapsed Time Between Two Timestamps¶

There’s another gotcha with (Unix time) timestamps: you can’t calculate the real-world elapsed time between two timestamps (correctly) by subtracting the smaller timestamp from the larger one. The result won’t include any of the leap seconds that occured between the two timestamps. You could look up how many leap seconds happened between the two timestamps and add that to the result. There are many library functions for working with timestamps; those are beyond the scope of this documentation.

Avoid Doing Transactions Around Leap Seconds¶

Because of the ambiguity and confusion that arises with Unix time around leap seconds, we advise users to avoid creating transactions around leap seconds.

Interpreting Sets of Timestamps¶

You can look at many timestamps to get a statistical sense of when something happened. For example, a transaction in a decided-valid block has many associated timestamps:

• its own timestamp
• the timestamps of the other transactions in the block; there could be as many as 999 of those
• the timestamp of the block
• the timestamps of all the votes on the block

Those timestamps come from many sources, so you can look at all of them to get some statistical sense of when the transaction “actually happened.” The timestamp of the block should always be after the timestamp of the transaction, and the timestamp of the votes should always be after the timestamp of the block.

How BigchainDB Uses Timestamps¶

BigchainDB doesn’t use timestamps to determine the order of transactions or blocks. In particular, the order of blocks is determined by RethinkDB’s changefeed on the bigchain table.

BigchainDB does use timestamps for some things. It uses them to determine if a transaction has been waiting in the backlog for too long (i.e. because the node assigned to it hasn’t handled it yet). It also uses timestamps to determine the status of timeout conditions (used by escrow).

Including Trusted Timestamps¶

If you want to create a transaction payload with a trusted timestamp, you can.

One way to do that would be to send a payload to a trusted timestamping service. They will send back a timestamp, a signature, and their public key. They should also explain how you can verify the signature. You can then include the original payload, the timestamp, the signature, and the service’s public key in your transaction. That way, anyone with the verification instructions can verify that the original payload was signed by the trusted timestamping service.

How the timestamp() Function Works¶

BigchainDB has a utility function named timestamp() which amounts to:

timestamp() = str(round(time.time()))

In other words, it calls the time() function in Python’s time module, rounds that to the nearest integer, and converts the result to a string.

It rounds the output of time.time() to the nearest second because, according to the Python documentation for time.time(), ”...not all systems provide time with a better precision than 1 second.”

How does time.time() work? If you look in the C source code, it calls floattime() and floattime() calls clock_gettime(), if it’s available.

ret = clock_gettime(CLOCK_REALTIME, &tp);

With CLOCK_REALTIME as the first argument, it returns the “Unix time.” (“Unix time” is in quotes because its value around leap seconds depends on how the system is set up; see above.)

Why Not Use UTC, TAI or Some Other Time that Has Unambiguous Timestamps for Leap Seconds?¶

It would be nice to use UTC or TAI timestamps, but unfortunately there’s no commonly-available, standard way to get always-accurate UTC or TAI timestamps from the operating system on typical computers today (i.e. accurate around leap seconds).

There are commonly-available, standard ways to get the “Unix time,” such as clock_gettime() function available in C. That’s what we use (indirectly via Python). (“Unix time” is in quotes because its value around leap seconds depends on how the system is set up; see above.)

The Unix-time-based timestamps we use are only ambiguous circa leap seconds, and those are very rare. Even for those timestamps, the extra uncertainty is only one second, and that’s not bad considering that we only report timestamps to a precision of one second in the first place. All other timestamps can be converted to UTC with no ambiguity.

Pull and Run the Image from Docker Hub¶

Assuming you have Docker installed, you would proceed as follows.

In a terminal shell, pull the latest version of the BigchainDB Docker image using:

docker pull bigchaindb/bigchaindb

then do a one-time configuration step to create the config file; we will use the -y option to accept all the default values. The configuration file will be stored in a file on your host machine at ~/bigchaindb_docker/.bigchaindb: