Private Blockchains: Hyperledger Composer Javascript API

Introduction

In my last article, I gave a quick overview of the Hyperledger Composer framework to build a business network with a private blockchain technology. I used a land registry network to show how the framework works. We then used a React application to use the REST API provided.

This time, instead of using the REST API, I made a little command line application using the Javascript API. The concept is simple. You enter commands in your terminal to trigger actions ( retrieve data, create assets and/or transactions ). We will re-use the same land registry network I used in the previous article.

Connecting to the composer runtime

First, we need to have our private blockchain running. If you haven't gone through my last article to set up your environment, you need to do it right now.

If you went through the article, you need to run a few commands to launch the runtime:

• First, you need to launch the ./startFabric.sh command from the folder I called fabric-tools in the last article.

• Next, from the land-registry folder, you need to install the composer runtime: composer network install --card PeerAdmin@hlfv1 --archiveFile [e-mail]

• Finally, still from the land-registry folder, deploy the business network: composer network start --networkName land-registry --networkVersion 0.0.1 --networkAdmin admin --networkAdminEnrollSecret adminpw --card PeerAdmin@hlfv1 --file networkadmin.card

And that's all you need, assuming you've done all the steps in the previous article before. If you only do those three commands without setting a proper environment, it will obviously not work.

The code

Note: I will link to the Github repository at the end of this article.

The application is rather simple. There is an index.js file.

const shell = require('shelljs')
const args = process.argv.slice(2)
const getREregistry = require('./getREregistry')
const getPIregistry = require('./getPIregistry')
const getPI = require('./getPI')
const contractLoan = require('./contractLoan')
const getLoans = require('./getLoans')
const getBanks = require('./getBanks')
const createPI = require('./createPI')
const createRE = require('./createRE')
const contractInsurance = require('./contractInsurance')
const getInsurances = require('./getInsurances')
const buyRealEstate = require('./buyRealEstate')
const getREAgents = require('./getREAgents')
const getNotaries = require('./getNotaries')

// get first argument
let arg = args.shift()
let realEstateId, duration, bankId, privateId, address, insuranceId

switch( arg ){
    case 'getAllRE':
        shell.exec('node getREregistry.js')
        process.exit()
        break
    case 'getAllPI': 
        shell.exec('node getPIregistry.js')
        process.exit()
        break
    case 'getREAgents':
        shell.exec('node getREAgents.js')
        process.exit()
        break
    case 'getInsurances':
        shell.exec('node getInsurances.js')
        process.exit()
        break
    case 'getNotaries': 
        shell.exec('node getNotaries.js')
        process.exit()
        break
    case 'getPI':
        const id = args.shift()
        shell.exec(`node getPI.js ${id}`)
        process.exit()
        break
    case 'getLoans':
        shell.exec('node getLoans.js')
        process.exit()
        break
    case 'getBanks':
        shell.exec('node getBanks.js')
        process.exit()
        break
    case 'createPI':
        privateId = args.shift()
        let name = args.shift()
        address = args.shift()
        let balance = args.shift()
        shell.exec(`node createPI.js ${privateId} ${name} ${address} ${balance}`)
        process.exit()
        break
    case 'createRE':
        let reId = args.shift()
        address = args.shift()
        let reSquareMeters = args.shift()
        let price = args.shift()
        let ownerId = args.shift()
        shell.exec(`node createRE.js ${reId} ${reAddress} ${reSquareMeters} ${price} ${ownerId}`)
        process.exit()
        break
    case 'contractLoan':
        let debtorId = args.shift()
        let bankId = args.shift()
        realEstateId = args.shift()
        let insterestRate = args.shift()
        duration = args.shift()
        shell.exec(`node contractLoan.js ${debtorId} ${bankId} ${realEstateId} ${insterestRate} ${duration}`)
        process.exit()
        break
    case 'contractInsurance':
        let insuredId = args.shift()
        insuranceId = args.shift()
        realEstateId = args.shift()
        cost = args.shift()
        duration = args.shift()
        shell.exec(`node contractInsurance.js ${insuredId} ${insuranceId} ${realEstateId} ${cost} ${duration}`)
        process.exit()
        break
    case 'buyRealEstate':
        let buyer = args.shift()
        let seller = args.shift()
        realEstateId = args.shift()
        let loan = args.shift()
        let realEstateAgent = args.shift()
        let notary = args.shift()
        insuranceId = args.shift()
        shell.exec(`node buyRealEstate.js ${buyer} ${seller} ${realEstateId} ${loan} ${realEstateAgent} ${notary} ${insuranceId}`)
        process.exit()
        break
    default:
        console.log('Wrong argument')
        process.exit()
        break
}

shell.exec('node index.js')

A GET route

We use shelljs to interact with the terminal. Depending on the argument you provide, we will execute a certain action. Some actions, when creating an asset or a participant, require additional arguments. Let's look at the getAllPI argument. PI stands for Private Individual, a participant in our network. When we provide this argument, we are going to retrieve every single Private Individual participant in the network. The action is described in the getPIRegistry.js file:

const BusinessNetworkConnection = require('composer-client').BusinessNetworkConnection
const Table = require('cli-table2')

const getPIregistry = (async function(){

    try {
        this.bizNetworkConnection = new BusinessNetworkConnection()
        let connection = await this.bizNetworkConnection.connect('admin@land-registry')
        let registry = await this.bizNetworkConnection.getParticipantRegistry('org.acme.landregistry.PrivateIndividual')
        let resources = await registry.getAll()
        let table = new Table({
            head: ['ID', 'Name', 'Address', 'Balance']
        })
        let arrayLength = resources.length
        for(let i = 0; i < arrayLength; i++) {
            let tableLine = []
            tableLine.push(resources[i].id)
            tableLine.push(resources[i].name)
            tableLine.push(resources[i].address)
            tableLine.push(resources[i].balance)
            table.push(tableLine)
        }
        console.log(table.toString())
        process.exit()

    } catch(error) {
        console.log(error)
        process.exit()
    }
}())

module.exports = getPIregistry

In order to interact with the Javascript API, we need only one package: composer-client. The structure is the same in every file. We connect to the private blockchain using the admin@land-registry admin card. I've put everything inside a IIFE ( Immediately Invoked Function Expression ) and I used the async/await keywords to make it clearer. The Javascript API uses promises, so you can chain the .then methods if you wish.

In our getPIRegistry file, we get the participant registry and call the getAll method on it. This will retrieve all the Private Individual participants. We then used the cli-table2 package to display the data in a nice table in our terminal.

A POST route

Create a Real Estate asset

To create a real estate asset, we use a command like this:

node index.js createRE id address squareMeters price ownerId

We need 5 parameters to create such an asset. The code is in the createRE.js file:

const BusinessNetworkConnection = require('composer-client').BusinessNetworkConnection

const createRE = (async function(){
    try {
        this.bizNetworkConnection = new BusinessNetworkConnection()
        let connection = await this.bizNetworkConnection.connect('admin@land-registry')
        const args = process.argv.slice(2)
        const reId = args.shift()
        const address = args.shift()
        const squareMeters = args.shift()
        const price = args.shift()
        const ownerId = args.shift()
        let factory = connection.getFactory()
        let re = factory.newResource('org.acme.landregistry', 'RealEstate', reId)
        re.address = address
        re.squareMeters = parseFloat(squareMeters)
        re.price = parseFloat(price)

        this.reRegistry = await this.bizNetworkConnection.getAssetRegistry('org.acme.landregistry.RealEstate')

        let ownerRelationship = factory.newRelationship('org.acme.landregistry', 'PrivateIndividual', ownerId)
        re.owner = ownerRelationship

        await this.reRegistry.add(re)
        console.log('Real Estate asset created!')
        process.exit()

    }catch( err ){
        console.log(err)
        process.exit()
    }
})()

module.exports = createRE

