github.com/kaituanwang/hyperledger@v2.0.1+incompatible/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  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  Fabcar uses the "first-network" sample as its limited development network. It
    27  consists of four peer nodes configured to use CouchDB as the state database,
    28  a single "solo" ordering node, a certificate authority (CA) and a CLI container
    29  for executing commands.
    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  
    37  * creates a channel and joins the peer to the channel
    38  * installs the ``fabcar`` smart contract onto the peer's file system and instantiates it on the channel (instantiate starts a container)
    39  * calls the ``initLedger`` function to populate the channel ledger with 10 unique cars
    40  
    41  These operations would typically be done by an organizational or peer admin.
    42  The script uses the CLI to execute these commands, however there is support in
    43  the SDK as well. Refer to the `Hyperledger Fabric Node SDK repo
    44  <https://github.com/hyperledger/fabric-sdk-node>`__ for example scripts.
    45  
    46  How an Application Interacts with the Network
    47  ---------------------------------------------
    48  
    49  Applications use **APIs** to invoke smart contracts. These smart contracts are
    50  hosted in the network and identified by name and version. For example, our
    51  chaincode container is titled - ``dev-peer0.org1.example.com-fabcar-1.0`` -
    52  where the name is ``fabcar``, the version is ``1.0``, and the peer it is running
    53  against is ``dev-peer0.org1.example.com``.
    54  
    55  APIs are accessible with an SDK. For purposes of this exercise, we're using the
    56  `Hyperledger Fabric Node SDK <https://hyperledger.github.io/fabric-sdk-node/>`__ though
    57  there is also a Java SDK and CLI that can be used to drive transactions.
    58  SDKs encapsulate all access to the ledger by allowing an application to
    59  communicate with smart contracts, run queries, or receive ledger updates. These APIs use
    60  several different network addresses and are run with a set of input parameters.
    61  
    62  Smart contracts are installed by a peer administrator and then instantiated on a
    63  channel by an identity fulfilling the chaincode's instantiation policy, which by
    64  default is comprised of channel administrators.  The instantiation of
    65  the smart contract follows the same transaction flow as a normal invocation - endorse,
    66  order, validate, commit - and is a prerequisite to interacting with a chaincode
    67  container. The script that launched our simplified Fabcar test network took care
    68  of the installation and instantiation for us.
    69  
    70  Query
    71  ^^^^^
    72  
    73  Queries are the simplest kind of invocation: a call and response.  The most common query
    74  will interrogate the state database for the current value associated
    75  with a key (``GetState``).  However, the `chaincode shim interface <https://godoc.org/github.com/hyperledger/fabric-chaincode-go/shim#ChaincodeStubInterface>`__
    76  also allows for different types of ``Get`` calls (e.g. ``GetHistoryForKey`` or ``GetCreator``).
    77  
    78  In our example, the peer holds a hash chain of all transactions and maintains
    79  chaincode state through use of a state database, which in our case is a CouchDB container.  CouchDB
    80  provides the added functionality of rich queries, contingent upon the chaincode data (key/val pairs)
    81  being modeled as JSON.  When we call the ``GetState`` API in our smart contract, we
    82  are retrieving the JSON value associated with a car from the CouchDB state database.
    83  
    84  Queries are constructed by identifying a peer, a chaincode, a channel and a set of
    85  inputs (e.g. the key) for an available chaincode function and then utilizing the
    86  ``chain.queryByChaincode`` API to send the query to the peer.  The corresponding
    87  value to the supplied inputs is returned to the application client as a response.
    88  
    89  Updates
    90  ^^^^^^^
    91  
    92  Ledger updates start with an application generating a transaction proposal. As with
    93  query, a request is constructed to identify a peer, chaincode, channel, function, and
    94  set of inputs for the transaction. The program then calls the
    95  ``channel.SendTransactionProposal`` API to send the transaction proposal to the
    96  peer(s) for endorsement.
    97  
    98  The network (i.e. the endorsing peer(s)) returns a proposal response, which the
    99  application uses to build and sign a transaction request. This request is sent
   100  to the ordering service by calling the ``channel.sendTransaction`` API. The
   101  ordering service bundles the transaction into a block and delivers it to all
   102  peers on a channel for validation (the Fabcar network has only one peer and one channel).
   103  
   104  Finally the application uses the :doc:`peer_event_services` to register for events
   105  associated with a specific transaction ID so that the application can be notified
   106  about the fate of a transaction (i.e. valid or invalid).
   107  
   108  For More Information
   109  --------------------
   110  
   111  To learn more about how a transaction flow works beyond the scope of an
   112  application, check out :doc:`txflow`.
   113  
   114  To get started developing chaincode, read :doc:`chaincode4ade`.
   115  
   116  For more information on how endorsement policies work, check out
   117  :doc:`endorsement-policies`.
   118  
   119  For a deeper dive into the architecture of Hyperledger Fabric, check out
   120  :doc:`architecture`.
   121  
   122  .. Licensed under Creative Commons Attribution 4.0 International License
   123     https://creativecommons.org/licenses/by/4.0/