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/