github.com/darrenli6/fabric-sdk-example@v0.0.0-20220109053535-94b13b56df8c/docs/source/ledger.rst (about)

     1  Ledger
     2  ======
     3  
     4  The ledger is the sequenced, tamper-resistant record of all state transitions.  State
     5  transitions are a result of chaincode invocations ('transactions') submitted by participating
     6  parties.  Each transaction results in a set of asset key-value pairs that are committed to the
     7  ledger as creates, updates, or deletes.
     8  
     9  The ledger is comprised of a blockchain ('chain') to store the immutable, sequenced record in
    10  blocks, as well as a state database to maintain current state.  There is one ledger per
    11  channel. Each peer maintains a copy of the ledger for each channel of which they are a member.
    12  
    13  Chain
    14  -----
    15  
    16  The chain is a transaction log, structured as hash-linked blocks, where each block contains a
    17  sequence of N transactions. The block header includes a hash of the block's transactions, as
    18  well as a hash of the prior block's header. In this way, all transactions on the ledger are
    19  sequenced and cryptographically linked together. In other words, it is not possible to tamper with
    20  the ledger data, without breaking the hash links. The hash of the latest block represents every
    21  transaction that has come before, making it possible to ensure that all peers are in a consistent
    22  and trusted state.
    23  
    24  The chain is stored on the peer file system (either local or attached storage), efficiently
    25  supporting the append-only nature of the blockchain workload.
    26  
    27  State Database
    28  --------------
    29  
    30  The ledger's current state data represents the latest values for all keys ever included in the chain
    31  transaction log. Since current state represents all latest key values known to the channel, it is
    32  sometimes referred to as World State.
    33  
    34  Chaincode invocations execute transactions against the current state data. To make these
    35  chaincode interactions extremely efficient, the latest values of all keys are stored in a state
    36  database. The state database is simply an indexed view into the chain's transaction log, it can
    37  therefore be regenerated from the chain at any time.  The state database will automatically get
    38  recovered (or generated if needed) upon peer startup, before transactions are accepted.
    39  
    40  Transaction Flow
    41  ----------------
    42  
    43  At a high level, the transaction flow consists of a transaction proposal sent by an application
    44  client to specific endorsing peers.  The endorsing peers verify the client signature, and execute
    45  a chaincode function to simulate the transaction.  The output is the chaincode results,
    46  a set of key/value versions that were read in the chaincode (read set), and the set of keys/values
    47  that were written in chaincode (write set).  The proposal response gets sent back to the client
    48  along with an endorsement signature.
    49  
    50  The client assembles the endorsements into a transaction payload and broadcasts it to an ordering
    51  service.  The ordering service delivers ordered transactions as blocks to all peers on a channel.
    52  
    53  Before committal, peers will validate the transactions.  First, they will check the endorsement
    54  policy to ensure that the correct allotment of the specified peers have signed the results, and they
    55  will authenticate the signatures against the transaction payload.
    56  
    57  Secondly, peers will perform a versioning check against the transaction read set, to ensure
    58  data integrity and protect against threats such as double-spending.
    59  Hyperledger Fabric has concurrency control whereby transactions execute in parallel (by endorsers)
    60  to increase throughput, and upon commit (by all peers) each transaction is verified to ensure
    61  that no other transaction has modified data it has read. In other words, it ensures that the data
    62  that was read during chaincode execution has not changed since execution (endorsement) time,
    63  and therefore the execution results are still valid and can be committed to the ledger state
    64  database. If the data that was read has been changed by another transaction, then the
    65  transaction in the block is marked as invalid and is not applied to the ledger state database.
    66  The client application is alerted, and can handle the error or retry as appropriate.
    67  
    68  See the :doc:`txflow` and :doc:`readwrite` topics for a deeper dive on transaction structure,
    69  concurrency control, and the state DB.
    70  
    71  State Database options
    72  ----------------------
    73  
    74  State database options include LevelDB and CouchDB. LevelDB is the default key/value state
    75  database embedded in the peer process. CouchDB is an optional alternative external state database.
    76  Like the LevelDB key/value store, CouchDB can store any binary data that is modeled in chaincode
    77  (CouchDB attachment functionality is used internally for non-JSON binary data). But as a JSON
    78  document store, CouchDB additionally enables rich query against the chaincode data, when chaincode
    79  values (e.g. assets) are modeled as JSON data.
    80  
    81  Both LevelDB and CouchDB support core chaincode operations such as getting and setting a key
    82  (asset), and querying based on keys. Keys can be queried by range, and composite keys can be
    83  modeled to enable equivalence queries against multiple parameters. For example a composite
    84  key of (owner,asset_id) can be used to query all assets owned by a certain entity. These key-based
    85  queries can be used for read-only queries against the ledger, as well as in transactions that
    86  update the ledger.
    87  
    88  If you model assets as JSON and use CouchDB, you can also perform complex rich queries against the
    89  chaincode data values, using the CouchDB JSON query language within chaincode. These types of
    90  queries are excellent for understanding what is on the ledger. Proposal responses for these types
    91  of queries are typically useful to the client application, but are not typically submitted as
    92  transactions to the ordering service. In fact, there is no guarantee the result set is stable
    93  between chaincode execution and commit time for rich queries, and therefore rich queries
    94  are not appropriate for use in update transactions, unless your application can guarantee the
    95  result set is stable between chaincode execution time and commit time, or can handle potential
    96  changes in subsequent transactions.  For example, if you perform a rich query for all assets
    97  owned by Alice and transfer them to Bob, a new asset may be assigned to Alice by another
    98  transaction between chaincode execution time and commit time, and you would miss this 'phantom'
    99  item.
   100  
   101  CouchDB runs as a separate database process alongside the peer, therefore there are additional
   102  considerations in terms of setup, management, and operations. You may consider starting with the
   103  default embedded LevelDB, and move to CouchDB if you require the additional complex rich queries.
   104  It is a good practice to model chaincode asset data as JSON, so that you have the option to perform
   105  complex rich queries if needed in the future.
   106  
   107  CouchDB Configuration
   108  ----------------------
   109  
   110  CouchDB is enabled as the state database by changing the stateDatabase configuration option from
   111  goleveldb to CouchDB.   Additionally, the ``couchDBAddress`` needs to configured to point to the
   112  CouchDB to be used by the peer.  The username and password properties should be populated with
   113  an admin username and password if CouchDB is configured with a username and password.  Additional
   114  options are provided in the ``couchDBConfig`` section and are documented in place.  Changes to the
   115  *core.yaml* will be effective immediately after restarting the peer.
   116  
   117  You can also pass in docker environment variables to override core.yaml values, for example
   118  ``CORE_LEDGER_STATE_STATEDATABASE`` and ``CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS``.
   119  
   120  Below is the ``stateDatabase`` section from *core.yaml*:
   121  
   122  .. code:: bash
   123  
   124      state:
   125        # stateDatabase - options are "goleveldb", "CouchDB"
   126        # goleveldb - default state database stored in goleveldb.
   127        # CouchDB - store state database in CouchDB
   128        stateDatabase: goleveldb
   129        couchDBConfig:
   130           # It is recommended to run CouchDB on the same server as the peer, and
   131           # not map the CouchDB container port to a server port in docker-compose.
   132           # Otherwise proper security must be provided on the connection between
   133           # CouchDB client (on the peer) and server.
   134           couchDBAddress: couchdb:5984
   135           # This username must have read and write authority on CouchDB
   136           username:
   137           # The password is recommended to pass as an environment variable
   138           # during start up (e.g. LEDGER_COUCHDBCONFIG_PASSWORD).
   139           # If it is stored here, the file must be access control protected
   140           # to prevent unintended users from discovering the password.
   141           password:
   142           # Number of retries for CouchDB errors
   143           maxRetries: 3
   144           # Number of retries for CouchDB errors during peer startup
   145           maxRetriesOnStartup: 10
   146           # CouchDB request timeout (unit: duration, e.g. 20s)
   147           requestTimeout: 35s
   148           # Limit on the number of records to return per query
   149           queryLimit: 10000
   150  
   151  
   152  CouchDB hosted in docker containers supplied with Hyperledger Fabric have the
   153  capability of setting the CouchDB username and password with environment
   154  variables passed in with the ``COUCHDB_USER`` and ``COUCHDB_PASSWORD`` environment
   155  variables using Docker Compose scripting.
   156  
   157  For CouchDB installations outside of the docker images supplied with Fabric, the
   158  *local.ini* file must be edited to set the admin username and password.
   159  
   160  Docker compose scripts only set the username and password at the creation of
   161  the container.  The *local.ini* file must be edited if the username or password
   162  is to be changed after creation of the container.
   163  
   164  .. note:: CouchDB peer options are read on each peer startup.
   165  
   166  .. Licensed under Creative Commons Attribution 4.0 International License
   167     https://creativecommons.org/licenses/by/4.0/