Taxonomy Icon

Blockchain

Blockchain is the big buzzword of 2018. Everyone’s talking about its impact on cryptocurrencies such as Bitcoin. But how do you build an application using blockchain technology? Hyperledger Fabric is a platform for developing enterprise-ready blockchain applications. It’s one of many open-source blockchain projects founded by the Linux Foundation. It’s designed for building business networks and making it easy for developers and business owners to create applications that solve business problems. Hyperledger Composer is a framework that sits on Hyperledger Fabric to facilitate and simplify the process of designing and building business networks. Developers can build the transaction processor functions using JavaScript and build end-to-end blockchain applications much quicker than building if building from the level of the Fabric itself.

Learning objectives

After completing this how-to guide, you will be able to:

  • Set up the Hyperledger Fabric environment on your own computer.
  • Build business networks using Hyperledger Composer by modeling assets, participants, and transactions.
  • Deploy the Business Network Archive (.bna) file to the Fabric, and use Loopback to spin up a REST server to connect to a UI.

Prerequisites

  • A Unix-based operating system. The Hyperledger Fabric environment can only be set up on Unix environments, so for windows users, you have to install a virtual machine and set up the environment as such. For the purposes of this demo, we’re going to be setting up a Ubuntu OS on VirtualBox.

  • A Hyperledger Fabric environment installed on your computer.

  • For Ubuntu Users

    • To run Hyperledger Composer and Hyperledger Fabric, we recommend you have at least 4Gb of memory.
    • The following are prerequisites for installing the required development tools:

      Operating Systems: Ubuntu Linux 14.04 / 16.04 LTS (both 64-bit), or Mac OS 10.12
      Docker Engine: Version 17.03 or higher
      Docker-Compose: Version 1.8 or higher
      Node: 8.9 or higher (note version 9 is not supported)
      npm: v5.x
      git: 2.9.x or higher
      Python: 2.7.x
      A code editor of your choice, we recommend VSCode.
      
    • If installing Hyperledger Composer using Linux, be aware of the following advice:

      Login as a normal user, rather than root.
      Do not su to root.
      When installing prerequisites, use curl, then unzip using sudo.
      Run prereqs-ubuntu.sh as a normal user. It may prompt for root password as some of it's actions are required to be run as root.
      Do not use npm with sudo or su to root to use it.
      Avoid installing node globally as root.**
      
    • If you’re running on Ubuntu, you can download the prerequisites using the following commands:

    curl -O https://hyperledger.github.io/composer/prereqs-ubuntu.sh chmod u+x prereqs-ubuntu.sh

    • Next run the script – as this briefly uses sudo during its execution, you will be prompted for your password.

    ./prereqs-ubuntu.sh

  • For Mac Users

Estimated time

To go through this guide, it will take an estimated 45 minutes to have an end-to-end Blockchain application up and running on Hyperledger Fabric.

Steps

Install the Development Environment

Follow these instructions to obtain the Hyperledger Composer development tools (primarily used to create Business Networks) and stand up a Hyperledger Fabric (primarily used to run/deploy your Business Networks locally). Note that the Business Networks you create can also be deployed to Hyperledger Fabric runtimes in other environments e.g. on a cloud platform: https://hyperledger.github.io/composer/installing/development-tools.html

  • Select “Deploy a Business Network”

  • Under the “Model Network Starter Template”, select “browse”, and choose the pizza-on-the-blockchain@0.0.1.bna file from this repository.

  • Select “Deploy”

  • Select “Connect Now”

You should be presented with the following screen:

  • Click on the “Model File” in the left pane. From this section you can model your business network. In our example, we are tracking the shipment of Frozen Pizzas from the Factory, to the Wholesaler, to the Retailer, down to the Customer. We’re assuming each Entity (i.e. Factory), will make use of RFID tags to store information on the pizza, and will scan that tag as it’s received. This information, such as timestamp, the date, and state (production, freezing, packaging, distribution) is stored on the Blockchain.

We will create multiple instances of type Entity (i.e. Factory).

Here we define the transactions that will take place on the Blockchain, such as changing the state of the pizza and which entity owns the pizza.

  • Select “Script File” in the left pane. From here, you will define the transaction processor functions, these are the functions that will execute when the transactions are invoked.

The ChangeStateToProduction function will change the state of the current pizza to Production.

The same applies with the other three states.

The ChangeOwner function will change the owner of the pizza to a new owner.

  • Select “Access Control” from the left pane. From here, you can determine which participants of the business network have access to which assets and transactions.

  • On the Top Pane, select “Test”.

  • From here, you can test out the transactions that you defined in the model file. On the top left, select “+ Create New Participant, and enter a unique identifier for the entity.

  • Select “Create New”. You should see a new entity being created. In the left Pane, under Assets, select Pizza. Select “+ Create New Asset.” Fill in the details for the Pizza, and select “Create New”. (For the state, select from “production”, “freezing”, “packaging”, and “distribution). For the Owner field, select the ID of the entity you just created.

You should see a new Pizza asset being created.

  • Select “Submit Transaction” on the bottom left. For the Transaction Type, select the “ChangeStateToFreezing” transaction, and for the “pizza” field, pass in the ID you just created when creating your pizza asset.

  • Select “Submit”

You should see a notification pop up saying “Submit Transaction Successful”. You can double-check by selecting “All Transactions” in the left pane, under Transactions.

  • In the ChangeStateToFreezing transactions, select “view record”, and you can see all the transaction related information.

