Slides presented at the Hyperledger Fabric Workshop in Barcelona on July 10th, 2019. This covers the development of a Fabric application and smart contract (i.e. chaincode), with some tips on good practices and the IBM Blockchain Platform extension for VS Code.

1. Hyperledger Fabric
Developing blockchain applications
V1.01, 13 June 2019
Arnaud J Le Hors
Senior Technical Staff Member Web & Blockchain Open Technologies
Member of the Hyperledger Project Technical Steering Committee

2. Application Development
• [ Key Concepts ]
• Example Walkthrough
• VS Code Extension
• Good practices
• Summary

3. 3
Blockchain concepts
• Concepts to consider for blockchain solutions:
• The business problem we’re trying to solve
• The participants involved (users and organizations)
• The assets
• The transactions, underpinned by contracts
• The goal is to move these topics into to a machine
readable form and eventual deployment to a blockchain
system

4. 4
Example: Commercial Paper
123 Fake Street,
New York, New York
28th February 2019
I promise to pay to the
order of the bearer the sum
of $1,000,000 on or after
28th February 2020.
MagnetoCorp
Matt Lucas
On behalf of MagnetoCorp
Matt Lucas
• Commercial paper is a means of providing short
term financing to companies
• Trust requirement and well-defined business
network make a good fit for blockchain
Business Problem?
Participants?
• MagnetoCorp (Issuing organization)
• Matt Lucas (MagnetoCorp employee)
• “the bearer” (could be many of these)
Assets?
• The Commercial Paper (!)
• $1,000,000
Transactions?
• Issue Buy RedeemID:
0000475923

5. 5
Commercial Paper: Transaction Lifecycle
Matt
Lucas
MagnetoCorp
issue
(omitting cash flows)
bearer1
bearer2
bearer3
BearerN
redeem
buy
buy
buy

6. 6
Commercial Paper: Cash Lifecycle
Matt
Lucas
MagnetoCorp
issue
bearer1
bearer2
bearer3
BearerN
redeem
buy buy
buy
$975,000
$950,000
$925,000
$900,000
$1,000,000

7. 7
Example: Commercial Paper
• Commercial paper is a means of providing short
term financing to companies
• Trust requirement and well-defined business
network makes a good fit for blockchain
Business Problem?
Participants?
• Magnetocorp (Issuing organization)
• Matt Lucas (Magnetocorp employee)
• “the bearer” (could be many of these)
Assets?
• The Commercial Paper
• $1,000,000
Transactions?
• Issue Buy Redeem
Q: How do we get
from these business
concepts to something
that can run on a
blockchain?
A: We will model them

8. 8
Smart contract programming
• Contract class
– Built-in Fabric class
• One method per transaction
– Code each transaction as method
• Transaction context
– Pass helpful information between
invocations
• before(), after() & unknown() handlers
– Common transaction logic programmed
here
• Installed on all endorsing organizations’ peers
– Instantiated on channel for applications.
(Think: implementation on peer,
interface on channel)
CommercialPaperContext extends Context {
constructor() {
this.paperList = new PaperList(this);
}
}
CommercialPaperContract extends Contract {
createContext() {
new CommercialPaperContext();
}
issue(ctx, issuer, paperNumber, ...) {
ctx.paperList.addPaper(...);
ctx.stub.putState(...);
}
buy(ctx, issuer, paperNumber, ...) {}
redeem(ctx, issuer, paperNumber, ...) {}
}
ctx
ctx
ctx
ctx
1
2
3
4
5

9. 9
Application programming with the SDK
• The application focuses on the
WHAT not the HOW:
1. Select identity from wallet
2. Connect to gateway
3. Access network channel
4. Select smart contract
5. Submit transaction
6. Process response
• SDK hides all details of consensus
Select identity from wallet
Connect to network gateway
Access PaperNet channel
Get PaperContact smart
contract
Submit issue transaction
Process issue notification
PaperContract
{
issue() {...}
buy() {...}
redeem() {...}
}
SDKApplication Smart contract
– Applications simply submit transactions to update ledger and are notified when complete
(either synchronously or asynchronously)

