Commit 8735e589 authored by David Enyeart's avatar David Enyeart Committed by Gerrit Code Review
Browse files

Merge "[FAB-14437] Document no events for Raft" into release-1.4

parents 180c65f0 ffa256ac
......@@ -306,6 +306,11 @@ get the required endorsements. But the application doesn't need to worry about
any of this -- it just issues `submitTransaction` and the SDK takes care of it
all!
Note that the `submitTransaction` API includes a process for listening for
transaction commits. Listening for commits is required because without it,
you will not know whether your transaction has successfully been orderered,
validated, and committed to the ledger.
Let's now turn our attention to how the application handles the response!
## Process response
......
Transaction Flow
================
This document outlines the transactional mechanics that take place during a standard asset
exchange. The scenario includes two clients, A and B, who are buying and selling
radishes. They each have a peer on the network through which they send their
transactions and interact with the ledger.
This document outlines the transactional mechanics that take place during a
standard asset exchange. The scenario includes two clients, A and B, who are
buying and selling radishes. They each have a peer on the network through which
they send their transactions and interact with the ledger.
.. image:: images/step0.png
**Assumptions**
This flow assumes that a channel is set up and running. The application user
has registered and enrolled with the organization’s certificate authority (CA)
and received back necessary cryptographic material, which is used to authenticate
to the network.
This flow assumes that a channel is set up and running. The application user has
registered and enrolled with the organization’s Certificate Authority (CA) and
received back necessary cryptographic material, which is used to authenticate to
the network.
The chaincode (containing a set of key value pairs representing the initial
state of the radish market) is installed on the peers and instantiated on the
channel. The chaincode contains logic defining a set of transaction
instructions and the agreed upon price for a radish. An endorsement policy has
also been set for this chaincode, stating that both ``peerA`` and ``peerB`` must endorse
any transaction.
channel. The chaincode contains logic defining a set of transaction instructions
and the agreed upon price for a radish. An endorsement policy has also been set
for this chaincode, stating that both ``peerA`` and ``peerB`` must endorse any
transaction.
.. image:: images/step1.png
1. **Client A initiates a transaction**
What's happening? - Client A is sending a request to purchase radishes. The
What's happening? Client A is sending a request to purchase radishes. This
request targets ``peerA`` and ``peerB``, who are respectively representative of
Client A and Client B. The endorsement policy states that both peers must endorse
any transaction, therefore the request goes to ``peerA`` and ``peerB``.
Client A and Client B. The endorsement policy states that both peers must
endorse any transaction, therefore the request goes to ``peerA`` and ``peerB``.
Next, the transaction proposal is constructed. An application leveraging a supported
SDK (Node, Java, Python) utilizes one of the available API's which generates a
transaction proposal. The proposal is a request to invoke a chaincode function
so that data can be read and/or written to the ledger (i.e. write new key value
pairs for the assets). The SDK serves as a shim to package the transaction proposal
into the properly architected format (protocol buffer over gRPC) and takes the user’s
cryptographic credentials to produce a unique signature for this transaction proposal.
Next, the transaction proposal is constructed. An application leveraging a
supported SDK (Node, Java, Python) utilizes one of the available API's
to generate a transaction proposal. The proposal is a request to invoke a
chaincode function with certain input parameters, with the intent of reading
and/or updating the ledger.
The SDK serves as a shim to package the transaction proposal into the properly
architected format (protocol buffer over gRPC) and takes the user’s
cryptographic credentials to produce a unique signature for this transaction
proposal.
.. image:: images/step2.png
2. **Endorsing peers verify signature & execute the transaction**
The endorsing peers verify (1) that the transaction proposal is well formed,
(2) it has not been submitted already in the past (replay-attack protection),
(3) the signature is valid (using MSP), and (4) that the
submitter (Client A, in the example) is properly authorized to perform
the proposed operation on that channel (namely, each endorsing peer ensures that
the submitter satisfies the channel's *Writers* policy).
The endorsing peers take the transaction proposal inputs as
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 is passed back as a “proposal response” to the SDK
which parses the payload for the application to consume.
.. note:: The MSP is a peer component that allows peers to verify
transaction requests arriving from clients and to sign transaction
results (endorsements). The writing policy is defined at channel
creation time and determines which users are entitled to submit a
transaction to that channel.
The endorsing peers verify (1) that the transaction proposal is well formed, (2)
it has not been submitted already in the past (replay-attack protection), (3)
the signature is valid (using the MSP), and (4) that the submitter (Client A, in the
example) is properly authorized to perform the proposed operation on that
channel (namely, each endorsing peer ensures that the submitter satisfies the
channel's *Writers* policy). The endorsing peers take the transaction proposal
inputs as 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 (i.e. key/value pairs
representing an asset to create or update). No updates are made to the
ledger at this point. The set of these values, along with the endorsing peer’s
signature is passed back as a “proposal response” to the SDK which parses the
payload for the application to consume.
.. note:: The MSP is a peer component that allows peers to verify transaction
requests arriving from clients and to sign transaction results
(endorsements). The writing policy is defined at channel creation time
and determines which users are entitled to submit a transaction to
that channel. For more information about membership, check out our
:doc:`membership/membership` documentation.
.. image:: images/step3.png
3. **Proposal responses are inspected**
The application verifies the endorsing peer signatures and compares the proposal
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.
responses to determine if the proposal responses are the same. If the chaincode
is only queried the ledger, the application would inspect the query response and
would typically not submit the transaction to the ordering service. If the client
application intends to submit the transaction to the 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
4. **Client assembles endorsements into a transaction**
The application “broadcasts” the transaction proposal and response within a
“transaction message” to the Ordering Service. The transaction will contain the
read/write sets, the endorsing peers signatures and the Channel ID. The
Ordering Service does not need to inspect the entire content of a transaction in order to perform
its operation, it simply receives
transactions from all channels in the network, orders them chronologically by
channel, and creates blocks of transactions per channel.
“transaction message” to the ordering service. The transaction will contain the
read/write sets, the endorsing peers signatures and the Channel ID. The
ordering service does not need to inspect the entire content of a transaction in
order to perform its operation, it simply receives transactions from all
channels in the network, orders them chronologically by channel, and creates
blocks of transactions per channel.
.. image:: images/step5.png
......@@ -103,14 +109,21 @@ Transactions in the block are tagged as being valid or invalid.
6. **Ledger updated**
Each peer appends the block to the channel’s chain, and for each valid transaction
the write sets are committed to current state database. An event is emitted, to
notify the client application that the transaction (invocation) has been
immutably appended to the chain, as well as notification of whether the
Each peer appends the block to the channel’s chain, and for each valid
transaction the write sets are committed to current state database. An event is
emitted, to notify the client application that the transaction (invocation) has
been immutably appended to the chain, as well as notification of whether the
transaction was validated or invalidated.
**Note**: See the :ref:`sequence diagram <swimlane>` to better understand the
.. note:: Applications should listen for the transaction event after submitting
a transaction, for example by using the ``submitTransaction``
API, which automatically listen for transaction events. Without
listening for transaction events, you will not know
whether your transaction has actually been ordered, validated, and
committed to the ledger.
See the :ref:`sequence diagram <swimlane>` to better understand the
transaction flow.
.. Licensed under Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/
https://creativecommons.org/licenses/by/4.0/
......@@ -275,7 +275,7 @@ identity ``user1`` from ``wallet``. See how the ``ccp`` has been loaded from
If you'd like to understand more about the structure of a connection profile,
and how it defines the network, check out
`the connection profile topic <./developapps/connectionprofile.html>`_.
`the connection profile topic <./developapps/connectionprofile.html>`_.
A network can be divided into multiple channels, and the next important line of
code connects the application to a particular channel within the network,
......@@ -468,6 +468,13 @@ transactions. It then distributes these blocks to every peer in the network,
where every transaction is validated and committed. Finally, the SDK is
notified, allowing it to return control to the application.
.. note:: ``submitTransaction`` also includes a listener that checks to make
sure the transaction has been validated and committed to the ledger.
Applications should either utilize a commit listener, or
leverage an API like ``submitTransaction`` that does this for you.
Without doing this, your transaction may not have been successfully
orderered, validated, and committed to the ledger.
``submitTransaction`` does all this for the application! The process by which
the application, smart contract, peers and ordering service work together to
keep the ledger consistent across the network is called consensus, and it is
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment