Getting started with Hyperledger Composer and private blockchains

hyperledger

Introduction

In my last article, I started to explore what characteristics a blockchain would need to have to be helpful to a business, and a business network. Now it is time to dive in and use some solutions that are already existing.

Private blockchains or public blockchains?

There are several frameworks and tools that can be used to create a blockchain for a business network. We could go down the path of a public blockchain with Ethereum. It is a possible solution. However, in my learning, I chose to go down a different path and use a private blockchain framework. I believe private blockchains make more sense for businesses than public ones. The anonymity provided by the Ethereum blockchain ( for example ) isn’t especially useful. The cryptocurrency also is not particularly useful. Some businesses will find a permissionless blockchain like Ethereum more attractive, but it makes more sense for networks to use a private blockchain.

In certain networks, you would need a permissioned blockchain that you can only join by invitation or permission. I chose to explore the Hyperledger framework, especially Fabric and Composer.

Hyperledger is an open source set of tools. It is hosted by the Linux Foundation and tries to explore how to use blockchains in a real-world business environment. There are a LOT of huge companies behind this thing ( IBM, Airbus, Intel, JPMorgan, Hitachi, Bosch …).

Hyperledger Fabric is the first framework born out of this adventure. It is a blockchain implementation using container technology and smart contracts.

However, we will start by using a tool called Hyperledger Composer. Composer is built on top of Fabric and will allow us to build rapidly a business network using Javascript. There is also a very helpful playground in the browser that we will use.

What we will cover in this article

  • Create a business network using the differents Composer tools
  • Create some transactions with the Composer REST API
  • Create a simple application and use our business network with a REST API

Let’s go!

Setting everything up

  • You will need Docker

  • You’ll need the Composer CLI tools: npm install -g composer-cli

  • This will run a REST server to expose our business network:
    npm install -g composer-rest-server

  • Some things for generating code:

npm install -g generator-hyperledger-composer
npm install -g yo

  • Next, we’ll need a local Hyperledger Fabric runtime, where our business network will be deployed.

Create a directory and let’s name it fabric-tools

mkdir ~/fabric-tools && cd ~/fabric-tools

Inside this new directory, run the following command:

curl -O https://raw.githubusercontent.com/hyperledger/composer-tools/master/packages/fabric-dev-servers/fabric-dev-servers.zip
unzip fabric-dev-servers.zip

This gives you all you need to run a local Hyperledger Fabric runtime.

Run: ./downloadFabric.sh
Next, run: ./startFabric.sh, then ./createPeerAdminCard.sh

Great, we’re all set up, we can start writing some code.

Creating a business network

You could choose to create your own business network from scratch. But, to speed things up, I made one for you. I chose a land registry network for my example.

In a network, there are three types of resources:

  • Participant: The types of entities that participate in the network. In my example, there are 5 differents types of participants:
    • PrivateIndividual: They buy and sell their properties
    • Bank: They afford loans ( or not )
    • Notary: They validate transactions
    • RealEstateAgent: They facilitate transactions between PrivateIndividuals
    • InsuranceCompany: You do need insurance on real estate right?
  • Assets: Assets are what transactions are made of. In this network, there are 3 different assets:
    • RealEstate: Because it’s a land registry, remember?
    • Insurance: From the InsuranceCompany participants
    • Loan: From the Bank participant, you know, to finance the real estate thing
  • Transactions: Without transactions, nothing would move. Transactions make things happen. I have 3 differents transactions in my network:
    • BuyingRealEstate: One PrivateIndividual buys, another sells. What happens then?
    • ContractingLoan: Between a Bank and a PrivateIndividual
    • ContractingInsurance: Between a PrivateIndividual and an InsuranceCompany

Ok, this is the outline of our business network. Let’s create it.

A business network archive is composed of 4 different types of files in Hyperledger:

  • Model file. Where you describe your participants, assets and transactions. We use a modeling language to describe this. Don’t worry, it’s not that complicated.

  • Access File. Hyperledger Fabric is a permissioned blockchain. We need to defined who gets to see what. For simplicity sake, we won’t do anything crazy in this file. Everybody will see everything. In this, we use an Access Control Language (ACL) to express permissions.

  • Script File. Written in Javascript. This defines what happens when a transaction happens in the network.

  • Query File. Used to execute queries. Written in a native query language. We won’t use this file for now. Another time.