10. © 2018 IBM Corporation
10
Example client application – JavaScript
• MagnetoCorp issues a commercial paper, face value $1M, redemption date 2019-10-31
const gateway = new Gateway();
const wallet = new FileSystemWallet('./WALLETS/wallet');
try {
await gateway.connect(ccp, {
identity: 'admin',
wallet: wallet
});
const network = await gateway.getNetwork('market1234');
const contract = await network.getContract('commercial-paper');
// issue commercial paper
const issueResponse = await contract.submitTransaction('issue’, ‘MagnetoCorp', '1000000', '2019-
10-31’);
let paper = CommercialPaper.fromBuffer(issueResponse);
} catch(error) {
console.log(error);
} finally {
gateway.disconnect();
}

11. 11
Understanding an application gateway
§Network topology constantly changing
– Peers, Orderers, CAs, smart contracts, ledgers
§Gateways isolate business logic from topology
– connectionProfile identifies components & roles
– connectionOptions specifies desired outcome
§Service Discovery
– CCP bootstrap -> discovery network dynamically!
Gateway
“buy”
application
Connection
profile
Orderer
1
MagnetoCorp
Orderer
2
DigiBank
channel: papernet
MagnetoCorp DigiBank
Peer2
MagnetoCorp
Peer7
DigiBank
Isabella
Peer1
MagnetoCorp
Peer3
MagnetoCorp
const connectionProfile = yaml.safeLoad('../gateway/paperNet.yaml');
const connectionOptions = {..., commitTimeout: 100,... };
const gateway = new Gateway();
await gateway.connect(connectionProfile, connectionOptions);

12. 12
Understanding wallets
• Wallets store a identities available to a user
– Typically X.509 certificates and private keys
– Application can use multiple wallets & identities ...
• Applications connect to gateway with identity
– Identified in gateway connectionOptions
PaperNet
ID1: MagnetoCorp.member
ID4: DigiBank.member
MSP
BondNet
ID1: MagnetoCorp.member
ID2: DigiBank.admin
MSP
MagnetoCorp
Isabella
CA1
Wallet1
ID1
ID2
ID3
DigiBank
CA2
Wallet2
ID4
App1 App2
Balaji
const user1 = 'paperUser1@MagnetoCorp.com';
const wallet = new FileSystemWallet('../identity/user/isabella/wallet');
const connectionOptions = {
identity: userName,
wallet: wallet,
eventHandlerOptions: {
commitTimeout: 100,
strategy: EventStrategies.MSPID_SCOPE_ANYFORTX
}
};
await gateway.connect(connectionProfile, connectionOptions);

13. 13
Connecting to a network channel and smart contract
• Gateway gives access to multiple networks
– gateway.getNetwork('papernet')
• All instantiated smart contracts accessible
– network.getContract('papercontract')
• Construct transaction proposal & submit it!
– contract.submitTranaction('sell',
'paper05')
– Multiple gateways/channels/contracts at
once!
const network1 = await gateway.getNetwork('PaperNet');
const network2 = await gateway.getNetwork('BondNet');
const euroContract = await network1.getContract('EuroCommercialPaperContract');
const bondContract = await network2.getContract('BondContract');
const issueResponse = await euroContract.submitTransaction('issue', 'MagnetoCorp'...);
const issueResponse = await bondContract.submitTransaction('sell', 'BOND007'...)
MagnetoCorp DigiBank
issuer
App channel: papernet
Peer9
DigiBank
paper
contract
ledger
Peer1
MagnetoCorp
paper
contract
ledger
Orderer
1
MagnetoCorp
Orderer
2
DigiBank
Ordering service
Peer3
MagnetoCorp
ledger
Peer8
DigiBank
ledger
Peer2
MagnetoCorp
ledger
Peer7
DigiBank
ledger

14. 14
Interacting with smart contracts and the ledger
• submitTransaction()
– Adds a fully signed new transaction to the ledger
– SDK manages entire multi-peer, ordering process
– Returns control when E/O/V complete (default)
• evaluateTransaction()
– Executes a transaction, but doesn't order it
– Typically used to query the ledger
– Only needs to interact with one peer
(pluggable handlers can be used for multi-peer query)
MagnetoCorp DigiBank
user
App channel: bond
Peer9
DigiBank
bonds
contract
ledger
Peer1
MagnetoCorp
bonds
contract
ledger
Orderer
1
MagnetoCorp
Orderer
2
DigiBank
Ordering service
Peer3
MagnetoCorp
ledger
Peer8
DigiBank
ledger
Peer2
MagnetoCorp
ledger
Peer7
DigiBank
ledgerbonds.submitTransaction('sell',
'BOND007');
bonds.evaluateTransaction('queryBond',
'BOND007');
1a 1b
1c1d
1e 1f
1
1
2
2a
2