That’s it! You’re ready to deploy your business network to the Hyperledger Fabric.

Deploy the Business Network to Hyperledger Fabric

  • Create the .bna file

    Once you have the environment set up, it’s time to package everything into a .bna file. In order to do this, we’re going to use a Yeoman generator to create a skeleton business network, then replace the model, script, and access control files with the ones we created earlier on in the tutorial.

    • Create a skeleton business network using Yeoman. This command will require a business network name, description, author name, author email address, license selection and namespace.

    yo hyperledger-composer:businessnetwork

    • Enter pizza-on-the-blockchain for the network name, and desired information for description, author name, and author email.

    • Select Apache-2.0 as the license.

    • Select org.acme.biznet as the namespace.

    • cd into the folder which was just created and replace the contents of /pizza-on-the-blockchain/lib/org.example.biznet.cto with the model file generated earlier on in the tutorial.

    • Replace the contents of /pizza-on-the-blockchain/lib/logic.js with the script file generated earlier on in the tutorial.

    • Create a new file in the pizza-on-the-blockchain folder, called permissions.acl and paste the contents of the Access Control file generated earlier on in the tutorial.

    Now that you have your busines network, it’s time to package it up into a .bna file. In the pizza-on-the-blockchain directory, enter the following command:

    composer archive create -t dir -n .

    After the command has run, a business network archive file called pizza-on-the-blockchain@0.0.1.bna has been created in the tutorial-network directory.

Deploy the Business Network

After creating the .bna file, the business network can be deployed to the instance of Hyperledger Fabric. Normally, information from the Fabric administrator is required to create a PeerAdmin identity, with privileges to deploy chaincode to the peer. However, as part of the development environment installation, a PeerAdmin identity has been created already.

After the runtime has been installed, a business network can be deployed to the peer. For best practice, a new identity should be created to administrate the business network after deployment. This identity is referred to as a network admin.

A PeerAdmin business network card with the correct credentials is already created as part of development environment installation.

Deploying a business network to the Hyperledger Fabric requires the Hyperledger Composer chaincode to be installed on the peer, then the business network archive (.bna) must be sent to the peer, and a new participant, identity, and associated card must be created to be the network administrator. Finally, the network administrator business network card must be imported for use, and the network can then be pinged to check it is responding.

  • To install the composer runtime, run the following command:

composer runtime install --card PeerAdmin@hlfv1 --businessNetworkName pizza-on-the-blockchain

The composer runtime install command requires a PeerAdmin business network card (in this case one has been created and imported in advance), and the name of the business network.

  • To deploy the business network, from the pizza-on-the-blockchain directory, run the following command:

composer network start --card PeerAdmin@hlfv1 --networkAdmin admin --networkAdminEnrollSecret adminpw --archiveFile pizza-on-the-blockchain@0.0.1.bna --file networkadmin.card

The composer network start command requires a business network card, as well as the name of the admin identity for the business network, the file path of the .bna and the name of the file to be created ready to import as a business network card.

  • To import the network administrator identity as a usable business network card, run the following command:

composer card import --file networkadmin.card

The composer card import command requires the filename specified in composer network start to create a card.

  • To check that the business network has been deployed successfully, run the following command to ping the network:

composer network ping --card admin@pizza-on-the-blockchain

The composer network ping command requires a business network card to identify the network to ping.

Generate a REST Server

Hyperledger Composer can generate a bespoke REST API based on a business network. For developing a web application, the REST API provides a useful layer of language-neutral abstraction.

  • To create the REST API, navigate to the pizza-on-the-blockchain directory and run the following command:

composer-rest-server

  • Enter admin@pizza-on-the-blockchain as the card name.

  • Select never use namespaces when asked whether to use namespaces in the generated API.

  • Select No when asked whether to secure the generated API.

  • Select Yes when asked whether to enable event publication.

  • Select No when asked whether to enable TLS security.

The generated API is connected to the deployed blockchain and business network.

Once the REST server is up and running, head over to https://localhost:3000/explorer

It should look a little like this:

Run the Application

  • Purpose

    This is a Python Flask web application built as an interface for the Blockchain network running on Hyperledger Fabric. The application utilises REST APIs (generated using the Composer REST Server) to connect to the Blockchain network and perform GET, POST and PUT requests.

  • Technology

This application was built with the Flask Microframework. The UI of the application was built with MaterializeCSS, a front-end framework based on Material Design.

  • How to run

    1. Install the requirements using the command pip install -r requirements.txt.
    2. Run the application as: python application.py.
    3. Point your web browser to the address localhost:<port>.
  • Help

Please feel free to contact me with any questions/comments.

  • Navigating the Application

Once you start up the application, you should be able to see this page:

Browse to the Factory page, and select Production as the Pizza state. Press Submit.

You can see the Current Status has changed to production. Now, when filling the form, select Freezing. Press Submit.

Now, try Packaging.

Finally, select Distribution.

Now, select Transfer Ownership, to transfer the ownership of the pizza to the Wholesaler. This will automatically take you to the Wholesaler page, and you can see the transaction issued onto the Blockchain.

Select Transfer Ownership again.

Select Transfer Ownership one more time.

From here, the Customer can keep track of their pizza through the entire process.

Summary

We showed you how to create a simple business network using Hyperledger Composer Playground, export it and create a business network archive file, and deploy it to the Hyperledger Fabric. We also showed how you can spin up a REST server for your applications to consume, and demonstrated that fact by connecting a Python-based application to the Blockchain to realize the use-case of a frozen pizza supply chain.