Introduction to Fabric Composer

This article (for CIOs, developers, analysts and IT architects) explains the value proposition and high-level features of Fabric Composer.

Fabric Composer (Composer) is an Open Source tool to define, deploy and integrate with business networks. Fabric Composer makes it easy for technical analysts and developers to create business networks that use a distributed-ledger to exchange information. The Composer runtime executes on the Open Source Hyperledger Fabric blockchain, storing all data on the distributed ledger, and executing all business logic on Hyperledger Fabric.

Business Networks and Distributed Ledgers

Business networks underpin all modern economies and facilitate the exchange of assets in return for services and goods. Business networks come in all shapes and sizes, from peer to peer marketplaces, hub-and-spoke, auctions, complex supply-chains, to industry consortia of co-operating and competing peers. Varying degrees of trust exist between the members of a business network and different members of the network require different privacy guarantees around the data and transactions flowing through the business network.

However, today, companies struggle to share accurate information in a timely manner with the other companies in their business networks. Information sharing often consists of paper forms, emails, spreadsheets, transferring flat-files, and complex messaging solutions. These inter-company inefficiencies result in high costs, slow settlement of trades, lack of regulatory visibility, limitations in end-to-end provenance, errors, disputes and the associated legal fees.

Source: https://www-935.ibm.com/services/us/gbs/thoughtleadership/blockchain/

Business networks are dynamic, frequently involve costly manual processes, and when dispute occur, often incur delays and legal fees. The promise of distributed ledger technology (based on the concept of a blockchain) is to streamline these inter-company interactions through digitisation and automation. In some industries a government regulator plays an important role in the business network, and regulatory compliance is a major challenge and cost for all members of the business network.

The members of a business network use a distributed ledger to share a common view of the state of the business network. This state can range from a shared view of the ownership of an asset, to the location of a shipping crate, to the balance of an account or the provenance (history) associated with an asset.

Technical Challenge

Traditionally blockchain development has been hard. It has required learning arcane terminology, cryptography, distributed systems architecture, consensus algorithms, working with low-level remote procedure call interfaces, understanding “novel” threading and re-entrancy models, and to cap it all learning a new programming language! Every project has been a “first of a kind” with limited scope for re-use and sharing.

For application developers and enterprise architects it was a frustrating experience as it often took weeks to build a simple proof of concept application.

To compound matters, the tools for blockchain-based development have not integrated well with best-of-breed tools and processes for enterprise application development: continuous integration, DevOps pipelines, blue-green rolling deployment, artifact repositories, sharing/versioning of binary assets as well as versioning of source assets.

Composer is a modern programming model and toolset for building blockchain applications. Rather than reinvent a new programming language for writing business logic it uses the most popular language on the planet: Javascript. It provides a rich Javascript SDK to interact with the business network and to build applications, but the business logic that runs on the business network is also written in Javascript. Learn one programming language and you can develop applications that go from the web-browser all the way back to the blockchain.

Composer integrates well with a modern development best practices and tools: Atom and VSCode editors, GitHub and GitHub Enterprise for source management, npm and npm enterprise for managing versioned binary artifacts, Travis CI and Jenkins for continuous integration, deployment using Docker images or as npm packages; so that developers and operations engineers can easily move applications from a development laptop to a managed cloud environment.

Editing a Composer model in VSCode

Composer strives to embrace the tools and development processes that you know and already use. You can run unit tests over your blockchain business logic using Mocha for example.

Composer also introduces higher-level abstractions over the blockchain that make it radically simpler to map from business requirements to a running implementation.

The Business Network Definition is a deployable unit that can deployed to a runtime, it defines the structure and relationships between:

• Participants: the members of a business network
• Assets: the goods or services stored on the ledger in registries
• Transactions: the business transactions that update the state of assets, create assets or destroy assets
• Access Control List: is used to declaratively specify under what circumstances a participant can access an asset

Composer enforces a clean separation between the distinct layers of a blockchain application:

• the data model for the assets, participants and transactions (the data stored on the ledger)
• the access control rules for the data on the ledger
• how certificates (identity) is mapped to the participants in the business network
• the APIs used by application developers to access the business network, either to query the ledger or to submit transactions

Defining a Business Network

The unit of development and operational management for Composer is the Business Network Definition. Let’s take a look at how a developer creates a new Business Network Definition.

Modeling the Business Domain