Generating code

We’ll use Yeoman to set up the code for us. Run:

yo hyperledger-composer:businessnetwork

Enter land-registry for the network name. Complete as you wish for the author fields.

Select Apache-2.0 as the license

Enter org.acme.landregistry as the namespace.

Great, now you have all the files you need.

The model file

Let’s start by the model. This is where we define our participants, assets and transactions. Open up the org.acme.landregistry.cto file and put this in there:

**
 * Business network model
 */

namespace org.acme.landregistry

participant PrivateIndividual identified by id {
  o String id
  o String name
  o String address
  o Double balance default = 0.0
}

participant Bank identified by id {
  o String id
  o String name
  o Double balance default = 0.0
}

participant InsuranceCompany identified by id {
  o String id
  o String name
  o Double balance default = 0.0
}
  
participant Notary identified by id {
  o String id
  o String name
  o String address
  o Double balance default = 0.0
}
  
participant RealEstateAgent identified by id {
  o String id
  o String name
  o Double balance default = 0.0
  o Double feeRate
}
  
asset RealEstate identified by id {
  o String id
  o String address
  o Double squareMeters
  o Double price
  --> PrivateIndividual owner
}

asset Loan identified by id {
   o String id
   o Double amount
   o Double interestRate
   --> PrivateIndividual debtor
  --> Bank bank
  --> RealEstate realEstate
   o Integer durationInMonths
}
  
asset Insurance identified by id {
  o String id
  --> RealEstate realEstate
  --> PrivateIndividual insured
  --> InsuranceCompany insuranceCompany
  o Double monthlyCost
  o Integer durationInMonths
}

transaction BuyingRealEstate {
  --> PrivateIndividual buyer
  --> PrivateIndividual seller
  --> RealEstate realEstate
  --> Loan loan
  --> RealEstateAgent realEstateAgent
  --> Notary notary
  --> Insurance insurance
}
  
transaction ContractingInsurance {
  --> PrivateIndividual insured
  --> InsuranceCompany insuranceCompany
  --> RealEstate realEstate
  o Double monthlyCost
  o Integer durationInMonths
}
  
transaction ContractingLoan {
  --> PrivateIndividual debtor
  --> Bank bank
  --> RealEstate realEstate
  o Double interestRate
  o Integer durationInMonths
}

Participants

Ok, there is quite a few things to uncover here. I think it reads relatively easily. First, I define our 5 participants types. They will all be uniquely identified by their id field. As you can see, this modeling language is strongly typed. You need to specify the type for each field. Nothing fancy for our participants, some String and Double types.

Assets

Our assets will also be identified by their id field. But, this time, you can see some arrows ( –> ) in the assets definitions. The arrows define relationships. A RealEstate asset has a relationship with a PrivateIndividual, its owner. A Loan has 3 differents relationships: the PrivateIndividual requesting a loan, the Bank that emits the loan and the RealEstate asset the loan finances.

Transactions

3 transactions in our model. They are not identified by any field like the other resources. The fields specified here will be passed to the functions declared in our script file. Let’s see this now.

The Script File

Back to good old Javascript. This is where we define what happens during a transaction. Open the logic.js file in the lib folder:

'use strict';


/**
 * Contracting an insurance
 * @param {org.acme.landregistry.ContractingInsurance} insurance
 * @transaction
 */

 function contractingInsurance( insurance ){
    return getAssetRegistry('org.acme.landregistry.Insurance')
      .then(function(assetRegistry){
      var factory = getFactory()
      var insuranceId = insurance.insured.id + '' + insurance.insuranceCompany.id + '' + insurance.realEstate.id
      var insuranceAsset = factory.newResource('org.acme.landregistry', 'Insurance', insuranceId)
      insuranceAsset.insured = insurance.insured
      insuranceAsset.insuranceCompany = insurance.insuranceCompany
      insuranceAsset.realEstate = insurance.realEstate
      insuranceAsset.durationInMonths = insurance.durationInMonths
      insuranceAsset.monthlyCost = insurance.monthlyCost
      
      return assetRegistry.add(insuranceAsset)
    })
 }


/**
 * Contracting a loan
 * @param {org.acme.landregistry.ContractingLoan} loan
 * @transaction
 */

