Hyperledger Fabric application development

Unit 06

IBM Skills Academy

V1.0, July 2018

Learning objectives

Chaincode basics

Chaincode
structure, APIs,
and data modeling

Chaincode in action

Summary
What you should be able to do

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

• Describe the chaincode lifecycle and deployment approaches.

• Identify the typical chaincode structure.
• Use Go and Node.js to develop a chaincode.
• Explain how to develop a transaction to create, update, or delete an asset.
• Explain how to query the world state ledger.
• Explain how to query the chain.

3
Learning objectives

Chaincode basics

Chaincode
structure, APIs,
and data modeling

Chaincode in action

Summary
User and system chaincodes

Hyperledger Fabric distinguishes between two types of chaincodes:

SCC User
SCC chaincode A

• System chaincodes (SCC) implement the system’s behavior: SCC

SCC User chaincode
o They run within the peer process. B
o They are bound with the peer’s startup.
Ledger
• User chaincodes implement the smart contract logic: Peer
o They run in isolated containers.
o They depend on the peer, but they can be bootstrapped after the peer’s startup.

Every chaincode program must implement the chaincode interface, which defines the methods that are run during the
chaincode’s lifecycle:
o The Init() method is called in response to an instantiate or upgrade transaction.
o The Invoke() method is called in response to an invoke transaction proposal.

5
Bootstrap chaincode (1/2): Install the chaincode

E0 E2
A
B O O A
B

O O
E1 Ordering service P3
A
B

Hyperledger Fabric Network

At first, chaincode is installed onto the peers that must run it.

6
Bootstrap chaincode (2/2): Instantiate the chaincode

E0 E2
A
B O O A
B

O O
E1 Ordering Service P3
A
B

Hyperledger Fabric Network

Peers instantiate the chaincode on the channels on which they want to transact.

7
Chaincode deployment approaches

CLI-based SDK-based API-based

Pros: Easy to use Pros: Places an Pros: Easy to use
(through peer commands). abstraction layer between (through Hyperledger
the application and the Composer or other
Cons: blockchain. platform, for example, IBM
o Impacts security due to Blockchain Platform APIs).
direct interaction with Cons: In more complex
peers to perform scenarios, it introduces Cons: Less flexibility and
actions. another debugging layer to control over the chaincode
o May not be possible in be managed. compilation process.
real-life production
scenarios.

8
Learning objectives

Chaincode basics

Chaincode
structure, APIs,
and data modeling

Chaincode in action

Summary
Developing the client and chaincode

Client SDK Chaincode

Fully
supported Go Go

Experimental
/ under
development

10
Chaincode structure

4. Implementation
3. CC interface GetState

Invoke() PutState

Init() GetFunctionAndParameters

2. shim.Start()

1. Import declarations
Chaincode APIs: Developing Go

• To develop chaincode in Go, you must import the shim package by running the following command:
import "github.com/hyperledger/fabric/core/chaincode/shim»

• Chaincodes must implement the following methods in the chaincode interface:

o Init(stub ChaincodeStubInterface) pb.Response
The Init() method is called during a chaincode instantiation or upgrade to perform any necessary
initialization of the application state.
o Invoke(stub ChaincodeStubInterface) pb.Response
The Invoke() method is called by Invoke() transaction (proposals) or Query() requests.

• The ChaincodeStubInterface object:

o Is passed as parameter to both Init() and Invoke().
o Can be used to discover information on the request (invoking an identity, target channel, or
arguments) and talk with the peer to retrieve or update the application state.

12
Chaincode APIs: Developing