A Business Network Definition contains a set of composer models, which defines the structure (schema) of the entities and the relationships between them. Models may be packaged within a business network definition, or may be referenced from an npm repository, for sharing across different business network definitions. For example, a regulator may publish a Composer model to npm that defines the data they would like to see on the ledger for audit purposes.

Composer introduces a domain specific model definition language. The syntax of the language makes it easy to quickly model the entities that compose a business network.

Let’s look at an example business network composed of a set of financial institutions that would like to use a distributed ledger to share reference data about corporate bonds.

Assets, Concepts, Enumerations, Participants and Transactions

Asset definitions specify the structure of the business entities whose state are tracked on the distributed ledger. The financial institutions in our example business network would like to share the reference data for corporate bonds. A technical/business analyst therefore defines a BondAsset type, instances of which will be stored on the distributed ledger. asset is a keyword of the modeling language and identifies that BondAsset is a type of asset.

asset BondAsset identified by ISINCode {
o String ISINCode
o Bond bond
}

Assets must have an identifying field, in this case the analyst has determined that the ISIN code for the corporate bond should be used to identity the BondAsset.

Note that a BondAsset has-a Bond (containment), which is defined as a concept in the modeling language. Concepts are complex types, or classes, and they allow a technical analyst define reusable model elements.

concept Bond {
o String[] instrumentId
o String description optional
o String currency optional
o String[] exchangeId
o String clearanceSystem optional
o String definition optional
o String seniority optional
o CouponType couponType optional
o Double couponRate optional
o DateTime maturity
o Double parValue
o Double faceAmount
o PaymentFrequency paymentFrequency
o String dayCountFraction
--> Issuer issuer
}

The Bond concept references the CouponType, which is defined as an enumerated type:

enum CouponType {
o FIXED
o FLOATING
}

The Composer Modeling Language has other features useful when defining business object models: derived types, relationships between types, optional fields, fields with default values, validators for fields.

The Bond concept has a relationship (–>) to an Issuer for the bond. Issuer is modeled as a participant in the business network:

participant Member identified by memberId {
o String memberId
o String name
}

participant Issuer extends Member {
}

Issuer specialises (sub-classes) Member, which represents a person or company that is a member of the business network, but that does not issue securities.

The state of assets and participants in the business network is modified by the processing of business transactions. The structure of transactions are themselves modeled:

transaction PublishBond identified by transactionId {
o String transactionId
o String ISINCode
o Bond bond
}

For this simple reference data sharing use case there is a single type of transaction that published information about a new Bond to the ledger.

Writing Business Logic

Once the domain model for the business network is in place a developer can start to implement the business logic using standard ES5 Javascript functions.

A Javascript function subscribes to a type of transaction using an annotation and the Composer runtime will invoke the function when transactions of the required type are submitted for processing.

/**
* Publish a new bond
* @param {org.acme.bond.PublishBond} publishBond - the publishBond transaction
* @transaction
*/
function publish(publishBond) {

return getAssetRegistry('org.acme.bond.BondAsset')
.then(function (registry) {
var factory = getFactory();
// Create the bond asset.
var bondAsset = factory.newResource('org.acme.bond', 'BondAsset', publishBond.ISINCode);
bondAsset.bond = publishBond.bond;
// Add the bond asset to the registry.
return registry.add(bondAsset);
});
}

The function above has the @transaction annotation to indicate that it would like to be called by the runtime to process a transaction. The standard @param JSDoc annotation is used to indicate the type of the transaction that the function processes.

The body of the Javascript function uses a runtime API that allows the code to create, update, destroy assets and participants and to store them in registries, which are persisted onto the blockchain.

Access Control

Within a business network we have different types of participants, and even different instances of participant. To prevent access control logic polluting the core business logic it can (optionally) be externalised into a set of Access Control Rules, which are evaluated by the Composer runtime and used to determine whether a participant submitting a transaction has permission to perform an operation (CREATE, READ, UPDATE, DELETE) on a resource type or resource instance.

The two ACL rules below specify that a member of the business network can READ BondAsset instances, but only the issuer of a BondAsset can perform CREATE, UPDATE and DELETE operations on an instance.

/**
* Access Control List for the bond data
*/
Issuer | org.acme.bond.BondAsset:a | ALL | org.acme.bond.Issuer:i | (a.bond.issuer.memberId === i.memberId) | ALLOW | Allow full access to the issuer of a bond
Default | org.acme.bond | READ | org.acme.bond | (true) | ALLOW | Allow read access