After the initial connection to the blockchain network, we retrieve the arguments we need. Then, we create a factory to create a new resource, in this case a RealEstate asset. We specify the relationship between the PrivateIndividual participant and this new RealEstate asset. Finally, after retrieving the RealEstate registry, we call the add method.

Note: You can add several assets or participants at once with the addAll method. This methods takes an array of the resources you want to add to the blockchain.

Submit a transaction

Last but not least, I will show you how to submit a transaction. The transaction will be triggered by this command:

node index.js buyRealEstate buyerId sellerId realEstateId loanId realEstateAgentId notaryId insuranceId

We need a few more arguments to complete this transaction, because there are quite a few relationships. You can go back to the previous article if you want to take a look at the business model we are using.

buyRealEstate.js

const BusinessNetworkConnection = require('composer-client').BusinessNetworkConnection

const contractInsurance = (async function(){
    try{
        this.bizNetworkConnection = new BusinessNetworkConnection()
        let connection = await this.bizNetworkConnection.connect('admin@land-registry')
        const args = process.argv.slice(2)
        const pIdBuyer = args.shift()
        const pIdSeller = args.shift()
        const realEstateId = args.shift()
        const loanId = args.shift()
        const realEstateAgentId = args.shift()
        const notaryId = args.shift()
        const insuranceId = args.shift()
        let transaction = {
            "$class": "org.acme.landregistry.BuyingRealEstate"
        }
        transaction.buyer = pIdBuyer
        transaction.seller = pIdSeller
        transaction.realEstate = realEstateId
        transaction.loan = loanId
        transaction.realEstateAgent = realEstateAgentId
        transaction.notary = notaryId
        transaction.insurance = insuranceId
        transaction.isNewOwnerMainResidence = false

        let serializer = connection.getSerializer()
        let resource = serializer.fromJSON(transaction)
        await this.bizNetworkConnection.submitTransaction(resource)
        console.log('Transaction Completed!')
        process.exit()
    }catch( err ){
        console.log(err)
        process.exit()
    }
})()

module.exports = contractInsurance

We start off the same, connecting to the blockchain and retrieving arguments. We then create a transaction object. Notice the $class key in the object. We get the serializer to transform our JSON into a resource Composer can understand. Finally we call the submitTransaction method.

Of course, before doing this transaction, you would need to contract a loan and an insurance. Both transactions can be created via the command line and you will find the code in the Github repository. To keep things short, I only show a few actions here.

Note: You could ( should ) add some validations in some actions ( make sure a Participant exists for example before specifying it in a transaction... ). I'll let you do that ;)

Repository

The code can be found here. Feedbacks welcome :)

Have fun!

Comments

[Jan]

Is a private blockchain not just a very inefficient database? I mean why blockchain at all in a private context? Because your company doesn't trust itself? Hypedriven developement? You just want to be cool, because all do blockchain now and you want to tell customers "yeee we're doing blockchain too!"?

[Damien Cosset]

First of all, I'm not selling anything here. I'm a web developer learning something new. I don't work at all with blockchains. I'm not trying to be "cool", whatever that means in this world. I like the blockchain technology and the ideas with it.

Second, private blockchains are not a solution for every single business network. Still a young technology, even more so on the permissioned blockchain side, we'll keep figuring out where it will be useful or not.

Permissioned blockchains could be a good way to increase trust between entities that have no reason to trust each other. In our "classic" business network, every single organisation will keep their own ledger of records. Which means that every time an operation happens, every organisation involved in this operation would need to update their ledger. If we have 5 companies involved in a transaction, we would have 5 different updates on 5 different ledgers.

By having a distributed ledger ( which is what a blockchain is ), we only need to update one ledger that everyone in the network share. The "permissioned" part means that entities can only view the part of the ledger they are involved with ( which is the difference with the Bitcoin blockchain for example ).

Potentially, the blockchain could reduce errors, and because it is almost impossible to cheat it, it increases the trust between the different organisations because they know the data is safe.

That's a very short answer to something that could take several articles to answer, on a technology we are still exploring and trying to find the best possible use cases. But, I hope it was clear enough.

Have a nice day.