function contractingLoan( loan ){
  return getAssetRegistry('org.acme.landregistry.Loan')
    .then(function(assetRegistry){
    var factory = getFactory()
    var loanId = loan.debtor.id + '' + loan.realEstate.id + '' + loan.bank.id
    var loanAsset = factory.newResource('org.acme.landregistry', 'Loan', loanId) 
    loanAsset.debtor = loan.debtor
    loanAsset.bank = loan.bank
    loanAsset.interestRate = loan.interestRate
    loanAsset.durationInMonths = loan.durationInMonths
    loanAsset.realEstate = loan.realEstate
    loanAsset.amount = loan.realEstate.price
    
    return assetRegistry.add(loanAsset)
  })
}

/**
 * Buying Real Estate
 * @param {org.acme.landregistry.BuyingRealEstate} trade
 * @transaction
 */

function buyingRealEstate( trade ){
  var notaryFees = 0.1 * trade.realEstate.price
  var realEstateAgentFees = trade.realEstateAgent.feeRate * trade.realEstate.price
  var insuranceCostFirstMonth = trade.insurance.monthlyCost
  var totalCost = notaryFees + realEstateAgentFees + insuranceCostFirstMonth 
  // Updates the seller's balance
  trade.seller.balance += trade.realEstate.price
  
  // Check if the buyer has enough to pay the notary, real estate agent and insurance
  if( trade.buyer.balance < totalCost ){
    throw new Error('Not enough funds to buy this!')
  }
  trade.buyer.balance -= totalCost
  trade.realEstate.owner = trade.buyer
  trade.realEstateAgent.balance += realEstateAgentFees
  trade.notary.balance += notaryFees
  
  Promise.all([
    getAssetRegistry('org.acme.landregistry.RealEstate'),
    getParticipantRegistry('org.acme.landregistry.PrivateIndividual'),
    getParticipantRegistry('org.acme.landregistry.PrivateIndividual'),
    getParticipantRegistry('org.acme.landregistry.Notary'),
    getParticipantRegistry('org.acme.landregistry.RealEstateAgent')
  ]).then(function(registries){
    return (
      registries[0].update(trade.realEstate),
      registries[1].update(trade.seller),
      registries[2].update(trade.buyer),
      registries[3].update(trade.notary),
      registries[4].update(trade.realEstateAgent)
    )
  })
}

Ok, we have three functions, one for each transaction. You use JSDoc description and tags to describe what transaction your function is supposed to work on. As you can see, you provide the namespace, { org.acme.landregistry.ContractingInsurance } for example, followed by @transaction.

contractingInsurance

In our model, to buy real estate, you first need to contract a loan and an insurance. This function creates an Insurance asset. We use the getAssetRegistry function to retrieve the insurance's asset registry. We then create a new Insurance asset and defines its properties. Finally, we add the new asset to the registry.

Note: All the registries that we use return promises.

contractingLoan

Exactly the same concept. Get the Loan registry, create a new Loan, add it. Note how I chose to dynamically create each asset ID. In a larger network, we would need to come up with something different. In our case, it'll be fine.

buyingRealEstate

Finally, we can buy some real estate. There are a few things going on here. First, I must explain a few rules about our network:

  • Everyone is paid during this transaction. Not before.

  • A notary must validate a transaction. She takes 10% of the real estate price as her fee. This is more or less what it costs in France in such transactions. So, if you buy a house for 100000€, you would need to pay an extra 10000€ to the notary.

  • Each transaction is conducted with a real estate agent. What the agent gets is specified in the model ( feeRate ).

  • The insurance has a montly cost. During the transaction, the buyer must pay the first month.

  • I assume that the buyer contracts a loan ONLY for the real estate price. Other costs must be paid by herself. As you can see in the function, if the buyer's balance can't cover the insurance's first month, the notary's fees and the real estate agent's fees, the transaction doesn't happen.

  • Transactions are atomic. Meaning, everything happens or nothing happens. If an error happens while we update one of our participants at the end of the transaction, we go back to the state we had before the transaction.

  • The rules I chose for the network are arbitrary. Some are based on how it works in France, others are chosen to make things a bit simpler.

In this function, we pay everyone. Then, we fetch every single registries we need and we update them all. Transaction done!

