Archived | Track pizza shipments with blockchain
Connect a Python app to the blockchain for a frozen pizza supply chain.
Note: IBM Blockchain Platform now utilizes Hyperledger Fabric for end-to-end development. Users may use Hyperledger Composer at their choice, but IBM will not provide support for it.
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.
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.
- Download Ubuntu: https://www.ubuntu.com/download/desktop
- Download VirtualBox https://www.virtualbox.org/wiki/Downloads
- Instructions for setting up Ubuntu on VirtualBoxhttps://askubuntu.com/questions/142549/how-to-install-ubuntu-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.
For Mac Users
- Please follow the steps here: Setting up Hyperledger Fabric on a Mac
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.
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/v0.19/installing/development-tools.html
Set up the Business Network
Head over to the Composer Playground: https://composer-playground.mybluemix.net/
Select “Deploy a Business Network”
Under the “Model Network Starter Template”, select “browse”, and choose the email@example.com 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.
pizza-on-the-blockchainfor the network name, and desired information for description, author name, and author email.
Apache-2.0as the license.
org.acme.biznetas the namespace.
cdinto the folder which was just created and replace the contents of
/pizza-on-the-blockchain/lib/org.example.biznet.ctowith the model file generated earlier on in the tutorial.
Replace the contents of
/pizza-on-the-blockchain/lib/logic.jswith the script file generated earlier on in the tutorial.
Create a new file in the
permissions.acland 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-blockchaindirectory, enter the following command:
composer archive create -t dir -n .
After the command has run, a business network archive file called
firstname.lastname@example.org 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.
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
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-blockchaindirectory, run the following command:
composer network start --card PeerAdmin@hlfv1 --networkAdmin admin --networkAdminEnrollSecret adminpw --archiveFile email@example.com --file networkadmin.card
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
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
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-blockchaindirectory and run the following command:
admin@pizza-on-the-blockchainas 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
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.
How to run
- Install the requirements using the command
pip install -r requirements.txt.
- Run the application as:
- Point your web browser to the address
- Install the requirements using the command
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.
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.
Transfer Ownership again.
Transfer Ownership one more time.
From here, the Customer can keep track of their pizza through the entire process.
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.