15. 15
Ledger notification interactions
• Three listener types:
– contract.addContractListener()
• wait for all transactions of given contract
– contract.addBlockListener()
• wait for blocks
– transaction.addTransactionListener()
• wait for specific transaction to be committed
const transaction = contract.createTransaction('sell');
transaction.addCommitListener(`${transactionId}-listener`, (err, txId, status, blockHeight) => {
...
if (status === ‘VALID’) {
console.info(‘Transaction committed’);
} else {
...
}, {checkpointer: false});
await transaction.submit('ibm', '1000000', '2019-03-31’);
MagnetoCorp DigiBank
issuer
App channel: papernet
Peer9
DigiBank
paper
contract
ledger
Peer1
MagnetoCorp
paper
contract
ledger
Orderer
1
MagnetoCorp
Orderer
2
DigiBank
Ordering service
Peer3
MagnetoCorp
ledger
Peer8
DigiBank
ledger
Peer2
MagnetoCorp
ledger
Peer7
DigiBank
ledger
1b
1a
1c
APIs under development in
FABN-1100, slated 2.0

16. 16
Customizing behavior with
connectionOptions
• connectionOptions specifies gateway behaviour
– wallet: & identity: must be set by app
– All other options have sensible defaults
• Strategies codify most popular behaviour
– e.g. "wait for any/all peers in my organization"
• EventStrategies.MSPID_SCOPE_ANYFORTX
• EventStrategies.MSPID_SCOPE_ALLFORTX
• Handlers for programmable interactions
– User function gets control at appropriate point in transaction lifecycle with relevant topology, i.e.
peers
• e.g. startListening(), waitForEvents(), cancelListening()...
– Keeps separate from application business logic. Advanced feature; only required for special
scenarios
Gateway
“transfer”
application
Connection
options
Peer6
DigiBank
channel: papernet
MagnetoCorp DigiBank
Peer2
MagnetoCorp
Peer7
DigiBank
Isabella
Peer1
MagnetoCorp
Peer3
MagnetoCorp
ledger ledger ledger
ledger ledger

17. Application Development
• Key Concepts
• [ Example Walkthrough ]
• VS Code Extension
• Good practices
• Summary

18. 18
Hyperledger Fabric Commercial Paper Sample
• https://hyperledger-fabric.readthedocs.io/en/release-1.4/tutorial/commercial_paper.html
• Download samples
• Create network
• Explore smart contract
• Install smart contract
• Instantiate smart contract
• Enroll Admin
• Register user
• Execute query
• Execute invoke
• Execute query

19. Application Development
• Key Concepts
• Example Walkthrough
• [ VS Code Extension ]
• Good practices
• Summary

20. 20
IBM Blockchain Visual Studio Code Extension
• VS Code Extension for developers
– Mac, Linux & Windows
• Smart contract & application
– Code, package, deploy, test,
debug
• Any Hyperledger Fabric deployment
– Close integration with IBP
• Works with local and remote networks
• Start for free, S&S from IBM
– Download from Marketplace
• Try out FabCar & Commercial Paper samples
• Local network and IBM Blockchain Platform!

21. Application Development
• Key Concepts
• Example Walkthrough
• VS Code Extension
• [ Good practices ]
• Summary

22. 22
Good practices
• Performance
• Integration with external systems
• GDPR

23. What are the Hyperledger Fabric performance levers?
A
B
0 1 2 3
Peer
Ledger
Blockchain WorldState
!Events
Chaincode
Channels
Local
MSP
1
4
3
2
1
3
4
• Indexing
• Size of payload
World State
Orderers / Channels (configtx.yaml)
• "absolute_max_bytes"
• "max_message_count"
• "timeout"
• World state queries
• Query aggregation (e.g. Sum)
• Business logic complexity
• Query to external sources (oracles)
Chaincode
2 • VSCC Transaction validation
• Peer’s resources
Committing peers
• ESCC Transaction signing
• Peer’s resources
Endorsing peers

24. What are the Client Application performance levers?
! Events
ChannelsClient
Application
SDK
(HFC)
Local
MSP
1
• GRPCs Connections reuse
• Endorsement load balancing
• Don’t always hit the same peer
• Complex Endorsement policies
• More endorsers = more invocations
• Channel Event Hubs impact
• How many events should you wait for?
• More peers an organization has on a
channel means more events to listen to
3
2
3
2
• Network latency
• To the orderer
• To the peers of every orgs
1 Fabric components
Fabric SDK / Client Application
Channels

25. 1. Make sure you reuse your connections
2. Ensure your connection profile is
properly configured
3. Load balance endorsement requests
across multiple peers
4. Sample code is not a guarantee of
scalability
5. If starting a new project, leverage the
new HL Fabric v1.4 programming
model!
Optimizing the client application
Latency per tx when not
reusing client connections
1
Enabling the peers that need to endorse2

26. 1. Understanding the effect of:
(configtx.yaml)
– Preferred Max Bytes
Represents the threshold at which a block will be
cut
– Block size
– Timeout
2. The peer and it’s dual personality
– Commit versus endorsement
– State validation is the most expensive operations
• Driven primarily by payload size and frequency
3. Increasing the number of endorsing
peers helps throughput
Transactions and the Orderer
Block commit State commit State validation

27. 1. Test your queries against separate
CouchDB first
Use _explain to and execution_stats to confirm
index is used
2. Avoid $or or $regexp in selectors
It ignores the index and forces CouchDB to
perform a full scan
3. Use pagination to improve performance
Pagination is supported since Hyperledger
Fabric v1.3
Considerations for queries

28. 28
Integrating with Existing Systems – Possibilities
Transform
Existing
systems
1. System
events
2. Blockchain
events
4. Call out to existing systems
3. Call into blockchain network
from existing systems
Blockchain network Existing
systems
!
!

29. 29
Non-determinism in blockchain
• Blockchain is a distributed processing system
– Smart contracts are run multiple times and in
multiple places
– Smart contracts need to run deterministically in
order for consensus to work
• Particularly when updating the world state
• It’s particularly difficult to achieve determinism with
off-chain processing
– Implement oracle services that are guaranteed to
be consistent for a given transaction, or
– Detect duplicates for a transaction in the
blockchain, middleware or external system
getDateTime()
getExchangeRate()
getTemperature()
random()
incrementValue
inExternalSystem(…)

30. 30
Block Fields and Personal Data
Potential areas where Personal Data could be included in the block:
• Proposal payload : These are the transaction input arguments.
• Client certificate: If the client certificate is individual to a Data Subject then it could be
considered PD.
• Key: The key written to or read from the world state. If PD is used in the key name then it will be
included here.
• Value: The value of any keys written to the world state. If PD is used in the key value then it will
be included here.
• Events: Events emitted from chaincode could include PD.
• Chaincode response: Any response from invoking the chaincode could include PD.
It is assumed that endorser and orderer certificates are issued to an organization and do not
include Personal Data.
Remember that Fabric configuration blocks also contain certificates!

31. 31
Solution – Store data off-chain
Config
Block
0
Config
Block
1
Transaction
Block
2
Transaction
Block
3
Genesis
Worldstate
Blockchain
Data Store
Salted hash
stored on-chain
matches hash in
data store
• What
– Store Personal Data (PD) in an off-chain mutable data storage
• How
– Store only proofs as a salted hash of the PD on-chain
– The salt must be stored securely, and should be unique for each PD
– The salted hash can be stored in an off-chain data store and linked to the PD
– Salt and salted hash can be in different data stores to the PD
– Warning: Hashes and salted hashes are considered pseudonymous data and
still fall under the scope of GDPR.
• Why
– PD, salted hash and salt can be deleted at any point from the data store(s)
causing the hash on-chain to be anonymized
Personal Data
Salt
salted hash
salted hash
salted hash

32. Application Development
• Key Concepts
• Example Walkthrough
• VS Code Extension
• Good practices
• [ Summary ]

33. 33
Summary
• The Hyperledger Fabric transaction
– Structure drives system design and application architecture
• Smart contract
– Contains transaction definitions for entire lifecycle of business
object(s) stored in a decentralized ledger
– built-in contract class makes programming easy
• Application
– Consensus is complex, but the SDK makes it easy for
applications
– submitTransaction(), evaluateTransaction(), addListener()
– gateway connectionOptions for ultimate customizability
• The IBM Blockchain VS Code Extension difference
– Supports development and debugging on local network as well as
multi-cloud IBM Blockchain Platform

34. Thank you
Arnaud J Le Hors
lehors@us.ibm.com
@lehors
www.ibm.com/blockchain
developer.ibm.com/blockchain
www.hyperledger.org
© Copyright IBM Corporation 2019. 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.