Hyperledger

This blog is meant to explain the differences between various types of blockchains. You might have heard about public, permissioned or private blockchain before, but what does that really mean?

Once this is settled, I will show you how to create your own permissioned network using Hyperledger Composer.

Motivation

There are two main reasons for this blog. One is that at SoftwareMill we are creating custom blockchain solutions for clients around the world and we explore all technical possibilities out there in order to be able to always provide the best solution available.

The second reason is that SoftwareMill’s team, which I had the pleasure to be part of, won HackYeah PKN Orlen’s challenge which the main goal was a development of loyalty program on the blockchain. We have chosen Hyperledger Composer and I wanted to share our experience.

Private vs Permissioned vs Public Blockchain

Public Blockchain

BTC

This is something we know and love (we love it, right? ;-) ). It is hard to find someone who has not heard about Bitcoin before. Most of the people heard about Ethereum as well. And You, my dear reader, have heard about them as well, I am sure!

Public blockchain is “simple” — it is a decentralized ledger on which you can write information. Every participant is equal (just like under communism — everyone is equal, except some people own most of the money ;-) ). Everyone, given they have enough built-in currency (like BTC or ETH), can send transactions anywhere and the optional smart contract executed by the transaction might optionally stop/modify the execution.

Public blockchain is, in theory, very safe. The more participants the network has, the more difficult it is to tamper with it. The built-in currencies are used as the incentive for the participants to join the network — if they commit their computing power, they might get some of the currency back as a reward.

You need to, of course, remember that even with modern sophisticated algorithms, the consensus protocols are liable for attacks, the smart contracts might have bugs which can be used to perform an attack so you are never 100% safe. Additionally, because the network is public, all information saved there is accessible to everyone.

Private Blockchain

Private blockchain has an owner that has full access to the ledger and in theory can tamper with whatever is stored in it. So in that sense the ledger is not truly decentralized, but it is using the mathematical theory behind the public blockchain to create a safe implementation of a database.

The participants of the private blockchain have to be invited and verified by the network owner.

This is a good solution for parties that are in agreement but are not in full trust between each-other. A good example here might be a supply chain.

Permissioned Blockchain

Finally, what You came for. The permissioned blockchain. It is something between the private and the public one. There is an admin of the network, the participants might be invited, but it can also be open to the public if the admin chooses so.

The participants of the network can be given specific permissions with different levels of access to different parts on the network. This will be cleared when you see examples from the Hyperledger Composer in the following sections.

TL;DR

To sum it up — if you need true decentralization and it’s difficult to gain trust from the users of your product — take a look at the public blockchain. If you want a secure database and your business needs to be “on the blockchain” (wink wink) — look at the private one. If you need a little bit of both — then permissioned might be the way to go.

Hyperledger

Now that we know, more or less, what are the dissimilarities between the various flavors of blockchain, let us take a look at the Hyperledger.

But what is Hyperledger?

It is an umbrella for many blockchain-related projects under The Linux Foundation. Right now, since no-one has not came up with The Right Use of Blockchain yet, there are thousands of companies investing gazillions of dollars, to be the first ones. And if you check out the Hyperledger website you will see all the big brands who are supporting the projects (in both money and engineering powers).

There are two projects we will look into today.

Hyperledger Fabric

Fabric is our blockchain. You can deploy nodes on the cloud or locally, using Docker or in bare JavaScript environment (node.js).

It has a fully customizable consensus algorithms, you can invite participants and give them specific access to parts of your network.

The assets on the network can be accessed via a JSON-based query language that is quite powerful.

You can connect to it from various APIs in various computer languages.

Hyperledger Composer

Fabric can do a lot, but for simple applications or PoCs you do not need to be on such a low level.

And here comes the Hyperledger Composer — a set of tools designed for rapid development of a blockchain network. It provides you with a DSL to specify the assets, the participants and the transactions. Smart contracts then are written in the lingua franca of today’s computer languages — the JavaScript :).

But how does it look like and what can we do with it?

Merchant Network

Ok, now, what are we trying to do? Our business case is quite simple — we will write a very naive implementation of asset tokens.

You can read more about them on our blog, but in layman terms those are tokens which are issued for a specific asset (yep :) I know — shocking!). The difference from other token types is that they kinda represent a share on a very specific item. It is not a share of business that sells art, but a share in a specific art piece.

It has ups and downs — if you own a share in the art selling business you will receive a dividend based on an average selling margins. But if you own a share in a specific art piece, if it performs — you might get very, very rich. If it does not — you might make nothing (or actually loose money).

There will be two actors on our network.

A Merchant — vetted by “our” company / owner of the blockchain, to make sure only real merchants can offer Mona Lisas and Sunflowers. They can list an art work on our system, issue tokens for it and name them. A merchant might decide to sell the art, removing it from the system.

A Person — our main user that will buy tokens for a specific art works and will be able to either agree to sell the work or not, when merchant calls for it.

What is important — we are just implementing the “storage” part of our system. Our solution will expose transactions via REST services that will have to be used by some other software that will implement the exchange of tokens, auctions of art works, user registration, merchant vetting etc. etc. etc. We will just provide a way to store all data on the blockchain.

Bootstrap the Network

First thing you need to do is to make sure the Hyperledger Composer and Fabric are working on your machine. Simply follow this user guide.

