Deploy a blockchain business network to the cloud using the IBM Blockchain
Starter Plan

The easy way to launch a pre-production network and run your first
application on it

In this tutorial, you’ll deploy an existing sample business network, the
Car Auction network, to the cloud, specifically to the IBM Blockchain Platform Starter Plan, now free in beta. Once you
deploy the sample network, you can start developing, demoing, and staging
your blockchain applications on a simulated multi-organization
network.

This tutorial is NOT about Hyperledger Fabric, which serves as the
underlying implementation of the IBM Blockchain Platform, nor about Hyperledger Composer, which provides a modern toolset to build
business networks and applications rapidly. Hyperledger Composer exposes a
business model and abstracts away the complexities involved.

This tutorial IS about deploying an existing sample business network
created using Hyperledger Composer to the free Starter Plan instance
available on the IBM Cloud.

Learning objectives

  • Deploy the Car Auction sample network to the IBM Cloud.
  • Start the sample network.
  • Generate REST APIs for the deployed sample network.
  • Generate and run an Angular app that uses the REST APIs.

Time to complete this tutorial

  • Approximately 45 minutes.

Prerequisites

You need the following software installed locally:

  • Mac OSX only – Install Xcode
  • npm v5.5.1 or
    higher
  • Node.js v8.9 or
    higher
  • git v1.7 or
    higher
  • Python 2.7.10 or higher

Let’s get started

For this exercise, let’s deploy the hugely popular sample “Car Auction” network (built using Hyperledger Composer) to the
Starter Plan instance. This image shows the participants, assets, and
typical transactions on this sample network:

Hyperledger Composer enables you to rapidly build business networks and
applications. To build a business network, you need to define a business
model in a .cto file, which contains the following:

  • Participants
  • Assets
  • Transactions

In the Car Auction network, the participants are
represented in the business model using the Auctioneer and
Member types as shown:

abstract participant User identified by email {
  o String email
  o String firstName
  o String lastName
}

participant Member extends User {
  o Double balance
}

participant Auctioneer extends User {
}

Similarly, assets are represented in the Car Auction
network using the types Vehicle and
VehicleListing as shown:

enum ListingState {
  o FOR_SALE
  o RESERVE_NOT_MET
  o SOLD
}

asset Vehicle identified by vin {
  o String vin
  --> Member owner
}

asset VehicleListing identified by listingId {
  o String listingId
  o Double reservePrice
  o String description
  o ListingState state
  o Offer[] offers optional
  --> Vehicle vehicle
}

And transactions are represented in the Car Auction
network by the types Offer and CloseBidding as
shown:

transaction Offer {
  o Double bidPrice
  --> VehicleListing listing
  --> Member member
}

transaction CloseBidding {
  --> VehicleListing listing
}

To exchange ownership of assets, participants submit transactions on the
business network.

Set up your local environment

  1. To deploy the existing Car Auction network to the IBM Cloud, you need
    the following software installed locally, as mentioned previously:

    • Mac OSX only – Install Xcode
    • npm v5.5.1
      or higher
    • Node.js v8.9
      or higher
    • git
      v1.7 or higher
    • Python 2.7.10 or higher
  2. If you’ve already been playing with Hyperledger Composer, then you
    should first uninstall and re-install the specified version of
    Hyperledger Composer that is compatible with the Starter Plan instance
    as shown:

    $ rm -rf ~/.composer
    $ npm uninstall -g composer-cli
    $ npm uninstall -g composer-rest-server
    $ npm uninstall -g generator-hyperledger-composer
    $ npm install -g composer-cli@0.18.1
    $ npm install -g composer-rest-server@0.18.1
    $ npm install -g generator-hyperledger-composer@0.18.1
  3. Next, you should clone the GitHub repo that contains the artifacts for
    the Car Auction network as shown:

    $ cd ~/Workdir
    $ git init business-networks
    $ cd business-networks
    $ git remote add -f origin https://github.com/hyperledger/composer-sample-networks
    $ git config core.sparseCheckout true
    $ echo "packages/carauction-network/" >> .git/info/sparse-checkout
    $ git pull origin master

At this point, the artifacts for the Car Auction network should be
available in the
~/Workdir/business-networks/packages/carauction-network
folder. This folder will serve as the root folder. From there, you will
execute the commands to build and deploy the business network to the
Starter Plan instance.

Launch the IBM Blockchain Starter Plan instance
on the IBM Cloud

  1. Create an IBM Cloud account, if you don’t have one
    already.
  2. Once you have an account, launch the Starter Plan instance, currently
    available only in the US South region, as shown:

  1. When the Starter Plan instance is up and running, you can monitor the
    organizations and the peers that are set up by default for you.
    Typically, you will have two organizations each with a Certificate
    Authority, Ordering Service, and Endorsing/Validating peer. To look at
    these elements, you can switch between the organizations using the
    drop-down under the profile icon on the top-right corner, as shown:

The resulting distributed ledger of transactions will be stored on
the peers in each organization. For more details, see the Hyperledger Fabric documentation.

  1. For the next set of steps, we will use the Connection Profile for
    Company A (org1). So, select Company A in the top-right corner before
    you start the next set of steps.

Download the Connection Profile

  1. Download the Connection Profile for Company A (org1) to your local
    filesystem, as shown:

  1. Note the value of the enrollSecret property from the raw
    JSON. (You can also get the value of the enrollSecret
    property from the downloaded JSON file by opening it up in an editor
    and searching for enrollSecret.) You will use the
    enrollSecret value in subsequent steps to create
    certificates and more.
  2. Rename and copy the downloaded json file to the root folder that was
    setup in the earlier steps as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ mv ~/Downloads/creds_*_org1.json connection-profile.json

Create the Certificate Authority Card

  1. Using the connection-profile.json and the
    enrollSecret value that you noted in the previous step,
    create a Certificate Authority card for Company A (org1) as shown,
    replacing <your-enrollSecret> with the value that
    you noted earlier:

    $ composer card create -f ca.card -p connection-profile.json -u admin -s <your-enrollSecret>
  2. Import the newly created card as shown:
    $ composer card import -f ca.card -n ca
  3. With the card containing the enrollSecret successfully
    imported, request the valid public/private keys for the admin from the
    Certificate Authority as shown:

    $ composer identity request --card ca --path ./credentials

At this point,
~/Workdir/business-networks/packages/carauction-network/credentials should
contain the public and private keys for the admin.

Add a certificate to the Starter Plan

Initially, the Starter Plan instance does not have any certificates in the
Members node, as you can see:

  1. Click on the Channels node on the left to see that
    the Block Height is 3, indicating the number of
    transactions that have been performed behind the scenes so far. Click
    on 3 to poke around to see the GENESIS block and check the details for
    each of the invocations.
  2. Open the public key for the admin located in
    ~/Workdir/business-networks/packages/carauction-network/credentials/admin-pub.pem
    in an editor and copy its contents to the clipboard. You will add this
    public key to the Starter Plan instance, as shown:
  1. Once the public key is added, you need to sync the certificate across
    peers using the Channels node, as shown:
  1. Click the Submit button to complete the process of
    syncing the certificate. At this point, if you go back and look at the
    Channels node, you will see that the Block Height has
    been updated to 4. This indicates that every change to the environment
    is also tracked as a transaction in the immutable distributed
    ledger.

Create and import a business network card for
the admin

With certificates synced across peers, you can create business network
cards to install Hyperledger Composer and then deploy/start the chaincode
or the business network on the Starter Plan instance.

Create an admin card with channel admin and peer admin roles, and then
import the newly created card as shown:

$ cd ~/Workdir/business-networks/packages/carauction-network
$ composer card create -f adminCard.card -p connection-profile.json -u admin
  -c ./credentials/admin-pub.pem -k ./credentials/admin-priv.pem
  --role PeerAdmin --role ChannelAdmin
$ composer card import -f adminCard.card -n adminCard

Install and start the business
network

In this step, you’ll use the adminCard created in the previous
step, with privileges to install and start a business network, to install
the Car Auction network to the Starter Plan instance.

  1. To be able to install and start a business network, you need to first
    create a Business Network Archive (.bna) file by zipping up the
    necessary artifacts as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer archive create -t dir -n .
  2. This will result in the creation of
    carauction-network@0.x.y.bna file, where
    @0.x.y represents the version specified in the
    package.json file. Since the Starter Plan instance does not accept
    files with @ in the name, rename the file as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ mv carauction-network@*.bna carauction-network.bna
  3. Install the business network and the Hyperledger Composer runtime to
    the Starter Plan instance as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer runtime install -c adminCard -n carauction-network
  4. If the previous step fails, then wait for a few seconds and give it
    another shot.
  5. Once the runtime and the business network are successfully installed,
    start the business network on the Starter Plan instance as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer network start -c adminCard -a carauction-network.bna -A admin
      -C ./credentials/admin-pub.pem -f delete_me.card

    You may run into sporadic issues such as
    REQUEST_TIMEOUT. Once again, wait for a few seconds
    and try again. In addition to starting the business network, the
    previous command also uses the -A switch to specify
    the id of the network-administrator who will be responsible for
    creating participants and other bookkeeping actions for the
    specific network.

  6. Once the command is successful, check the Block Height
    under the Channels node in the UI to see it updated to 5, as well as
    details about the newly installed/started Car Auction network.
  7. Delete the redundant delete_me.card that was generated by
    the previous command as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ rm delete_me.card

Create a card for the network
administrator

While starting the business network in the previous section, we used the
-A command-line argument to specify the id of the network
administrator who will be responsible for running the network by issuing
identities and such to other participants on the network. Let’s create the
business network card for the network-admin.

  1. To create the business network card for the network admin, use the
    following command:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer card create -n carauction-network -p ./connection-profile.json
      -u admin -c ./credentials/admin-pub.pem -k ./credentials/admin-priv.pem
  2. Import the card using the following command:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer card import -f admin@carauction-network.card

At this point, the business network is operational on the Starter Plan
instance.

Generate REST APIs for the business
network

Once the business network is running on the Starter Plan instance, you can
use composer-rest-server@0.18.1 to generate REST APIs that
can be exercised from web apps as well as native apps. All changes to the
participants and assets will be tracked as transactions in the distributed
ledger, and you can observe the Block Height grow under the
Channels node.

  1. If you have not installed composer-rest-server@0.18.1,
    please install it as shown:

    $ npm install -g composer-rest-server@0.18.1
  2. To connect to the business network running on the Starter Plan
    instance, make sure that you are starting
    composer-rest-server@0.18.1 from the same root directory
    that contains the connection-profile.json file as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer-rest-server -c admin@carauction-network -n never
  3. At this point, you can point your browser to
    http://localhost:3000 to browse and exercise the REST
    APIs to create new participants and assets, and submit transactions
    while watching the Block Height under Channels node grow.
    If you look at the auction.cto file that defines the
    business model of the Car Auction network, you will recall that
    participants are represented by Auctioneer and
    Member types; assets are represented by
    Vehicle and VehicleListing types; and
    transactions are defined using Offer and
    CloseBidding types.

This video shows the REST APIs being
exercised using the JSON payload:

In the above video, you can see the following participants being
created:

  • Bobby Da Boss with email
    bobby.da.boss@example.com is created as an
    Auctioneer to run the auction.
  • James Bond with a balance of $1000 and email
    address james.bond@example.com is created as a
    Member.
  • Jason Bourne with a balance of $2000 and
    email address jason.bourne@example.com is created as a
    Member.
  • Bruce Wayne with a balance of $5000 and email
    address bruce.wayne@example.com is created as a
    Member.

After creating each of these participants, you can see the
Block Height under the Channels node increasing as
the changes are recorded as transactions in the distributed
ledger.

In the video, you will also see the following assets being
created:

  • Vehicle identified by BM_001 and owned by
    bruce.wayne@example.com is added to the network.
  • Bruce Wayne puts up one of his Batmobiles, identified by
    BM_001, for sale by creating a VehicleListing
    identified by L1 and an asking price of $500.

Once again, after each of these actions, the
Block Height under the Channels node increases.

Finally, in the video, you will also see the transactions being
submitted:

  • An Offer is made on behalf of James Bond for
    $800.
  • An Offer is made on behalf of Jason Bourne for
    $1200.

Bobby Da Boss, the Auctioneer, will submit a
CloseBidding transaction eventually. And, you can see
the ownership of the Batmobile change from bruce.wayne@example.com
to jason.bourne@example.com. You will also see the $1200 added to
Bruce Wayne’s balance. And, the same amount deducted from Jason
Bourne’s balance.

You will also see the Block Height increasing with
transactions being submitted by the participants and the assets
exchanged. Each of these changes is recorded as a transaction in
the distributed ledger that is stored on the peers in the two
organizations. You can observe the Block Height grow
after a change is made as shown in the above video.

Generate an Angular app for the business
network

You can exercise the REST endpoints generated in the previous step by an
Angular app generated using the Yeoman generator.

  1. Install generator-hyperledger-composer@0.18.1 and
    yo as shown:

    $ npm install -g generator-hyperledger-composer@0.18.1
    $ npm install -g yo
  2. Since composer-rest-server@0.18.1 is running in the
    current tab of your terminal, open another tab or window for your
    terminal for the next set of steps. Also, you should be in the root
    directory that contains connection-profile.json to
    generate the Angular app as shown:

    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ yo hyperledger-composer:angular
    
    Welcome to the Hyperledger Composer Angular project generator
    ? Do you want to connect to a running Business Network? Yes
    ? Project name: angular-app
    ? Description: Hyperledger Composer Angular project
    ? Author name: foo
    ? Author email: foo@example.com
    ? License: Apache-2.0
    ? Name of the Business Network card: admin@carauction-network
    ? Do you want to generate a new REST API or connect to an existing REST AP
    I?  Connect to an existing REST API
    ? REST server address: http://localhost
    ? REST server port: 3000
    ? Should namespaces be used in the generated REST API? Namespaces are not
    used
    Created application!

    This will generate an application in the angular-app folder.

To run the generated Angular app do the following:

$ cd ~/Workdir/business-networks/packages/carauction-network
$ cd angular-app
$ npm start

The app will be compiled, and you can eventually interact with it by
pointing your browser to http://localhost:4200. This video
shows the
Vehicle and VehicleListing assets that were
created and updated using the REST APIs directly as part of the previous
section:

Conclusion

You now know how to use Blockchain-as-a-Service in the
Starter Plan on the IBM Cloud. You’re ready to take advantage of deploying your
own business networks, so that you can take ’em out for a spin. And, once
you’re satisfied, you can seamlessly move your deployment to the
Enterprise Plan.

Next steps

  • Now that you’ve deployed a sample network, learn how to create
    business networks from scratch using Hyperledger Composer in our
    popular series, Hyperledger Composer basics, by Steve
    Perry.
     
  • Stay in the know with the monthly Blockchain Newsletter for
    developers. Check out the current issue and subscribe.
     
  • Check out the many code patterns, which provide roadmaps
    for solving complex problems with blockchain technology, and include
    architecture diagrams, code repos, and additional
    reading.
     
  • Stop by the Blockchain Developer Center. It’s your
    source for free tools and tutorials, along with code and community
    support, for developing and deploying blockchain solutions for
    business.

About the author

Sanjay Saxena is an IBM Senior Technical Staff Member and Developer
Advocate for the IBM Cloud. He is currently focused on emerging
technologies such as Blockchain, IoT, AR/VR, and Jupyter/Spark. Sanjay has
more than two decades of system development experience, including
MVC-based metadata-driven application development frameworks, real-time
communications, pub/sub messaging across Java, C#, Objective-C, and
JavaScript. A husband and father of two, Sanjay enjoys skiing, STEM, and
mixing flavors and spirits for the perfect cocktail.


Downloadable resources


#awvi,#blockchain

via IBM developerWorks : Cloud computing https://ibm.co/2cihRPX

May 1, 2018 at 04:00AM