• To develop chaincode in Node.js, you must import the fabric-shim module by running the following command:
const shim = require('fabric-shim’);

• Chaincodes must implement the following methods in the ChaincodeInterface:

o <async> Init(stub)
The Init() method is called during a chaincode instantiation or upgrade to perform any necessary
initialization of the application state.
o <async> Invoke(stub)
The Invoke() method is called by Invoke() transaction (proposals) or Query() requests.

• The ChaincodeStub object:

o Is passed as parameter to both Init() and Invoke().
o Can be used to discover information about the request (invoking an identity, target channel, or arguments)
and talk with the peer to retrieve or update the application state.

13
Chaincode implementation: Handling input and context

• All transactions are processed through the Invoke() or Init() methods:

o The client may specify a function name as an argument of the invocation (typically the 1°).
o The shim provides the interface methods to handle transaction input:
GetArgs(), GetStringArgs(), GetFunctionAndParameters(), and so on

• Transactions are processed within a transaction context:

o Who invoked the transaction, when, and on which channel.
o The shim provides interface methods to handle transaction context:
GetTxID(), GetCreator(), GetTxTimestamp(), GetChannelID(), SetEvent(), and so on

14
Chaincode implementation: Handling data

• The shim provides interface methods to interact with the data layer:
o getState(), putState(), delState(), getHistoryForKey(), GetQueryResult(), and so on.
o By default, the world state is stored in a key value store and uses a byte array as the
value.
o Data models eventually must be converted into a JSON string.
• Native JSON structure and rich query support depend on the state database.
• CouchDB:
CouchDB
o Requires indexes to:
 Make JSON queries efficient.
 Perform JSON queries with a sort.
Chaincode Peer
o Indexes must be defined and deployed.
SHIM

LevelDB

15
Handling the chain: Query System Chaincode

Query System Chaincode (QSCC) provides convenient APIs to retrieve information about the blockchain by providing the
following inquiry methods:

• GetChainInfo, which retrieves blockchain Height, currentBlockHash, and previousBlockHash

• GetBlockByNumber and GetBlockByHash
• GetTransactionByID

Block 15 Block 16 Block 17

…
Block Hash: 57ec2fda71 Block Hash: 87ea2ffe94 Block Hash: 44bf2efe32

Previous Block Hash: Previous Block Hash: Previous Block Hash: …

d68b2f0a3b 57ec2fda71 87ea2ffe94

Transaction Transaction Transaction

Transaction Transaction

Transaction

16
Client SDK and chaincode operations
Peer process

Query chain QSCC

Chaincode Docker container

Query ledger
GetState
Invoke() Invoke()
PutState
Upgrade() Init()
…
Instantiate()

Client shim.Start()
Import
Learning objectives

Chaincode basics

Chaincode
structure, APIs,
and data modeling

Chaincode in action

Summary
Implementing Invoke()
Modify the ledger
state.
Arg(0)
key JSON
Invoke() Arg(x) string
Putstate
Value

Encoding/JSON

Import Type struct{}

Implementing Invoke(): Example (asset creation and update)
Modify the ledger
state.
Args
AssetID(123) JSON
CreateAsset() Putstate
AssetName(“A string
sset”)
UpdateAsset()

AssetName = string

Encoding/JSON AssetID = integer

Import Type struct{}

Implementing Query()
Query() ledger
GetState
state
Arg(0) JSON
Query() Arg(x) string
GetStateByRange

GetStateByPartialCompositeKey

getQueryResult

Encoding/JSON

Import Type struct{}

 Implementing Query(): Level DB or CouchDB

Key/Rich
Query
GetState
JSON
Query() string CouchDB
GetStateByRange

GetStateByPartialCompositeKey
LevelDB
Key getQueryResult

Encoding/JSON

Import Type struct{}

Learning objectives

Chaincode basics

Chaincode
structure, APIs,
and data modeling

Chaincode in action

Summary
Unit summary
This unit described chaincode basics for development, including:

• User and system chaincode lifecycle.

• Client and chaincode supported languages for development.

• Typical chaincode structure and shim APIs.

• Data modeling and handling rich queries.

• Interacting with QSCC to query the chain.

24
Exercise objectives

During this exercise, you will apply Hyperledger Fabric chaincode development concepts to:

• Start the sample.

• Review the Go chaincode.
• Add/change the logic.
• Install/instantiate the chaincode.
• Review changes.
• Do the same for the Node.js chaincode.

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

• http://hyperledger-fabric.readthedocs.io/en/release-1.1

• https://developer.ibm.com/courses/all/ibm-blockchain-foundation-developer/

26
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.
 © Copyright IBM Corporation 2018. 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.