Once this is set up, create a new network by typing yo hyperledger-composer:businessnetwork . Call the network merchant-network and for the package use org.szimano.merchantnetwork (or whatever you prefer, just remember to update package name in the following examples).

Model

Once the network is bootstrapped, we can start writing the business logic. First thing we’re gonna write is the model. It consists of four things:

Participants that represent the actors of our system, but also provide granular access to it (when you connect to the blockchain you will be identified as one of the actors on the system). Assets which are the entities stored on the chain. Transactions which are the operations on the assets. Events that can be emitted during transactions for your applications to listen on.

The model file will start with the namespace defined.

So now let us start with the assets then. First one will be a very simple actor called Person .

Every asset has to have a primary key and we have added a name field. Fields are marked with o at the beginning.

The second actor will be our Merchant.

It extends the Person, so we do not need to specify the primary key (it will be inherited) and there is no extra information we need to store about the Merchant except them being the Merchant :)

Once the participants are settled, we will need to define our assets.

The first one will be the art work itself.

You can see there are two new things — keyword asset and a new ascii art arrow --> meaning a relation. The assets also needs a primary key plus we have added a description field on which we will store a human readable description of the art work.

Once we have the art, we can create an art token.

Those tokens have names, they are bound to an art work plus they are owned by a Person (which can be both Merchant and regular Person). The onSale , defaulted to false, will be used by the Person to mark their tokens as "ready to sale".

The assets are in place, now we need the transactions that will trigger the actions on our network.

First one is the transaction during which a Merchant will be able to list an art on the system.

Once the art is listed, we need a way of sending tokens between the users.

And finally, the merchant needs to have a way of selling the art work.

Now, when the model is ready, we need to implement how the system will run on top of it.

Queries

In the project root create a queries.qry file - you can define named queries that will use a SQL-like language. In our case we will need two - the ability to select all tokens for a given art and a given token owner:

and a second one to get all tokens for a given art:

If you know SQL (and I am pretty sure you do), the above looks very familiar. The _$VAR is a notation for passing external parameters to the query (more on the usage of those later).

Smart Contract (aka logic.js)

Now, that we have all the bits and pieces in place, we can create our “smart contract” that will list the art work on our system, issue tokens for it and assign them all to the merchant.

You need to start with a specially prepared comment with annotations (like xdocklet in Java that I was using when I started my first job 12 years ago :D ).

Our method takes one parameter which is the transaction that we want it to process. It will be marked with @param annotation, followed by a fully qualified type of the transaction. It will return a string, which we have to mark with @returns annotation. And finally, since this is a transaction processor, we need to mark it with @transaction annotation.

Then another transaction to send tokens between users:

In this method, we are sending tokens between two participants.

One thing worth noticing is that in code block [1] we are using a query. The difference here is that instead of passing the actual object as a parameter we need to create a special string pointing to the resource that has a form of: resource:{FULLY_QUALIFIED_TYPE}#{ID} . In our example we need to pass a Person resource, but since this can be either a Person or Merchant (which inherits from Person ) we cannot just hard-code the namespace. Instead, we are calling getFullyQualifiedType() on the sender object which will give us what we need (either org.szimano.merchantnetwork.Merchant for Merchant or org.szimano.merchantnetwork.Person for Person ). Remember that a Person with a given ID is a different resource then a Merchant with the same ID. Inheritance here is very limited!

Once [7] is executed, the owner of the ArtToken will be changed and the sender user will no longer have access to them.

The final transaction is for selling the art. To make it easier, we are just writing the transaction on the blockchain to mark that the art has been sold. The tokens are not then removed from it — this is something that could be done in further network development.

What we are going to use is the onSale field that is set to false by default. Every owner of an asset token can mark its onSale to true which means that he or she is ready to sell the art. Once at least 50% of the tokens for a given art work are set as onSale = true then our network will allow creating a sale transaction.

Permissions

Since this is a permissioned blockchain we need a way of describing the permissions.

They all have to have:

a unique rule name

description

participant — for whom should the rule be evaluated (connected user to the blockchain)

— for whom should the rule be evaluated (connected user to the blockchain) operation — a mix of READ , CREATE , UPDATE , DELETE and ALL

— a mix of , , , and resource — for which asset or participant on the blockchain should the rule be evaluated

— for which asset or participant on the blockchain should the rule be evaluated action — either ALLOW or DENY

— either or transaction /optional/ — inside which transaction should this rule be evaluated

/optional/ — inside which transaction should this rule be evaluated condition /optional/ — a logic that can bind the participant , asset and transaction (see below)

The participant and resource can be followed by #{ID} to specify a specific instance, e.g. org.szimano.merchantnetwork.Merchant#szimano1 .

Let us start with a simple ACL allowing all participant reading all data on Person s.

Then, we will allow creating and reading ListArtWork transaction by Merchants, but we will use the condition field to make sure that the Merchant lists only own art works.

Then, let us allow Merchant selling art work, but again making sure he sells only art listed by them.

Finally, we will allow the network admin to fully control everything. Permissions are good but this is our network! ;-)

Build and run your network

Finally, once all is done, we need to run a few magic commands in the terminal.

Run Fabric

Given that you followed the composer installation guide, just type