From ee188e43e52d6bb6788994d07c2fbb51907a6170 Mon Sep 17 00:00:00 2001 From: David Enyeart Date: Sat, 16 Sep 2017 15:33:48 -0400 Subject: [PATCH] [FAB-6190] Improve docs for query Improvement documentation on query scenarios. Change-Id: I2e5b9b9c184e30331fa28b26efacfea0294cb920 Signed-off-by: David Enyeart --- docs/source/glossary.rst | 50 ++++++++++++++++++++++++++++------------ docs/source/txflow.rst | 20 ++++++++-------- 2 files changed, 45 insertions(+), 25 deletions(-) diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index e76267e6acc..d593b4fb097 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -127,8 +127,10 @@ be added/removed for various reasons. Endorsement ----------- -Refers to the process where specific peer nodes execute a transaction and return -a ``YES/NO`` response to the client application that generated the transaction proposal. +Refers to the process where specific peer nodes execute a chaincode transaction and return +a proposal response to the client application. The proposal response includes the +chaincode execution response message, results (read set and write set), and events, +as well as a signature to serve as proof of the peer's chaincode execution. Chaincode applications have corresponding endorsement policies, in which the endorsing peers are specified. @@ -143,8 +145,9 @@ A policy could require that a transaction be endorsed by a minimum number of endorsing peers, a minimum percentage of endorsing peers, or by all endorsing peers that are assigned to a specific chaincode application. Policies can be curated based on the application and the desired level of resilience against -misbehavior (deliberate or not) by the endorsing peers. A distinct endorsement -policy for install and instantiate transactions is also required. +misbehavior (deliberate or not) by the endorsing peers. A transaction that is submitted +must satisfy the endorsement policy before being marked as valid by committing peers. +A distinct endorsement policy for install and instantiate transactions is also required. .. _Fabric-ca: @@ -190,17 +193,25 @@ The process of placing a chaincode on a peer's file system. Instantiate ----------- -The process of starting a chaincode container. +The process of starting and initializing a chaincode application on a specific channel. +After instantiation, peers that have the chaincode installed can accept chaincode +invocations. .. _Invoke: Invoke ------ -Used to call chaincode functions. Invocations are captured as transaction -proposals, which then pass through a modular flow of endorsement, ordering, -validation, committal. The structure of invoke is a function and an array of -arguments. +Used to call chaincode functions. A client application invokes chaincode by +sending a transaction proposal to a peer. The peer will execute the chaincode +and return an endorsed proposal response to the client application. The client +application will gather enough proposal responses to satisfy an endorsement policy, +and will then submit the transaction results for ordering, validation, and commit. +The client application may choose not to submit the transaction results. For example +if the invoke only queried the ledger, the client application typically would not +submit the read-only transaction, unless there is desire to log the read on the ledger +for audit purpose. The invoke includes a channel identifier, the chaincode function to +invoke, and an array of arguments. .. _Leading-Peer: @@ -279,7 +290,7 @@ read/write operations to the ledger. Peers are owned and maintained by members. Policy ------ -There are policies for endorsement, validation, block committal, chaincode +There are policies for endorsement, validation, chaincode management and network/channel management. .. _Proposal: @@ -295,7 +306,14 @@ proposal is either an instantiate or an invoke (read/write) request. Query ----- -A query requests the value of a key(s) against the current state. +A query is a chaincode invocation which reads the ledger current state but does +not write to the ledger. The chaincode function may query certain keys on the ledger, +or may query for a set of keys on the ledger. Since queries do not change ledger state, +the client application will typically not submit these read-only transactions for ordering, +validation, and commit. Although not typical, the client application can choose to +submit the read-only transaction for ordering, validation, and commit, for example if the +client wants auditable proof on the ledger chain that it had knowledge of specific ledger +state at a certain point in time. .. _SDK: @@ -316,7 +334,7 @@ State Database -------------- Current state data is stored in a state database for efficient reads and queries -from chaincode. These databases include levelDB and couchDB. +from chaincode. Supported databases include levelDB and couchDB. .. _System-Chain: @@ -340,9 +358,11 @@ channels relative to their aligned and varying business agendas. Transaction ----------- -An invoke or instantiate operation. Invokes are requests to read/write data from -the ledger. Instantiate is a request to start a chaincode container on a peer. +Invoke or instantiate results that are submitted for ordering, validation, and commit. +Invokes are requests to read/write data from the ledger. Instantiate is a request to +start and initialize a chaincode on a channel. Application clients gather invoke or +instantiate responses from endorsing peers and package the results and endorsements +into a transaction that is submitted for ordering, validation, and commit. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ - diff --git a/docs/source/txflow.rst b/docs/source/txflow.rst index e1741fc4bce..9704539b5c2 100644 --- a/docs/source/txflow.rst +++ b/docs/source/txflow.rst @@ -54,13 +54,12 @@ arguments to the invoked chaincode's function. The chaincode is then executed against the current state database to produce transaction results including a response value, read set, and write set. No updates are made to the ledger at this point. The set of these values, along with the -endorsing peer’s signature and a YES/NO endorsement statement is passed back as -a “proposal response” to the SDK which parses the payload for the application to -consume. +endorsing peer’s signature is passed back as a “proposal response” to the SDK +which parses the payload for the application to consume. *{The MSP is a peer component that allows them to verify transaction requests arriving from clients and to sign transaction results(endorsements). -The *Writing* policy is defined at channel creation time, and determines +The Writing policy is defined at channel creation time, and determines which user is entitled to submit a transaction to that channel.}* @@ -69,11 +68,13 @@ which user is entitled to submit a transaction to that channel.}* 3. **Proposal responses are inspected** The application verifies the endorsing peer signatures and compares the proposal -responses (link to glossary term which will contain a representation of the payload) -to determine if the proposal responses are the same and if the specified endorsement -policy has been fulfilled (i.e. did peerA and peerB both endorse). The architecture -is such that even if an application chooses not to inspect responses or otherwise -forwards an unendorsed transaction, the policy will still be enforced by peers +responses to determine if the proposal responses are the same. If the chaincode only queried +the ledger, the application would inspect the query response and would typically not +submit the transaction to Ordering Service. If the client application intends to submit the +transaction to Ordering Service to update the ledger, the application determines if the specified +endorsement policy has been fulfilled before submitting (i.e. did peerA and peerB both endorse). +The architecture is such that even if an application chooses not to inspect responses or otherwise +forwards an unendorsed transaction, the endorsement policy will still be enforced by peers and upheld at the commit validation phase. .. image:: images/step4.png @@ -113,4 +114,3 @@ protobuffers. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ -