Introducing Hyperledger Composer

Unit 02

IBM Skills Academy

V1.0, July 2018

Learning objectives

What is Hyperledger
Composer?

Application development

Effective administration

Summary
What you should be able to do

Upon completion of this unit, you should be able to:

• Understand Hyperledger Composer, its capabilities, and its role in modeling and implementing blockchain applications.

• How Hyperledger Composer fits into Hyperledger’s blockchain landscape.

• Explore the fundamental concepts to design, model, and implement business networks.

• Discover advanced topics such as connection profiles, ID cards, and integration into current systems.

3
Learning objectives

What is Hyperledger
Composer?

Application development

Effective administration

Summary
Blockchain refresher

• Blockchain builds on basic business concepts:

o Business Networks connect businesses.
o Participants are known and require an identity.
o Assets flow over business networks.
o Transactions describe asset exchange.
o Contracts underpin transactions.
o The ledger is a log of transactions.

• Blockchain is a shared, replicated ledger that has

consensus, immutability, finality, and provenance.

5
Hyperledger Composer: Accelerating time to value

Business application
https://hyperledger.github.io/composer/

• A suite of high-level application abstractions for business networks.

• Emphasis on business-centric vocabulary for quick solution creation. Hyperledger Composer

• Reduce risk, and increase understanding and flexibility.

Blockchain (Hyperledger Fabric)

• Features:
o Model your business networks, and test and expose through APIs.
o Applications invoke APIs transactions to interact with the business
network.
o Integrate existing systems of record by using LoopBack/REST.

• Fully open source, and part of Linux Foundation Hyperledger

• Try it in your web browser now: http://composer-playground.mybluemix.net/

6
Benefits of Hyperledger Composer

Increases Saves Reduces Increases

understanding. time. risk. flexibility.

Bridges simply from Develop blockchain Well-tested, efficient High-level abstraction

business concepts to applications more design conforms to makes it easier to
blockchain. quickly and cheaply. best practice. iterate.

7
An extensive, familiar, and open development toolset

composer-client
composer-admin

Data modeling JavaScript Web playground Client libraries

business logic

$ composer
Swagger

Editor support CLI utilities Code generation Existing systems and

data

8
User roles in a blockchain project
• Network service provider:
NSP
• Governs the network: Channels, membership, and so on.
• A consortium of network members or designated authority.

• Network service consumer:

• Operates a set of peers and certificate authorities on the network.
• Represents an organization on the business network.

• Business service provider:

• Develops blockchain business applications.
• Includes transaction, app server, integration, and presentation logic.

Business service consumer: Hosts application and User: Runs presentation logic, for
integration logic, which invokes blockchain example, on a mobile device or
transactions. dashboard.

A single organization might play multiple roles!

The developer role in a blockchain project
• Network service provider:
NSP
• Governs the network: Channels, membership, and so on.
• A consortium of network members or designated authority.

• Network service consumer:

• Operates a set of peers and certificate authorities on the network.
• Represents an organization on the business network.

• Business service provider:

• Develops blockchain business applications.
• Includes transaction, app server, integration, and presentation logic.

Business service consumer: Hosts application and User: Runs presentation logic, for
integration logic, which invokes blockchain example, on a mobile device or
transactions. dashboard.

A single organization might play multiple roles!

Learning objectives

What is Hyperledger
Composer?

Application development

Effective administration

Summary
Key concepts for the business service provider
Business service
provider Smart contract logic
Presentation
Uses logic
Develops Develops

User Model Transaction

Develops processor functions
Calls
Vehicle Order REST
interface Invokes
Hosts transaction
Business app Updates
Integration
Logic
Business Asset
Business logic registry
service
consumer
Defined in Transaction
registry

Defined in Updates

Participant
registry
12
Key concepts for a vehicle manufacture developer
Vehicle Manufacture
Developer

Mobile Manufacture smart contract.

Uses auction app
Develops Develops
@
Person Model Place order
ID,
Develops Update order status
email
Calls
REST
Place order
Vehicle Vehicle interface
Update order status
listing
Hosts Manufacturing [Registry operations]
Updates
back-end
service

Regulator System of record Vehicle

Manufacturer integration registry
Defined in Defined in
Business logic
Order
transaction
registry

Updates
Person Manufacturer Regulator
registry registry registry
13
Hyperledger Composer Architecture

14
 The business service provider develops three components

Smart contracts Business logic Presentation logic

• Implements the logic that is • Services that interact with the o Provides the front end for
deployed to the blockchain: registries: the user. May be several of
o Models describe assets, o Create, delete, update, these applications.
participants, and query, and invoke smart o Interacts with business
transactions. contracts. logic through standard
o Transaction processors o Implemented inside interfaces (for example,
provide the JavaScript business applications, REST).
implementation of integration logic, and o Hyperledger Composer
transactions. REST services. can generate the REST
o ACLs define privacy rules. o Hosted by the business interface from a model and
o May also define events and application consumer. a sample application.
registry queries.

15
Assets, participants, and transactions

Vehicle Vehicle Orders Place order

listing Member Manufacturer Regulator Updater order status

Transaction
processors

16
Access control
• It is possible to restrict which resources can be read
and modified by which participants:
o Rules are defined in an .acl file and deployed
with the rest of the model.
o Transaction processors can also look up the
current user and implement rules
programmatically.

• ACL rules can be simple (for example, everybody can

read all resources) or more complex (for example, only
the owner of an asset can do everything to it).

• The application supplies credentials (user ID/secret) of

the participant when connecting to the Hyperledger
Fabric network:
o This also applies to Playground!
o Remember to grant System ACL all access if
necessary.
17
Events and queries
• Events allow applications to act when a transaction occurs:
o Events are defined in models.
o Events are emitted by transaction processor scripts.
o Events are caught by business applications.
• Caught events include transaction IDs and other relevant information.

• Queries allow applications to perform complex registry searches:

o They can be statically defined in a separate .qry file or generated
dynamically by the application.
o They are invoked in the application by using buildQuery() or
Query().
o Queries require the blockchain to be backed by CouchDB.

• Hyperledger Fabric uses LevelDB as the default state database, which

we will explore in later units. It acts as a key-value data store.
CouchDB is an optional alternative external state database that
provides extra query support.

18
Smart contract development: Hyperledger Composer Playground

• Web tool for defining and testing Hyperledger

Composer models and scripts.

• Designed for the application developer:

o Define assets, participants, and
transactions.
o Implement business rules within
transaction processor scripts (Smart
Contracts).
o Test by populating registries and invoking
transactions.

• Deploy to instances of Hyperledger Fabric, or

simulate completely within a browser.

• Install on your machine or run online at

http://composer-playground.mybluemix.net.
19
General-purpose development: Visual Studio Code
• A Hyperledger Composer extension is available for this popular
tool.

• Features to aid rapid Hyperledger Composer development:

o Edit all Hyperledger Composer file types with full syntax
highlighting.
o Validation support for models, queries, and ACLs.
o Inline error reporting.
o Snippets (press Ctrl+Space for code suggestions).
o Generate UML diagrams from models.

• Install directly from Code Marketplace.

20
Creating the business and user applications

• The JavaScript business applications

require() function uses the NPM “composer-
client” module:
o Provides the API to access assets,
participants, and transactions.
o A RESTful API (through LoopBack)
can be generated.

• A command-line tool is available to

generate user command-line or Angular2
applications from a model. Also helps with
the generation of unit tests to help ensure Model

quality code.

21
Debugging

• Playground Historian enables you to view all

transactions. See what occurred and when.

• Diagnostics framework enables application-level trace:

o Uses the Winston Node.js logging framework.
o Application logging that uses the DEBUG env
var.
o Hyperledger Composer logs are sent to stdout
and ./logs/trace_<processid>.trc.

• Hyperledger Fabric chaincode tracing is also possible.

• For more information, go to the following website:

https://hyperledger.github.io/composer/problems/diagnostics.html

22
Learning objectives

What is Hyperledger
Composer?

Application development

Effective administration

Summary
There are two user roles with “administration” responsibility
• Network service provider:
NSP
• Governs the network: Channels, membership, and so on.
• A consortium of network members or designated authority.

• Network service consumer:

• Operates a set of peers and certificate authorities on the network.
• Represents an organization on the business network.

• Business service provider:

• Develops blockchain business applications.
• Includes transaction, app server, integration, and presentation logic.

Business service consumer: Hosts application and User: Runs presentation logic, for
integration logic, which invokes blockchain example, on a mobile device or
transactions. dashboard.

A single organization might play multiple roles!

Key concepts for administrators Network
service
consumer Smart contract logic

Packages
User Connection Creates Business
profile network
Issues
archive
Issues
Customizes
Business Refers to and deploys
User service
identity consumer
identity
REST
interface
Connects Asset Participant Transaction Identity
Business app registry registry registry registry

Integration
Hosts …
logic
Business Chaincode container Ledger
Business network
Business logic
service card Hyperledger Fabric
consumer (Connection profile +
Peer
business service
consumer identity)
25
The network service consumer packages resources into a BNA file

• Business network archive (.BNA) is a package of the

resources that are used by Hyperledger Fabric: Business network archive
o Model files (.CTO).
o Transaction processors (.JS).
o Access Control Lists (.ACL). model.cto logic.js permissions.acl

o Static queries (.QRY).

?
o Documentation and versioning (.MD).
o It does not contain the client application. queries.qry readme.md

• The BNA simplifies deployment of blockchain and

promotion between environments, such as TAR, WAR, composer archive create –archiveFile my.bna
--sourceType module --sourceName myNetwork
EAR, JAR, and BAR.

• Create BNA files from Playground or a command line,

and build from a file system or NPM module.

26
Connection profiles to Hyperledger Fabric

• Use connection profiles to describe Hyperledger Fabric connection

parameters. One connection profile is required per channel.
• Not necessary for a web-based simulation.
• Enrollment in Hyperledger Fabric network is required. You issue a
Hyperledger Fabric identity from the Hyperledger Composer
participants.
• Connection profiles are used by Hyperledger Composer only. There
are plans to implement common connection profiles that can be used
by both Hyperledger Fabric and Hyperledger Composer.

27
 Participant identity Key component; make sure
• The network service consumer issues network it is understood..
participants with an identity to connect to
Hyperledger Fabric:
o Issued as a Hyperledger Fabric user
ID/secret.
o Automatically swapped for a certificate on first
use.
o Packaged in a business network card and
supplied when the client application connects.
• Hyperledger Composer Participant to Hyperledger Fabric Identity
mapping is stored on the blockchain in an identity registry.
• Usually, only business service consumers have a Hyperledger Fabric
identity. Users log in to the business application by using a
separately managed identity; blockchain transactions are invoked by
proxy.
• Manage identity from Playground, JavaScript, REST, or the CLI. For
example, you can test a connection, issue an identity, bind an
identity to a participant, revoke an identity, and list identities.

28
Business network cards
• Business network cards are a convenient packaging of identity and connection profile:
o Contains everything that you need to connect to a blockchain business network.
o Each card refers to a single participant and single business network.
o Analogous to an ATM card.

• Manage cards from both Playground and the CLI:

o Create, delete, export, import, and list.
o Create requires a user ID/secret or certificate/private
key.
• Use cards to connect to Hyperledger Fabric from
Playground, CLI, or from within your application.
composer network deploy -a my.bna -c my.card

29
Systems of record integration
• Domain-specific APIs are attractive to mobile and web
developers. Resources and operations are business-
meaningful.
• Hyperledger Composer uses the LoopBack framework to
create REST APIs: https://loopback.io/.
• There are extensive test facilities for REST methods that
use LoopBack.
• Secured by using JS Passport, with 400+ options for
authentication. Support for API keys to secure REST
APIs.
• Hyperledger Composer provides back-end integration
with any LoopBack compatible product:
o Examples include IBM App Connect Enterprise and
API Connect, StrongLoop.
o Outbound and Inbound (where supported by
middleware).

30
Using LoopBack: Examples

• IBM App Connect Enterprise: • Node-RED:

