Prototyping with Hyperledger Caliper
Argent Crypto, Inc. is a Canadian firm dedicated to enabling the decentralized future through personalized blockchain consulting and investment services. This publication features the expertise and knowledge from a collective of blockchain developers, crypto-enthusiasts, traders, and technology professionals. If you’d like to contribute to this publication, message us at: info@argentcrypto.com
This blog post includes:
- An introduction to using Hyperledger Caliper
- Commands to bootstrap a Hyperledger Composer project to be used with Caliper
- Hints on how to configure Caliper for different test runs
Prototyping with Hyperledger Caliper
One of the recurring themes for developers new to the Hyperledger projects is simply trying to untangle the differences between them — Fabric, Sawtooth, Iroha, Burrow, Composer — it can be overwhelming. Online courses are of middling quality and offer little hands-on experience, and the documentation is above-average but seems heavily geared towards the network administration side of things rather than developers.
In this article I’d like to demonstrate the advantages of starting with Hyperledger Caliper, and prototyping your development in many different Hyperledger projects when you’re first starting out. Not only does this Caliper-first/test-first approach give you the feeling of what development might look like for your concept, but at the end of the prototype phase, you have built-in testing & performance metrics to publish with your Proof-of-Concept, to help justify the future path you advocate for. What boss isn’t going to love that?
This first article covers getting started with Caliper and the first prototype we’ll try, using Hyperledger Composer. The next article will cover prototyping with “raw” Fabric (i.e. without Composer), as well as Sawtooth.
Let’s get started.
Step 1: Install Caliper and Run the Samples
This should hopefully be as simple as following the instructions in the README file from the hyperledger-caliper github repository. Follow the link here and get the codebase cloned onto your local machine:
https://github.com/hyperledger/caliper
Once you have cloned the caliper repository and have the prerequisites installed, go ahead and follow the instructions under the “Install blockchain SDK’s” section for Fabric, Sawtooth and Composer.
NOTE: At the time of writing, Hyperledger is up to version 1.2, and Composer is at 0.20.0. You should update the version numbers listed for Composer in the README instructions.
Once installed, issue the following command in the root caliper directory to run Caliper with the out-of-the-box benchmarks for a sample Hyperledger Composer app on the included “basic sample network”:
node benchmark/composer/main.js -c config-composer.json
Step 2: Composer Prototype
We’re going to do the first prototype with Hyperledger Composer, simply because prototyping is exactly what it’s great at. It scaffolds all the network components for you, and can even generate some REST API’s for ease of interacting with your blockchain. It frees you to concentrate on your schema (model) and the business logic for transactions between participants.
Bootstrap a Composer Project with Yeoman
For this article, I’ll assume you haven’t already got a Composer business network created, so we’ll create a quick one from scratch. (If you do already have one, just copy and paste the whole project directory to caliper/src/contract/composer).
a) Install yeoman and generator-hyperledger-composer:
npm install -g yo
npm install -g generator-hyperledger-composer
b) Generate a skeleton composer project inside the caliper source folder:
cd <caliper install dir>/caliper/src/contract/composer
yo hyperledger-composer
Follow the prompts to create a business network app. If you choose to create an empty model file, you will need to write a model before you can compile & test it with Caliper. For the purpose of proceeding with this tutorial, you can just generate the populated sample network if you’re not too familiar with Composer yet.
For the rest of the tutorial, we’ll pretend we created a business network called “finance-network”.
Compile the BNA file.
cd finance-network
composer archive create -a finance-network@0.0.1.bna -t dir -n .
Don’t forget the last period in the command above. If you need a primer on what BNA files are and how Composer works, see the Hyperledger Composer docs.
Configure Caliper’s Sample Network environments to install your new BNA
Open the file network/fabric/2-org-1-peer/composer.json. At the top, there is a property called “chaincodes” that looks like this:
“chaincodes”: [{“id”: “basic-sample-network”, “version”: “0.1.0”, “path”: “src/contract/composer”, “orgs”: [“Org1”, “Org2”], “loglevel”: “INFO”}],
Copy and paste the one array object, and then update the “id”, “version”, and “path” properties of the new one to reflect the project you created. Note that the “id” must match the name of the folder of your project. For our example, it would now look like
“chaincodes”: [
{“id”: “basic-sample-network”, “version”: “0.1.0”, “path”: “src/contract/composer”, “orgs”: [“Org1”, “Org2”], “loglevel”: “INFO”},{“id”: “finance-network”, “version”: “1.0.0”, “path”: “src/contract/composer”, “orgs”: [“Org1”, “Org2”], “loglevel”: “INFO”}],
This is configuring the 2-org-1-peer network to install your BNA when it spins up. You could update the other network configurations in a similar manner if you wish to use them with your tests as well, but for now we’ll leave them. The 2-org-1-peer network is the default network that is used if no other network is specified when you run the caliper benchmarking.
Create the Test Script
Unless you’re using the default generated model file, you’ll need to create a test script that uses YOUR model for the benchmarking framework to execute.
Copy the benchmark/composer/composer-samples/basic-sample-network.js file and rename it to something like “finance-network.js”. Open that file and update the “init” and “run” functions to match your model. The “init” function is run once when the framework starts, and the “run” function is executed continuously based on the parameters you’ll pass to Caliper. Use the init function to create your network participants and assets, and the run function to perform transactions between them.
Configure Caliper for your Test Run
Take a look at benchmark/composer/config-composer.json. In the JSON there is a section called “rounds”, which is where you configure your test iterations that Caliper will perform.
Copy benchmark/composer/config-composer.json to benchmark/composer/config-financenetwork-composer.json, and update the rounds configuration to what you’d like to try. Make sure you update the “callback” property of each round to point to YOUR test script that you created above (myapp-sample-network.js, instead of basic-sample-network.js).
Run Caliper against your BNA and Test Script
Run the following command:
node benchmark/composer/main.js -c config-financenetwork-composer.json
And that’s it! You’ve successfully installed Caliper and Composer, created a business network archive in Composer, and deployed and tested it using Caliper. In the next article we’ll port your model and logic over to a similar implementation in Fabric, and then again in Sawtooth.
Final Words
To summarize the various configurations inside the caliper folder that we changed:
src/contract/composer/finance-network: is the Composer project we created with Yeoman that includes our model and chaincode.
network/fabric/2-org-1-peer/composer.json: was updated to install our custom Composer project chaincodes into the network when it starts.
benchmark/composer/composer-samples/finance-network.js: was the test script we created to match our Composer model and perform the test transactions
benchmark/composer/config-financenetwork-composer.json: was the caliper test run configuration we created that uses our test script for a callback.
Try playing around with different “rounds” configurations for Caliper, and add more complexity to your Composer model, chaincode, and test script.
BONUS TIP: When you start wondering why Composer turns your laptop into molten slag, try reconfiguring the 2-org-1-peer network to use LevelDB instead of CouchDB. It makes a big difference in performance.
(Hint: Comment out line 62 and 63 of the docker-compose.yaml file for the network.)
