125 lines
6.0 KiB
ReStructuredText
125 lines
6.0 KiB
ReStructuredText
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.
|
||
|
||
.. 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.
|
||
|
||
The chaincode (containing a set of key value pairs representing the initial
|
||
state of the radish market) is installed on the peers and deployed to 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.
|
||
|
||
.. image:: images/step1.png
|
||
|
||
1. **Client A initiates a transaction**
|
||
|
||
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``.
|
||
|
||
Next, the transaction proposal is constructed. An application leveraging a
|
||
supported SDK (Node, Java, Go) 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. The SDK submits the transaction proposal to a target peer,
|
||
which will manage the transaction submission on behalf of the client.
|
||
The target peer first forwards the transaction proposal to other peers
|
||
for execution, as required by the endorsement policy.
|
||
|
||
.. 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 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 target peer.
|
||
|
||
.. 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 target peer verifies the proposal responses are the same prior to proceeding with the transaction submission.
|
||
The architecture is such that even if a transaction is submitted without this check,
|
||
the endorsement policy will still be checked and enforced when each peer validates transactions prior to committing them.
|
||
|
||
.. image:: images/step4.png
|
||
|
||
4. **Target peer assembles endorsements into a transaction**
|
||
|
||
The target peer “broadcasts” the transaction proposal and response within a
|
||
“transaction message” to the ordering service. The transaction contains the
|
||
Channel ID, the read/write sets, and a signature from each endorsing peer.
|
||
The ordering service does not need to inspect the entire content of a transaction in
|
||
order to perform its operation, it simply receives transactions, orders them, and creates
|
||
blocks of transactions per channel.
|
||
|
||
.. image:: images/step5.png
|
||
|
||
5. **Transaction is validated and committed**
|
||
|
||
The blocks of transactions are “delivered” to all peers on the channel. The
|
||
transactions within the block are validated to ensure endorsement policy is
|
||
fulfilled and to ensure that there have been no changes to ledger state for read
|
||
set variables since the read set was generated by the transaction execution.
|
||
Transactions in the block are tagged as being valid or invalid.
|
||
|
||
.. image:: images/step6.png
|
||
|
||
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 by each peer 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:: 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.
|
||
|
||
You can also use the swimlane sequence diagram below to examine the
|
||
transaction flow in more detail.
|
||
|
||
.. image:: images/flow-4.png
|
||
|
||
.. Licensed under Creative Commons Attribution 4.0 International License
|
||
https://creativecommons.org/licenses/by/4.0/
|