o IBM App Connect Enterprise V10 o Pre-built nodes are available for
contains a LoopBack connector. Hyperledger Composer.
o This example takes input from a file, o Connect to hardware devices, APIs, and
SAP, or IBM MQ. online services.
o Data mapping from CSV, BAPI/IDOC, or o Install direct from Node-RED UI by
a binary form to JSON model definition. clicking Manage Palette -> Install ->
node-red-contrib-composer.
31
Hyperledger Composer outlook

• Still early in the product lifecycle.

• Many improvements are planned. See

https://github.com/hyperledger/composer/issues.

• An active development community:

o Open community calls every two weeks
o Rocket Chat
o Stack Overflow

• Get involved by engaging with the development community

at:
https://github.com/hyperledger/composer/wiki/Community

32
Learning objectives

What is Hyperledger
Composer?

Application development

Effective administration

Summary
Unit summary

This unit covered an introduction into Hyperledger Composer with the following key takeaways:
• Hyperledger Composer is a suite of open source tools and application abstractions that build and model
blockchain-based business networks.
• Hyperledger Composer is the fastest way to start prototyping blockchain applications.
• An event subscription model enhances the interaction possibilities with applications.
• A combination of connection profiles and identities, which are bundled into business network cards, are the
authentication mechanism to connect to a business network.
• For systems of record integration, Hyperledger Composer uses LoopBack, which itself supports various
interfaces, such as REST, IBM App Connect Enterprise, and IBM MQ.

34
Checkpoint questions

1) What are the key characteristics of Hyperledger Composer?

a) Systems of record integration that uses REST services.

b) Closed source application.

c) Suited for non-technicians to model business networks.

d) Integrations are available for various code editors.

e) A suite of high-level application abstractions for blockchain business networks.

f) All of the above.

35
Checkpoint questions

2) What are the three models that describe a Hyperledger Composer application?

a) Assets, participants, and consensus

b) IoT, participants, and transaction processors

c) Assets, participants, and transactions

d) REST, ACLs, and models

36
Checkpoint questions

3) Select all statements that are true:

a) Events are fired by transaction processor scripts.

b) Events are fired by asset models.

c) Queries can be used only if statically defined in separate *.qry files.

d) Queries are only supported if the Hyperledger Fabric blockchain is backed by CouchDB.

37
Checkpoint questions

4) Connection profiles encapsulate connection parameters for Hyperledger Fabric and are required on a
channel basis.

a) True. One connection profile for each channel is required.

b) False. One connection profile per business network is required.

38
Checkpoint questions

5) What are true statements for systems of record integration?

a) Domain-specific APIs are preferred for the integration of mobile and web applications.

b) Fine granular, low-level APIs are preferred for the integration of mobile and web applications.

c) Hyperledger Composer uses the LoopBack framework to expose REST APIs.

d) Node-RED supports Hyperledger Composer and provides pre-built nodes.

39
Checkpoint answers

List the correct answer for each question.

1. a, c, d, e

2. c

3. a, d

4. a

5. a, c, d

40
Exercise introduction

We continue with the introduced example of a vehicle manufacturing process and will implement such a
network on Hyperledger Composer.

We start with Hyperledger Composer Playground and become familiar with the tools. We continue by creating
models for participants, assets and transactions, and use the CLI tools to deploy business network archives to
a Hyperledger Fabric environment.

To get experience for the integration of applications like websites and mobile apps, we look at the powerful
capabilities of LoopBack and Swagger.

41
References

For more information about the topics that are covered in this unit, see the following resources:

• https://hyperledger.github.io/composer

• https://composer-playground.mybluemix.net

• https://hyperledger.github.io/composer/latest/tutorials/tutorials.html

• https://hyperledger.github.io/composer/latest/introduction/introduction.html

42
Thank you.
IBM Skills Academy

www.ibm.com/blockchain

developer.ibm.com/blockchain

www.hyperledger.org

© Copyright IBM Corporation 2017. All rights reserved. The information contained in these
materials is provided for informational purposes only, and is provided AS IS without warranty
of any kind, express or implied. Any statement of direction represents IBM's current intent, is
subject to change or withdrawal, and represents only goals and objectives. IBM, the IBM
logo, and other IBM products and services are trademarks of the International Business
Machines Corporation, in the United States, other countries or both. Other company, product,
or service names may be trademarks or service marks of others.