github.com/kchristidis/fabric@v1.0.4-0.20171028114726-837acd08cde1/docs/source/understand_fabcar_network.rst (about) 1 Understanding the Fabcar Network 2 ================================ 3 4 Fabcar was designed to leverage a network stripped down to only the components 5 necessary to run an application. And even with that level of simplification, 6 the ``./startFabric.sh`` script takes care of the installation and 7 configuration not baked into the network itself. 8 9 Obscuring the underpinnings of the network to that degree is fine for the 10 majority of application developers. They don't necessarily need to know how 11 network components actually work in detail in order to create their app. 12 13 But for those who do want to know about the fun stuff going on under the covers 14 (so to speak), let's go through how applications **connect** to the network and 15 how they propose **queries** and **updates** on a more granular level, as well 16 as point out the differences between a small scale test network like Fabcar and 17 how apps will usually end up working in the real world. 18 19 We'll also point you to where you can get detailed information about how Fabric 20 networks are created and how a transaction flow works beyond the scope of the 21 role an application plays. 22 23 Components of the Fabcar Network 24 -------------------------------- 25 26 The Fabcar network consists of one peer node, one ordering node (aka, the 27 "orderer"), a couchDB container, and a CLI container. This represents a 28 very limited network, without a certificate authority or any other 29 peers. 30 31 For detailed information on these components and what they do, refer to 32 :doc:`build_network`. 33 34 These components are bootstrapped by the ``./startFabric.sh`` script, which 35 also: 36 * creates a channel and joins the peer to the channel 37 * installs smart contract onto the peer's file system and instantiates it on the channel (instantiate starts a container) 38 * calls the ``initLedger`` function to populate the channel ledger with 10 unique cars 39 40 These operations would typically be done by an organizational or peer admin. 41 The script uses the CLI to execute these commands, however there is support in 42 the SDK as well. Refer to the `Hyperledger Fabric Node SDK repo 43 <https://github.com/hyperledger/fabric-sdk-node>`__ for example scripts. 44 45 How an Application Interacts with the Network 46 --------------------------------------------- 47 48 Applications use **APIs** to invoke smart contracts. These smart contracts are 49 hosted in the network and identified by name and version. For example, our 50 chaincode container is titled - ``dev-peer0.org1.example.com-fabcar-1.0`` - 51 where the name is ``fabcar``, the version is ``1.0``, and the peer it is running 52 against is ``dev-peer0.org1.example.com``. 53 54 APIs are accessible with an SDK. For purposes of this exercise, we're using the 55 `Hyperledger Fabric Node SDK <https://fabric-sdk-node.github.io/>`__ though 56 there is also a Java SDK and CLI that can be used to develop applications. 57 SDKs encapsulate all access to the ledger by allowing an application to 58 use smart contracts, run queries, or receive ledger updates. These APIs use 59 several different network addresses and are run with a set of input parameters. 60 61 Smart contracts are installed and instantiated on a channel through the 62 consensus process. The script that launched our simplified Fabcar test network 63 bypassed this process by installing and instantiating the smart contracts for 64 us on the lone peer in our network. 65 66 One crucial aspect of networks missing from Fabcar is the roll a certificate 67 authority (CA) plays issuing the certificates that allow users to query, 68 transact, and govern a network. This simplification was made because Fabcar is 69 really meant to show how applications connect to the network and issue queries 70 and updates rather than highlighting the enrollment and governance process. 71 72 In future iterations of Fabcar we'll go more into how enrollment works and how 73 different kinds of certificates are issued. 74 75 Query 76 ^^^^^ 77 78 Queries are the simplest kind of invocation: a call and response. Applications 79 can query different ledgers at the same time. Those results are returned to 80 the application **synchronously**. This does not necessarily ensure that each 81 ledger will return exactly the same information (a peer can go down, for 82 example, and miss updates). Given that our sample Fabcar network has only one 83 peer, that's not really an issue here, but it's an important consideration 84 when developing applications in a real world scenario. 85 86 The peers hold the hash chain (the record of updates), while the updates 87 themselves are stored in a separate couchDB container (which allows for the 88 storage of rich queries, written in JSON). 89 90 Queries are built using a **var request** -- identifying the correct ledger, the 91 smart contracts it will use, the search parameters etc -- and then invoking the 92 ``chain.queryByChaincode`` API to send the query. An API called 93 ``response_payload`` returns the result to the application. 94 95 Updates 96 ^^^^^^^ 97 98 Ledger updates start with an application generating a transaction proposal. A 99 request is constructed to identify the channel ID, function, and specific smart 100 contract to target for the transaction. The program then calls the 101 ``channel.SendTransactionProposal`` API to send the transaction proposal to the 102 peer(s) for endorsement. 103 104 The network (i.e., the endorsing peer) returns a proposal response, which the 105 application uses to build and sign a transaction request. This request is sent 106 to the ordering service by calling the ``channel.sendTransaction`` API. The 107 ordering service bundles the transaction into a block and delivers it to all 108 peers on a channel for validation (the Fabcar network has only one endorsing 109 peer and one channel). 110 111 Finally the application uses two event handler APIs: ``eh.setPeerAddr`` to 112 connect to the peer's event listener port and ``eh.registerTxEvent`` to 113 register events associated with a specific transaction ID. The 114 ``eh.registerTxEvent`` API registers a callback for the transactionID that 115 checks whether ledger was updated or not. 116 117 For More Information 118 -------------------- 119 120 To learn more about how a transaction flow works beyond the scope of an 121 application, check out :doc:`txflow`. 122 123 To get started developing chaincode, read :doc:'chaincode4ade'. 124 125 For more information on how endorsement policies work, check out 126 :doc:`endorsement-policies`. 127 128 For a deeper dive into the architecture of Hyperledger Fabric, check out 129 :doc:`arch-deep-dive`. 130 131 .. Licensed under Creative Commons Attribution 4.0 International License 132 https://creativecommons.org/licenses/by/4.0/