github.com/muhammedhassanm/blockchain@v0.0.0-20200120143007-697261defd4d/sawtooth-core-master/docs/source/architecture/transactions_and_batches.rst (about)

     1  ************************
     2  Transactions and Batches
     3  ************************
     4  
     5  Modifications to state are performed by creating and applying transactions.  A
     6  client creates a transaction and submits it to the validator.  The validator
     7  applies the transaction which causes a change to state.
     8  
     9  Transactions are always wrapped inside of a batch.  All transactions within a
    10  batch are committed to state together or not at all.  Thus, batches are the
    11  atomic unit of state change.
    12  
    13  The overall structure of batches and transactions includes Batch, BatchHeader,
    14  Transaction, and TransactionHeader:
    15  
    16  .. image:: ../images/arch_batch_and_transaction.*
    17     :width: 80%
    18     :align: center
    19     :alt: Transaction and batch entity diagram
    20  
    21  Transaction Data Structure
    22  ==========================
    23  
    24  Transactions are serialized using Protocol Buffers.  They consists of two
    25  message types:
    26  
    27  .. literalinclude:: ../../../protos/transaction.proto
    28     :language: protobuf
    29     :caption: File: protos/transaction.proto
    30     :linenos:
    31  
    32  Header, Signature, and Public Keys
    33  ----------------------------------
    34  
    35  The Transaction header field is a serialized version of a TransactionHeader.
    36  The header is signed by the signer's private key (not sent with the
    37  transaction) and the resulting signature is stored in header_signature.  The
    38  header is present in the serialized form so that the exact bytes can be
    39  verified against the signature upon receipt of the Transaction.
    40  
    41  The verification process verifies that the key in signer_public_key signed the
    42  header bytes resulting in header_signature.
    43  
    44  The batcher_public_key field must match the public key used to sign the batch in
    45  which this transaction is contained.
    46  
    47  The resulting serialized document is signed with the transactor's private
    48  ECDSA key using the secp256k1 curve.
    49  
    50  The validator expects a 64 byte "compact" signature. This is a concatenation
    51  of the R and S fields of the signature. Some libraries will include an
    52  additional header byte, recovery ID field, or provide DER encoded signatures.
    53  Sawtooth will reject the signature if it is anything other than 64 bytes.
    54  
    55  .. note::
    56  
    57     The original header bytes as constructed from the sender are used
    58     for verification of the signature.  It is not considered good practice to
    59     de-serialize the header (for example, to a Python object) and then
    60     re-serialize the header with the intent to produce the same byte sequence as
    61     the original.  Serialization can be sensitive to programming language or
    62     library, and any deviation would produce a sequence that would not match the
    63     signature; thus, best practice is to always use the original header bytes for
    64     verification.
    65  
    66  Transaction Family
    67  ------------------
    68  
    69  In Hyperledger Sawtooth, the set of possible transactions are defined by an
    70  extensible system called transaction families.  Defining and implementing a new
    71  transaction family adds to the taxonomy of available transactions which can be
    72  applied. For example, in the language-specific tutorials that show you how to
    73  write your own transaction family (see the :doc:`/app_developers_guide`), we
    74  define a transaction family called "xo" which defines a set of transactions for
    75  playing tic-tac-toe.
    76  
    77  In addition to the name of the transaction family (family_name), each
    78  transaction specifies a family version string (family_version).  The version
    79  string enables upgrading a transaction family while coordinating the nodes
    80  in the network to upgrade.
    81  
    82  Dependencies and Input/Output Addresses
    83  ---------------------------------------
    84  
    85  Transactions can depend upon other transactions, which is to say a dependent
    86  transaction cannot be applied prior to the transaction upon which it depends.
    87  
    88  The dependencies field of a transaction allows explicitly specifying the
    89  transactions which must be applied prior to the current transaction.  Explicit
    90  dependencies are useful in situations where transactions have dependencies but
    91  can not be placed in the same batch (for example, if the transactions are
    92  submitted at different times).
    93  
    94  To assist in parallel scheduling operations, the inputs and outputs fields of a
    95  transaction contain state addresses.  The scheduler determines the implicit
    96  dependencies between transactions based on interaction with state.  The
    97  addresses may be fully qualified leaf-node addresses or partial prefix
    98  addresses.  Input addresses are read from the state and output addresses are
    99  written to state.  While they are specified by the client, input and output
   100  declarations on the transaction are enforced during transaction execution.
   101  Partial addresses work as wildcards and allow transactions to specify parts of
   102  the tree instead of just leaf nodes.
   103  
   104  Payload
   105  -------
   106  
   107  The payload is used during transaction execution as a way to convey the change
   108  which should be applied to state.  Only the transaction family processing the
   109  transaction will deserialize the payload; to all other components of the
   110  system, payload is just a sequence of bytes.
   111  
   112  The payload_sha512 field contains a SHA-512 hash of the payload bytes.  As part
   113  of the header, payload_sha512 is signed and later verified, while the payload
   114  field is not.  To verify the payload field matches the header, a SHA-512 of the
   115  payload field can be compared to payload_sha512.
   116  
   117  Nonce
   118  -----
   119  
   120  The nonce field contains a random string generated by the client.  With the
   121  nonce present, if two transactions otherwise contain the same fields, the nonce
   122  ensures they will generate different header signatures.
   123  
   124  Batch Data Structure
   125  ====================
   126  
   127  Batches are also serialized using Protocol Buffers.  They consist of two
   128  message types:
   129  
   130  .. literalinclude:: ../../../protos/batch.proto
   131     :language: protobuf
   132     :caption: File: protos/batch.proto
   133     :linenos:
   134  
   135  Header, Signature, and Public Keys
   136  ----------------------------------
   137  
   138  Following the pattern presented in Transaction, the Batch header field is a
   139  serialized version of a BatchHeader.  The header is signed by the signer's
   140  private key (not sent with the batch) and the resulting signature is stored in
   141  header_signature.  The header is present in the serialized form so that the
   142  exact bytes can be verified against the signature upon receipt of the Batch.
   143  
   144  The resulting serialized document is signed with the transactor's private
   145  ECDSA key using the secp256k1 curve.
   146  
   147  The validator expects a 64 byte "compact" signature. This is a concatenation
   148  of the R and S fields of the signature. Some libraries will include an
   149  additional header byte, recovery ID field, or provide DER encoded signatures.
   150  Sawtooth will reject the signature if it is anything other than 64 bytes.
   151  
   152  Transactions
   153  ------------
   154  
   155  The transactions field contains a list of Transactions which make up the batch.
   156  Transactions are applied in the order listed.  The transaction_ids field
   157  contains a list of Transaction header_signatures and must be the same order as
   158  the transactions field.
   159  
   160  Why Batches?
   161  ============
   162  
   163  As we have stated above, a batch is the atomic unit of change in the system.
   164  If a batch has been applied, all transactions will have been applied in the
   165  order contained within the batch.  If a batch has not been applied (maybe
   166  because one of the transactions is invalid), then none of the transactions will
   167  be applied.
   168  
   169  This greatly simplifies dependency management from a client perspective, since
   170  transactions within a batch do not need explicit dependencies to be declared
   171  between them.  As a result, the usefulness of explicit dependencies (contained
   172  in the dependencies field on a Transaction) are constrained to dependencies
   173  where the transactions cannot be placed in the same batch.
   174  
   175  Batches solve an important problem which cannot be solved with explicit
   176  dependencies.  Suppose we have transactions A, B, and C and that the desired
   177  behavior is A, B, C be applied in that order, and if any of them are invalid,
   178  none of them should be applied.  If we attempted to solve this using only
   179  dependencies, we might attempt a relationship between them such as: C depends
   180  on B, B depends on A, and A depends on C.  However, the dependencies field
   181  cannot be used to represent this relationship, since dependencies enforce order
   182  and the above is cyclic (and thus cannot be ordered).
   183  
   184  Transactions from multiple transaction families can also be batched together,
   185  which further encourages reuse of transaction families.  For example,
   186  transactions for a configuration or identity transaction family could be
   187  batched with application-specific transactions.
   188  
   189  Transactions and batches can also be signed by different keys.  For example, a
   190  browser application can sign the transaction and a server-side component can
   191  add transactions and create the batch and sign the batch.  This enables
   192  interesting application patterns, including aggregation of transactions from
   193  multiple transactors into an atomic operation (the batch).
   194  
   195  There is an important restriction enforced between transactions and batches,
   196  which is that the transaction must contain the public key of the batch signer
   197  in the batcher_public_key field.  This is to prevent transactions from being reused
   198  separate from the intended batch.  So, for example, unless you have the
   199  batcher's private key, it is not possible to take transactions from a batch and
   200  repackage them into a new batch, omitting some of the transactions.
   201  
   202  .. Licensed under Creative Commons Attribution 4.0 International License
   203  .. https://creativecommons.org/licenses/by/4.0/