Ibp technical introduction
- 1. IBM Blockchain Platform: Technical Introduction Building and running blockchain applications using IBM Blockchain Platform V1.01, 20 May 2019 IBM Blockchain Platform Technical Series Architectural Good Practices Modeling Blockchain Applications What’s New in Technology Under the Covers Technical Introduction
- 2. Key Concepts Understand the concepts behind Hyperledger Fabric Developer tools Using IBM Blockchain Platform to implement blockchain applications Administrator tools A demo of how to use IBM Blockchain Platform to simplify operations
- 3. 3 Blockchain concepts • Consider the business concepts that comprise blockchain solutions: – Assets modeled as data structures – Contracts modeled as algorithms – Transactions modeled as invocations of algorithms – Business Networks modeled as peer-to-peer networks – Participants modeled as nodes on these networks • IBM Blockchain Platform is based around Hyperledger Fabric • We will now look at how Hyperledger Fabric exposes these business concepts to the blockchain developer • We will also look at the IBM Blockchain Platform tools that help developers implement these concepts in a solution
- 4. 4 Transaction Endorsement • Hyperledger Fabric is built on the idea of selective transaction endorsement – It’s a key differentiator from public blockchain networks (e.g. the bitcoin mining network collectively “endorses” all transactions) • Each transaction is subject to a set of rules that govern who must sign off on it (“endorsement policy”) • In order to be valid, transactions must be endorsed according to its endorsement policy • Endorsement policies are typically agreed as part of the design of the transaction’s implementation (smart contract) ORG1 ORG2 ORG1 must sign ORG2 must sign “Transfer CAR1 from ORG1 to ORG2” CAR1
- 5. 5 Endorsed transactions in the blockchain ledger # Transaction Initiator Receiver Asset Invoked TX Invoked by Endorsed by 1 Transfer ORG1 ORG2 CAR1 transfer(CAR1, ORG2) ORG1 ORG1, ORG2 2 Transfer ORG2 ORG3 CAR1 transfer(CAR1, ORG3) ORG2 ORG2, ORG3 3 Issue VDA ORG3 CAR2 issue(CAR2, ORG3) VDA VDA, ORG3 4 Scrap ORG3 CAR1 scrap(CAR1) ORG3 ORG3, VDA 5 Update rules VDA updatePolicy(…) VDA VDA, ORG1, ORG2, ORG3 ORG1 ORG2 ORG3 VDA
- 6. 6 Understanding a Hyperledger Fabric transaction car transfer transaction: identifier: 1234567890 proposal: input: {CAR1, ORG1, ORG2} signature: input*ORG1 response: output: {CAR1.owner=ORG1, CAR1.owner=ORG2} signatures: output signed by ORG1 output signed by ORG2 A transaction to transfer CAR1 from ORG1 to ORG2 • Transaction structure: – Name & ID: obvious! – Proposal: The transaction inputs, also obvious! • Signed by transaction initiator – Response: The transaction results • before and after states • Signed by all approvers: less obvious! • Valid transactions – Signed by multiple organizations! – This is what makes blockchain based on Hyperledger Fabric powerful!
- 7. 7 A smart contract generates a transaction response • Define controlled access to ledger – c.f. database stored procedures • Uses transaction proposal (input) from application – Generates a signed transaction response (output) – Uses world state to simplify processing • Contract executed by multiple organizations – Recall: Valid transactions signed by ALL endorsing ORGS – e.g. car transfers must be signed by ORG1 && ORG2 – Endorsement policy defines endorsing organizations car contract: query(car): get(car); return car; transfer(car, buyer, seller): get(car); car.owner = buyer; put(car); return car; update(car, properties): get(car); car.colour = properties.colour; put(car); return car; Car endorsement policy: ORG1 AND ORG2
- 8. 8 The ledger: an immutable history of transactions • Most important data structure – A network can have more than one logical ledger • Blockchain: history of all transactions – Sequence of valid & invalid transactions, grouped in blocks – Hashed and linked using cryptography – e.g. history of car ownership since manufacture • World State: current value of all states – The result of applying all valid transactions, in order – Simplifies applications because that’s what most frequently required – e.g. current details of all cars (owners, colour, registration...) Ledger components: blockchain & world state t1 t2 t3 CAR1:{owner:ORG2} CAR2:{owner:ORG2} t4 t5 t6 ✓ X Blockchain World state b1 b2 ledger
- 9. 9 The importance of organization and identity • All entities have an identity – Users, applications, network nodes... everything! – Typically based on X.509 certificates, private keys – CN=Anthony/OU=Dev/O=IBM • Identity determines rights over resources – Read/write ledger, submit transactions... – In fact, entire system is governed using policy • Flexible identity architecture – N logical organizations in 1 physical organization – X.509 typical, but pluggable – Hierarchies: root CA, intermediate, OUs, roles, CRLs etc... Organization Certificate Authority Identity CA1 CA2 O1 P u P u O2 P u P u O3 P u
- 10. 10 A blockchain network: Decentralized and multi-organizational • A consortium of multiple organizations – Collaboration for shared data and shared processes – Mutually agreed policies define “constitution” • A ledger is physically replicated – Each organization hosts multiple copies of a ledger • Ledger copies synchronized via consensus – Execute, Order, Validate protocol (more later) • Key application policy: Endorsement policy – Which organizations must sign valid transactions DIST MFR 2 Blockchain Network MFR 1 Insurer DMV Dealer ledger ledger ledger ledger ledger ledger MFR = Manufacturer DIST = Distributor
- 11. 11 Key components of a network topology (1/2) • Peer – Hosts a copy of a ledger – Endorsing peers host smart contract – A channel links applications & peers • Ordering Service – Creates blocks of sequenced txns – Distributes blocks to peers – Transactions are validated by peers • Certificate Authority – Issues identities (X.509) to ALL entities in all organizations (users/applications, peers, orderers...) – Private keys must be kept securely by owning entity seller buyer “transfer” application channel: drivenet Orderer 1 ManCorp Peer3 ManCorp Orderer 2 DealerCorp Peer8 DealerCorp Peer9 DealerCorp Peer7 DealerCorp Peer1 ManCorp Peer2 ManCorp car contract car contract CA1 ManCorp Ordering service “query” application CA2 DealerCorp ledger ledger ManCorp DealerCorp ledger ledger ledger ledger
- 12. 12 Key components of a network topology (2/2) • Transaction • User • Application • Peers • Smart contract • Ledger • Channel • Ordering Service • Certificate Authority seller buyer “transfer” application channel: drivenet Orderer 1 ManCorp Peer3 ManCorp Orderer 2 DealerCorp Peer8 DealerCorp Peer9 DealerCorp Peer7 DealerCorp Peer1 ManCorp Peer2 ManCorp car contract car contract CA1 ManCorp Ordering service “query” application CA2 DealerCorp ledger ledger ManCorp DealerCorp ledger ledger ledger ledger . Increasing cardinality t
- 13. 13 The transaction lifecycle: Execute-Order-Validate • Execute – App sends signed proposal to endorsing peers – Each contract generates a signed response • Order – App assembles fully signed transaction. Orders. – Ordering service creates sequenced txn blocks – Distributes to peers, who independently process • Validate – Signature check: according to endorsement policy – Response check: Verify transaction response generated in execution phase is still valid – Notify application that transaction committed (valid/invalid) ManCorp DealerCorp seller “transfer” application channel: papernet Peer9 DealerCorp car contract ledger Peer1 ManCorp car contract ledger Orderer 1 ManCorp Orderer 2 DealerCorp Ordering service Peer3 ManCorp ledger Peer8 DealerCorp ledger Peer2 ManCorp ledger Peer7 DealerCorp ledger
- 14. 14 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
- 15. 15 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 DriveNet channel Get CarContact smart contract Submit transfer transaction Process transfer notification CarContract { query() {...} transfer() {...} update() {...} scrap() {...} } SDKApplication Smart contract – Applications simply submit transactions to update ledger and are notified when complete (either synchronously or asynchronously)
- 16. © 2018 IBM Corporation 16 Example client application – JavaScript • IBM issues a commercial paper, face value $1M, redemption date 2019-10-31 • IBM sells paper to ACME Inc. for $900,000 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 paper = await contract.submitTransaction('issue', 'ibm', '1000000', '2019-10-31'); // sell paper to buyer 'acme' for $900,000 await contract.submitTransaction('move', paper, 'acme', '900000'); } catch(error) { console.log(error); } finally { gateway.disconnect(); }
- 17. © 2018 IBM Corporation 17 Example client application – Java // Create a new file system based wallet for managing identities. Path walletPath = Paths.get("wallet"); Wallet wallet = Wallet.createFileSystemWallet(walletPath); // load a CCP Path networkConfigPath = Paths.get("..", "..", "paper-network", "connection.json"); // create a gateway, then connect Gateway.Builder builder = Gateway.createBuilder(); builder.identity(wallet, "admin").networkConfig(networkConfigPath); try (Gateway gateway = builder.connect()) { // get the network and contract Network network = gateway.getNetwork("market1234"); Contract contract = network.getContract("commercial-paper"); // issue commercial paper String paper = contract.submitTransaction("issue", "ibm", "1000000", "2019-10-31") // then sell paper to acme for $900,000 contract.submitTransaction("move", paper, "acme", "900000")) } catch (Exception ex) { ex.printStackTrace(); } • IBM issues a commercial paper, face value $1M, redemption date 2019-10-31 • IBM sells paper to ACME Inc. for $900,000
- 18. 18 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 “transfer” application Connection profile Orderer 1 ManCorp Orderer 2 DealerCorp channel: drivenet ManCorp DealerCorp Peer2 ManCorp Peer7 DealerCorp Isabella Peer1 ManCorp Peer3 ManCorp const connectionProfile = yaml.safeLoad('../gateway/driveNet.yaml'); const connectionOptions = {..., commitTimeout: 100,... }; const gateway = new Gateway(); await gateway.connect(connectionProfile, connectionOptions);
- 19. 19 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: ManCorp.member ID4: DealerCorp.member MSP BondNet ID1: ManCorp.member ID2: ManCorp.admin MSP ManCorp Isabella CA1 Wallet1 ID1 ID2 ID3 DealerCorp CA2 Wallet2 ID4 App1 App2 Balaji const user1 = 'paperUser1@mancorp.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);
- 20. 20 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
- 21. 21 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
- 22. 22 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
- 23. 23 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 DealerCorp channel: drivenet ManCorp DealerCorp Peer2 ManCorp Peer7 DealerCorp Isabella Peer1 ManCorp Peer3 ManCorp ledger ledger ledger ledger ledger
- 24. Key Concepts Understand the concepts behind Hyperledger Fabric Developer tools Using IBM Blockchain Platform to implement blockchain applications Administrator tools A demo of how to use IBM Blockchain Platform to simplify operations