Composer Playground

Developers, business and technical analysts can use the Composer Playground web application to interactively define and test business networks. This zero-install web based environment allows the domain model to be specified, ACL rules and transaction processor functions to be written, and then to deploy the network to either a simulated ledger or to a full Hyperledger Fabric distributed ledger. Once deployed the user can interactively create assets, participants, submit transactions and inspect the state of the ledger.

Building an Application

Once the model, transaction processor functions and access control logic for a business network definition is in place and has been debugged it is time to build a user interface to interact with the business network.

Node.js

Developers creating Node.js applications can simply use the Composer composer-client and composer-admin npm modules to programmatically query the ledger, submit transactions or perform management operations on the business network definition itself; deploy and undeploy for example.

To bootstrap a skeleton project structure developers can use a Composer generator for the popular Yeoman code generator framework.

Web

Developers building a modern web application to interact with a business network use stongly-typed, domain specific, REST APIs that are automatically generated from the business network definition. Composer uses the Open Source Loopback framework to expose GET/POST/PUT/DELETE verbs for the assets that have been modeled in the business network.

REST API generated from a Composer Business Network Definition

Web developers use their existing REST API integration tools and skills to build rich and engaging front-end applications, and do not need specialised blockchain or Composer skills, instead simply consuming REST APIs described using Swagger (Open API) specifications.

To bootstrap a skeleton Angular project structure (including the generation of Typescript domain classes from the business network definition) developers can use a Composer generator for the popular Yeoman code generator framework.

Mobile

Mobile developers can also exploit the strongly-typed, automatically generated REST API for the business network to create amazing mobile experiences that interact with the distributed ledger. They can also generate APIs from the Swagger specification of the REST API for Android or Swift mobile application development.

Enterprise Integration

The Composer Loopback connector can be used outside of the context of a REST application, driving the Loopback connector from a variety of integration products. For example, using IBM Integration Bus an integration developer can build a declarative integration flow that receives enterprise messages from existing batch, mainframe or message queue-based systems, and submits them to the business network for processing.

Deploying and Operating the Network

Composer can deploy a business network definition to any existing Hyperledger Fabric v0.6 instance, with support for Hyperledger Fabric v1.0 under development. This includes:

• Fabric running using Docker Compose on a developer’s laptop
• Fabric running on shared VMs managed by an IaaS platform, such as IBM Cloud (Softlayer), AWS EC2, or Microsoft Azure
• Fabric running as a managed service on IBM Bluemix
• Fabric running as a high security managed service on IBM HSBN

Composer applications deploy as “standard” Hyperleger Fabric chaincode, so any utilities, tools or management consoles that support Hyperledger Fabric will work with Fabric Composer.

Summary

If you are a CIO, you are probably already thinking about how distributed ledger technology will disrupt your industry; the threats, as well as the opportunities. Composer allows you to test your ideas quickly and with low risk, while working in an Open Source eco-system that facilitates collaboration and minimises vendor lock-in. Please use the IBM Blockchain Garages to engage with Composer experts.

If you are an IT architect, struggling to start a blockchain POC, or worried about the complexity of supporting the technology in your environment, please give Composer a try. I’m confident that in a week you’ll have a demo up and running that you can show your executives and project sponsors. Use the Loopback connector to connect existing enterprise systems to the blockchain.

If you are a business analyst, the Composer Modeling Language allows you to focus on your core expertise, defining the domain models, and with the help of a JS developer you can specify the business logic for a complex business scenario backed by a distributed ledger.

If you are a web or mobile developer you get to use REST APIs and the tools you are familiar with, and don’t have to become a blockchain or cryptography expert to create a compelling user experience.

If you are a specialist in DevOps be reassured that the Composer team understands the importance of continuous integration and robust testing, staging and promotion processes. Create unit and system tests for business network definitions just as you would for your other code. Use DevOps best practices to reduce time to market, reduce risk and catch bugs earlier in the product development cycle.

If you work in Operations, know that you can manage and deploy Fabric Composer in a wide variety of environments, giving you maximum flexibility; from bare metal running in your data centre, to a fully-managed offering running on state of the art IBM LinuxOne systems in the IBM Cloud.

References

• Get Started with IBM Blockchain
• Fabric Composer Homepage
• Hyperldger Fabric Homepage