Permissions file

Finally, the permission file. We won't do anything crazy here. Just copy and paste this in the .acl file. We can define permissions depending on the participants, as you should in a private blockchain, but that would be outside the scope of this article. Put this in the permissions.acl file:

rule Default {
    description: "Allow all participants access to all resources"
    participant: "ANY"
    operation: ALL
    resource: "org.acme.landregistry.*"
    action: ALLOW
}

rule SystemACL {
  description:  "System ACL to permit all access"
  participant: "ANY"
  operation: ALL
  resource: "org.hyperledger.composer.system.**"
  action: ALLOW
}

Basically, let everyone do whatever they want. Not what you would like in a production-ready blockchain, but good enough for now.

Deploying

Everything is ready! Now, we can deploy our business network in the Hyperledger Fabric. We'll need to run a few commands:

First, we need to create a Business Network Archive that the Fabric can use. To do this, in the land-registry folder, run this:

composer archive create -t dir -n .

This will create a .bna file.

Next, we'll install the composer runtime with:

composer runtime install --card PeerAdmin@hlfv1 --businessNetworkName land-registry

The PeerAdmin card is the one you created by running /.createPeerAdminCard.sh earlier.

Next, we'll deploy the business network:

composer network start --card PeerAdmin@hlfv1 --networkAdmin admin --networkAdminEnrollSecret adminpw --archiveFile land-registry@0.0.1.bna --file networkadmin.card

Finally, we'll need to import the network administrator card into the network:

composer card import --file networkadmin.card

Playing around

Everything is ready. We can now create the REST API by running composer-rest-server.

  • Enter admin@land-registry as the card name.
  • Never use namespaces, then NO, then YES, then NO. ( Just YES to WebSockets )

You can navigate to localhost:3000/explorer now.

We have now access to a REST API to interact with our business network. As you can see, we have everything we defined earlier: paticipants, assets and transactions.

First things first, we need to create our participants and at least one RealEstate asset so we can make a transaction.

Let's go to the PrivateIndivual item, and select the /POST route. I'll create two participants here.

I'll name one PrivateIndividual Joe, with the id joe. I'll also give him 50000 in his balance. Give whatever address you want. Hit Try it out to create Joe.

The other individual will be Sophie, with the id sophie. She'll have 10000 in her balance. Give her an address and hit Try it out.

Make sure the response code is 200 every time. You can double check by going to the /GET route and fetch the data.

Let's move to the other participants now. The concept is the same, just jump between the different items.

The notary will be Ben, with the id ben. The real estate agent will be called Jenny, id jenny. Her feeRate will be set to 0.05 ( 5% ). The bank will be HSBC, id hsbc. Finally, the insurance company will be AXA, id axa.

Now, let's create a RealEstate asset. Same concept, got to the /POST route and give it the following data:

  {
    "$class": "org.acme.landregistry.RealEstate",
    "id": "buildingOne",
    "address": "France",
    "squareMeters": 100,
    "price": 100000,
    "owner": "resource:org.acme.landregistry.PrivateIndividual#sophie"
  }

As you can see in the owner field, I decided to give this asset to Sophie, by specifying her id. This is the relationship between RealEstate and PrivateIndividual.

A transaction

Great, now, we can make a transaction! Sophie decides to sell her house, and Joe decides to buy it. First, Joe needs to go to his bank and contract a loan. In our network, we do not create a Loan asset directly. The transaction ContractingLoan is responsible for the creation of the asset. So choose the ContractingLoan transaction in the list, and the /POST route. To create our loan, give it the following data:

{
  "$class": "org.acme.landregistry.ContractingLoan",
  "debtor": "org.acme.landregistry.PrivateIndividual#joe",
  "bank": "org.acme.landregistry.Bank#hsbc",
  "realEstate": "org.acme.landregistry.RealEstate#buildingOne",
  "interestRate": 2.5,
  "durationInMonths": 300
}

Again, you need to specify a few relationships for this transaction. The debtor is Joe, so I specify his id joe. The bank is hsbc and the real estate financed is buildingOne. I chose a 2.5% interest rate over 300 months ( 25 years ).

Note: Remember to give the participant or asset ID in the relationship. So => joe NOT Joe.!

Submit and you will see your new Loan if you go to the Loan items and use the /GET route.

Next, let's contract an insurance. The concept is the same, the transaction ContractingInsurance is responsible for the creation of the asset. Move to this item and choose the /POST route again:

{
  "$class": "org.acme.landregistry.ContractingInsurance",
  "insured": "org.acme.landregistry.PrivateIndividual#joe",
  "insuranceCompany": "org.acme.landregistry.InsuranceCompany#axa",
  "realEstate": "org.acme.landregistry.RealEstate#buildingOne",
  "monthlyCost": 150,
  "durationInMonths": 12
}

Again, the insured is joe. The insuranceCompany is axa, and the realEstate is still buildingOne. I chose 150 for the monthly insurance's costs for a 12 months duration. Submit and check that the Insurance asset has been created by checking the /GET route under Insurance.

We finally have all the pre-requisites to execute our BuyingRealEstate transaction. Move to said transaction and give it the following data:

{
  "$class": "org.acme.landregistry.BuyingRealEstate",
  "buyer": "org.acme.landregistry.PrivateIndividual#joe",
  "seller": "org.acme.landregistry.PrivateIndividual#sophie",
  "realEstate": "org.acme.landregistry.RealEstate#buildingOne",
  "loan": "org.acme.landregistry.Loan#joebuildingOnehsbc",
  "realEstateAgent": "org.acme.landregistry.RealEstateAgent#jenny",
  "notary": "org.acme.landregistry.Notary#ben",
  "insurance": "org.acme.landregistry.Insurance#joeaxabuildingOne"
}

Same concept, we specify the relationships in the transaction by adding the proper ids. joe is the buyer, sophie is the seller, jenny is the real estate agent, joebuildingOnehsbc is the loan's id, joeaxabuildingOne is the insurance's id, buildingOne is the real estate's id and ben is the notary's id.

When this transaction is submitted. You will see that the RealEstate asset has now a new owner Joe. You can also also see that the participant's balances have been updated:

  • Sophie's balance is now 110000 ( Her 10000 + the real estate's price of 100000 )

  • Joe's balance is now 34850. ( His 50000 - notary's fees of 10000 - real estate agent's fees of 5000 - the insurance's first month of 150 )

  • The notary's balance is now 10000

  • The real estate agent's balance is now 5000.

Great, we interacted with our business network and a blockchain. Now, let's create a simple User Interface that will interact with this REST API and retrieve some data.

Create a simple application with Composer and Fabric

We will not do anything too fancy, just something to show how straightforward it is to work with the business network in the Hyperledger Composer world.

This simple application will be built using the create-react-app tool. We will be able to do 4 things will it:

  • GET and display PrivateIndividual participants
  • GET and display RealEstate assets
  • POST and create new PrivateIndividual participants
  • POST and create new RealEstate assets

Of course, there are no limits to what you can do with the REST API, I chose arbitrarly which routes we will use here.

create-react-app

First, we need to install the create-react-app tool:

npm install -g create-react-app

Next, create your app:

create-react-app <APP_NAME>

This will create a React application in your app folder. You don't have to setup anything. Now, we need to change a couple of things to make sure we can talk to the REST API.

The proxy and port

We are going to retrieve data from our REST API running in localhost:3000. We will run our app in a different port. To make sure our React application goes to the right place to get the data and avoid cross-origin issues, go to your package.json file.

In the file, you will simply add the line:

"proxy": "http://localhost:3000/"

That's it for the proxy. Now, in that same file, look in the scripts object for the start command. The start command should look like this now:

"start": "PORT=3001 react-scripts start"

Because the REST API will run on port 3000, this will simply run the React app on the port 3001, and not ask us a different port everytime we start it.

The code!

I tried to make things very simple. Just raw code, no CSS, no fancy stuff. Two files: App.js and Client.js. You'll create the file Client.js and add this:

function search(query, cb) {
    return new Promise( (resolve,reject) => {
        return fetch(`api/${query}`, {
            accept: "application/json"
        })
            .then(parseJSON)
            .then(data => resolve(data));
    })

}

function create(type, data){
    return new Promise((resolve, reject) => {
        return fetch(`api/${type}`, {
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json'
            },
            method: 'post',
            body: JSON.stringify(data)
        })
        .then(parseJSON)
        .then(() => resolve())
    })

}

function parseJSON(response) {
  return response.json();
}

const Client = { search, create };
export default Client;

What do we have here? Basically, we have two functions: search and create. The function search will handle our GET requests, the create one will handle our POST requests. If you didn't explore the REST API a bit, every route begins with the prefix /api. In our case, http://localhost:3000/api/, that's our prefix. The proxy key we added in our package.json will send every request to the right place. We just have to make sure the rest of our query is good.

So:

  • GET and POST PrivateIndividual => http://localhost:3000/api/PrivateIndividual
  • GET and POST RealEstate => http://localhost:3000/api/RealEstate

Now, let's move to the App.js file:

import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';
import Client from './Client'

class App extends Component {

    state = {
        privates: [],
        realEstate: []
    }

    componentWillMount = () => {
        this.getPrivateIndividual()
        this.getRealEstate()
    }

    getPrivateIndividual = () => {
        Client.search('PrivateIndividual')
        .then(data => {
            this.setState({
                privates: data
            })
        })
    }

    getRealEstate = () => {
        Client.search('RealEstate')
        .then(data => {
            this.setState({
                realEstate: data
            })
            for( let i = 0; i < this.state.realEstate.length; i++ ){
                let privateIndividual = this.state.realEstate[i].owner.split('#')[1]
                Client.search(`PrivateIndividual/${privateIndividual}`)
                    .then(data => {
                        let realEstate = this.state.realEstate
                        realEstate[i].ownerName = data.name
                        this.setState({
                            realEstate
                        })
                    })
            }
        })
    }

    handlePrivateInputChange = e => {
        const {name, value} = e.target
        this.setState({
            [name]: value
        })
    }

    submitPrivate = () => {
        const data = {
            "$class": "org.acme.landregistry.PrivateIndividual",
            "id": this.state.name.toLowerCase(),
            "name": this.state.name,
            "address": this.state.address,
            "balance": this.state.balance
        }

        Client.create('PrivateIndividual', data)
        .then(() => {
            this.getPrivateIndividual()
        })
    }

    handleRealEstateInputChange = e => {
        const { value, name } = e.target
        this.setState({
            [name]: value
        })
    }

    submitRealEstate = () => {
        const data =  {
            "$class": "org.acme.landregistry.RealEstate",
            "id": this.state.id,
            "address": this.state.realEstateAddress,
            "squareMeters": this.state.squareMeters,
            "price": this.state.price,
            "owner": `org.acme.landregistry.PrivateIndividual#${this.state.owner}`
        }

        Client.create('RealEstate', data)
        .then(() => {
            this.getRealEstate()
        })
    }

  render() {

    return (
      

Add PrivateIndividual

Add RealEstate

Private Individual

{this.state.privates.map((p, i) => (
Name: {p.name} Balance: {p.balance}
))}

Real Estate Assets

{this.state.realEstate.map((r, i) => (
ID: {r.id} Address: {r.address} Price: {r.price} Owner: {r.ownerName}
))}
); } } export default App;

There is nothing crazy here either. The HTML is composed of two forms: one to create a new PrivateIndividual and another to create a new RealEstate asset. Below these, we loop through the data we have and create simple boxes to display our assets and participants.

In the componentWillMount function, we retrieve our data. submitPrivate and submitRealEstate do what they are told 😉 .Notice the shape of the object we sent to the API.

Running the app

Make sure your REST API is running. If not, re-run composer-rest-server. Then, in the land-registry folder, run your React app with npm start.

Now, you can play along with your private blockchain!

Note: In the React application, I skipped things like error handling, CSS styling and other POST routes for transactions. The article seems long enough and, I hope, clear enough so that you could manage these things on your own. Have fun!

3 Comments, RSS

  1. Business Cash Advance March 30, 2018 @ 11:04 pm

    Hello. Thanks.Great article.

  2. Floyd April 30, 2018 @ 2:59 am

    in this step:”Open the org.example.mynetwork.cto model file.” Please explain exactly who someone opens the CTO file using VSCode. It may be clear to some but not others. In VSCode I don’t see the file. Please address. Thank you.

    • dcosset May 2, 2018 @ 3:49 pm

      In VSCode, you will need the Hyperledger Composer plugin extension.

Your email address will not be published. Required fields are marked *

*