BigchainDB: A hands-on approach

A small tutorial that should get you going with blockchain technology.

If you just want to just see the POC, click here.

In my last blogpost, I gave a small introduction about BigchainDB and the concept of transactions. Today we’ll build a small Proof of Concept to get you started with this new technology!

original: Carl Wycoff — Flickr

Use Case: Farm to Fork 🍖

Last week, there was a huge scandal in Belgium over the meat industry. A meat processing company was accused of fraudulent practices; reuse of overdue meat, which posed a great risk to consumer health. Although there were reports of the negative practices of this business in the past, the official instances that are accountable for auditing the food-related economy didn’t act on them.

These problems arise whenever a company can work without transparency to not only other businesses, but also to the government and the consumers. A solution to this could be to use asset control on BigchainDB. This way, a BigchainDB consortium could be set up to enable the government or other agencies (or even the consumer) to see exactly what has been done to the food on their plate.

In our tutorial, we’ll create a small POC that provides these functionalities:

• Creating assets: The introduction of a new ‘food-item’ that enters the food economy.
• Transferring assets: The food-item should be transferable to other companies up until it gets offered to the consumer.
• Updating assets: Data should be tied to food-items, so that firms can register what they did with the asset and other companies can see what actions have been performed with or on the food-item in the past.

If you are confused about something, you can always check out the code for this tutorial at my GitHub!

Project setup

Registering our application

For this POC, we will use the BigchainDB Test Network, which allows us to use an existing network instead of setting one up ourselves. Go to the signup page and create an account. After completing this step, you can create a new application; by doing this, the BigchainDB Testnet website will provide you with both an application ID and an application Key that you need to interact with the network.

Creating a new application on the BigchainDB Testnet.

Webpage

The focus of this tutorial isn’t webdesign, so I’ve decided to not include the code for this page. The code for the webpage can be found on the GitHub page of this project.

Dependencies

For connectivity to the BigchainDB network, we’ll use the js-bigchain-driver:

npm install bigchaindb-driver

For managing keypairs, we’ll use the bip39 library:

npm install bip39

If you ever need more information, you can checkout the official documentation.

We’ll also use the dotenvpackage to handle environment variables:

npm install dotenv --save

With dotenv we can create a .env file to store our variables in. This way, when we push our code to a remote repository, we don’t expose our personal details (such as passwords or, in this case, the app_id and app_key of our application):

APP_URL=https://test.bigchaindb.com/api/v1/
APP_ID=Get one on the website of BigchainDB
APP_KEY=Get one on the website of BigchainDB

We’ll create a javascript class to interact with the BigchainDB network. To use this file in a browser, we’ll need to bundle it with browserify:

npm install -g browserify

Because we will bundle our javascript code, we’ll need a dependency that allows browserify to include our .env variables:

npm install localenvify --save

Now, if we want our webpage to use our latest code, you simply have to execute the next command:

browserify js/FarmToFork.js -t localenvify -s ftf_module -o js/bundle.js

Javascript

Create a new javascript file that we’ll to interact with the network. The constructor will initialize a new connection and generate a keypair (we’ll write the method later) from the keySeed parameter. The keypair will be stored in this.currentIdentity and will be used throughout the tutorial as the identity we’ll use to perform actions on our own assets:

If you get confused during the tutorial, you can always check what to put where by looking at the latest version on GitHub. There’s also a javascript file that we’ll use to link our FarmToFork class with our webpage (after it has been bundled with browserify). The main focus of this tutorial isn’t working with Vue.js, so the code for this file can be found on the GitHub page of this project.

Implementing functionality

Keypairs

Transactions on BigchainDB are signed with private keys and outputs contain a (list of) public key(s). Storing public and private keys is a complex matter; luckily the bip39 package provides a method of generating keypairs by using a seed. This makes generating keypairs as easy as this:

The method for generating keypairs based on a supplied seed.

Creating food-items (CREATE transactions)

All data on the BigchainDB is stored in transactions. Each transaction contains an immutable asset, and can be chained to alter the state or information of this asset. In our POC, the food-items are assets and the actions we can perform on them (transport, processing, …) are transactions.

To introduce a food-item (an asset) on the market, we have to issue a CREATE-transaction, which can be created as follows using the js-bigchaindb-driver :

Your metadata and assetdata should always be a JSON object, otherwise you will get unexpected behavior (as I found out through tedious trial and error).

We can invoke this function (after bundling) like this:

ftfApp.farmToFork.createAsset("a cow").then( response => console.log(response) );

This will issue a CREATE transaction and log the created transaction to the console after successully posting it to the network.

Get a list of all your food-items

Transactions have outputs, which are the ‘receivers’ of the asset after the transaction has been issued. By filtering assets based on their output, we can retrieve all assets that currently reside in your BigchainDB ‘wallet’; these are the assets that you currently own.

Performing actions on food-items (TRANSFER transaction)

There are 2 things we can do to food-items: process them and transfer them to another firm. This functionality means we’ll have to append data; we’ll have to use TRANSFER transactions to build upon the existing transactions for a specific asset.

First, we’ll implement functionality to perform actions on them. An action is just a string that conveys what has been done to the asset. This will be encapsulated in a JSON-object along with the date of the action. This provides a simple format that can be read out later:

Now that we can perform actions on our assets, it’s time to implement the transferation of assets. In our POC, this is the equivalent of transferring a real food product to another firm so that they can further process it or further sell or distribute it.

The method of transferring the asset is almost the same as performing actions on them, but this time we’ll pass another public key to generate the transaction output with:

See a list of all assets in on the network

Now that we’ve implemented all this functionality, we’ll need to implement the most important part of this POC: a method to see the whole history of a certain asset. This will provide the transparency that will force companies to handle ethical business practices.

You probably noticed every time we added a new asset, we passed the string FtfTutorialAsset as a parameter. This string can be used to retrieve a list of assets in order to extract assets to query for their transaction history:

When we extract the asset ID from an asset in the retrieved list, we can request a complete list of transactions by using this method provided by the js-bigchaindb-driver:

connection.listTransactions(YOUR-ASSET-ID).then(response => console.log(response) );

Of course, you’ll want to format it into a nice user interface, but that’s outside the scope of this tutorial. However, you can see how it could look (in a rudimentary form) on the hosted gh-pages for this tutorial:

Conclusion

By combining the information provided by the BigchainDB js-driver documentation and the intuitive explanations of the Hitchhiker’s guide to BigchainDB, there is enough supporting material available to begin creating full-blown applications that can be used to solve problems in the real world.

Hopefully, this tutorial is a useful guide that will help you and the community to bootstrap your application development, and attract more interest in BigchainDB.