Include signature hash & auth commitment sections.

zip-0244.rst

@@ -137,28 +137,48 @@ In the specification below, nodes of the tree are presented in depth-first order
 --------------
 A BLAKE2b-256 hash of the following values ::
 
-   * ``header_digest`` (32-byte hash output)
+   * T.1: ``header_digest`` (32-byte hash output)
-   * ``transparent_digest`` (32-byte hash output)
+   * T.2: ``transparent_digest`` (32-byte hash output)
-   * ``sprout_digest (32-byte hash output)
+   * T.3: ``sprout_digest (32-byte hash output)
-   * ``sapling_digest (32-byte hash output)
+   * T.4: ``sapling_digest (32-byte hash output)
+
+The personalization field of this hash is set to::
+
+  "ZcashTxHash_" || CONSENSUS_BRANCH_ID
+
+As in ZIP 143 [#zip-0143]_, CONSENSUS_BRANCH_ID is the 4-byte little-endian encoding of
+the consensus branch ID for the epoch of the block containing the transaction. Domain
+separation of the transaction id hash across parallel consensus branches provides replay
+protection: transactions targeted for one consensus branch will not have the same
+transaction identifier on other consensus branches.
+
+T.1: ``header_digest``
+`````````````````````````
+A BLAKE2b-256 hash of the following values ::
+
+* T.1a. ``version`` (4-byte little-endian version identifier including overwinter flag)
+* T.1b. ``version_group_id`` (4-byte little-endian version group identifier)
+* T.1c. ``consensus_branch_id`` (4-byte little-endian consensus branch id)
+* T.1d. ``lock_time``  (4-byte little-endian nLockTime value)
+* T.1e. ``expiry_height``  (4-byte little-endian block height)
 
 The personalization field of this hash is set to::
 
   "ZTxIdHeadersHash"
 
-1: ``transparent_digest``
+T.2: ``transparent_digest``
 `````````````````````````
 A BLAKE2b-256 hash of the following values ::
 
-* 1a. ``prevouts_digest`` (32-byte hash)
+* T.2a. ``prevouts_digest`` (32-byte hash)
-* 1b. ``sequence_digest`` (32-byte hash)
+* T.2b. ``sequence_digest`` (32-byte hash)
-* 1c. ``outputs_digest``  (32-byte hash)
+* T.2c. ``outputs_digest``  (32-byte hash)
 
 The personalization field of this hash is set to::
 
   "ZTxIdTranspaHash"
 
-1a: ``prevouts_digest``
+T.2a: ``prevouts_digest``
 '''''''''''''''''''''''
 A BLAKE2b-256 hash of the field encoding of all ``outpoint``
 field values of transparent inputs to the transaction.
@@ -167,7 +187,7 @@ The personalization field of this hash is set to::
 
   "ZTxIdPrevoutHash"
 
-1b: ``sequence_digest``
+T.2b: ``sequence_digest``
 '''''''''''''''''''''''
 A BLAKE2b-256 hash of the 32-bit little-endian representation of all ``nSequence``
 field values of transparent inputs to the transaction.
@@ -176,29 +196,36 @@ The personalization field of this hash is set to::
 
   "ZTxIdSequencHash"
 
-1c: ``outputs_digest``
+T.2c: ``outputs_digest``
 ''''''''''''''''''''''
-A BLAKE2b-256 hash of the field encoding of all transparent outputs 
+A BLAKE2b-256 hash of the field encodings of all ``prevout`` field values of 
-belonging to the transaction.
+transparent inputs belonging to the transaction.
 
 The personalization field of this hash is set to::
 
   "ZTxIdOutputsHash"
 
-2: ``sprout_digest``
+T.3: ``sprout_digest``
 `````````````````````````
-A BLAKE2b-256 hash of the field encoding of all Sprout ``JoinSplit`` components of the
+A BLAKE2b-256 hash of the non-authorizing components of Sprout ``JSDescription`` values
-transaction followed by the field encoding of the ``joinSplitPubKey`` value. This is
+belonging to the transaction. For each ``JSDescription``, the following elements are
-equivalent to the internal hash that is specified by ZIP 143 [#zip-0143]_ over the Sprout
+appended to the hash ::
-data, with the distinction that the unmodified hash finalized immediately after
+
-initialization with the personalization string is used in the case that no ``JoinSplit``
+* T.3a. ``vpub_old`` (8-byte signed little-endian)
-components exist, rather than the ``uint256`` of ``0x0000...0000``.
+* T.3b. ``vpub_new`` (8-byte signed little-endian)
+* T.3c. ``anchor``   (32 bytes)
+* T.3d. ``nullifiers``  (2 x 32 bytes)
+* T.3e. ``commitments`` (2 x 32 bytes)
+* T.3f. ``ephemeral_key`` (32 bytes)
+* T.3g. ``random_seed`` (32 bytes)
+* T.3h. ``macs`` (2 x 32 bytes)
+* T.3i. ``ciphertexts`` (2 x 601 bytes)
 
 The personalization field of this hash is set to::
 
   "ZTxIdJSplitsHash"
 
-3: ``sapling_digest``
+T.4: ``sapling_digest``
 `````````````````````
 The digest of Sapling components is composed of two subtrees which are organized to 
 permit easy interoperability with the ``CompactBlock`` representation of Sapling data
@@ -206,26 +233,26 @@ specified by the ZIP 307 Light Client Protocol [#zip-0307]_.
 
 This digest is a BLAKE2b-256 hash of the following values ::
 
-   * 3a. ``sapling_spends_digest`` (32-byte hash)
+   * T.4a. ``sapling_spends_digest`` (32-byte hash)
-   * 3b. ``sapling_outputs_digest`` (32-byte hash)
+   * T.4b. ``sapling_outputs_digest`` (32-byte hash)
-   * 3c. ``valueBalance`` (64-bit signed little-endian)
+   * T.4c. ``valueBalance`` (64-bit signed little-endian)
 
 The personalization field of this hash is set to::
 
   "ZTxIdSaplingHash"
 
-3a: ``sapling_spends_digest``
+T.4a: ``sapling_spends_digest``
 ''''''''''''''''''''''''''''''
 This digest is a BLAKE2b-256 hash of the following values ::
 
-   * 3a.i.   ``sapling_spends_compact_digest`` (32-byte hash)
+   * T.4a.i.   ``sapling_spends_compact_digest`` (32-byte hash)
-   * 3b.ii.  ``sapling_spends_noncompact_digest`` (32-byte hash)
+   * T.4a.ii.  ``sapling_spends_noncompact_digest`` (32-byte hash)
 
 The personalization field of this hash is set to::
 
   "ZTxIdSSpendsHash"
 
-3a.i: ``sapling_spends_compact_digest``
+T.4a.i: ``sapling_spends_compact_digest``
 .......................................
 A BLAKE2b-256 hash of the field encoding of all nullifier field
 values of Sapling shielded spends belonging to the transaction.
@@ -234,77 +261,215 @@ The personalization field of this hash is set to::
 
   "ZTxIdSSpendCHash"
 
-3a.ii: ``sapling_spends_noncompact_digest``
+T.4a.ii: ``sapling_spends_noncompact_digest``
 ...........................................
 A BLAKE2b-256 hash of the non-nullifier information for all Sapling shielded spends
-belonging to the transaction. For each spend, the following elements are included
+belonging to the transaction, excluding zkproof data. For each spend, the following
-in the hash:: 
+elements are included in the hash:: 
 
-   * 3a.ii.1 ``cv``      (field encoding bytes)
+   * T.4a.ii.1 ``cv``      (field encoding bytes)
-   * 3a.ii.2 ``anchor``  (field encoding bytes)
+   * T.4a.ii.2 ``anchor``  (field encoding bytes)
-   * 3a.ii.3 ``rk``      (field encoding bytes)
+   * T.4a.ii.3 ``rk``      (field encoding bytes)
-   * 3a.ii.4 ``zkproof`` (field encoding bytes)
 
 The personalization field of this hash is set to::
 
   "ZTxIdSSpendNHash"
 
-3b: ``sapling_outputs_digest``
+T.4b: ``sapling_outputs_digest``
 '''''''''''''''''''''''''''''''
 This digest is a BLAKE2b-256 hash of the following values ::
 
-   * 3a.i.   ``sapling_outputs_compact_digest`` (32-byte hash)
+   * T.4a.i.   ``sapling_outputs_compact_digest`` (32-byte hash)
-   * 3b.ii.  ``sapling_outputs_memos_digest`` (32-byte hash)
+   * T.4b.ii.  ``sapling_outputs_memos_digest`` (32-byte hash)
-   * 3b.iii. ``sapling_outputs_noncompact_digest`` (32-byte hash)
+   * T.4b.iii. ``sapling_outputs_noncompact_digest`` (32-byte hash)
 
 The personalization field of this hash is set to::
 
   "ZTxIdSOutputHash"
 
-3b.i: ``sapling_outputs_compact_digest``
+T.4b.i: ``sapling_outputs_compact_digest``
 .........................................
 A BLAKE2b-256 hash of the subset of Sapling output information included in the 
 ZIP-307 [#zip-0307]_ ``CompactBlock`` format for all Sapling shielded outputs
 belonging to the transaction. For each output, the following elements are included
 in the hash:: 
 
-   * 3b.i.1 ``cmu``                  (field encoding bytes)
+   * T.4b.i.1 ``cmu``                  (field encoding bytes)
-   * 3b.i.2 ``ephemeral_key``        (field encoding bytes)
+   * T.4b.i.2 ``ephemeral_key``        (field encoding bytes)
-   * 3b.i.3 ``enc_ciphertext[..52]`` (First 52 bytes of field encoding)
+   * T.4b.i.3 ``enc_ciphertext[..52]`` (First 52 bytes of field encoding)
 
 The personalization field of this hash is set to::
 
   "ZTxIdSOutC__Hash"
 
-3a.ii: ``sapling_outputs_memos_digest``
+T.4a.ii: ``sapling_outputs_memos_digest``
 ........................................
 A BLAKE2b-256 hash of the subset of Sapling shielded memo field data for all Sapling 
 shielded outputs belonging to the transaction. For each output, the following elements 
 are included in the hash:: 
 
-   * 3b.ii.1 ``enc_ciphertext[52..564] (contents of the encrypted memo field)
+   * T.4b.ii.1 ``enc_ciphertext[52..564] (contents of the encrypted memo field)
 
 The personalization field of this hash is set to::
 
   "ZTxIdSOutM__Hash"
 
-3a.iii: ``sapling_outputs_noncompact_digest``
+T.4a.iii: ``sapling_outputs_noncompact_digest``
 ..............................................
 A BLAKE2b-256 hash of the remaining subset of Sapling output information **not** included
-in the ZIP-307 [#zip-0307]_ ``CompactBlock`` format, for all Sapling shielded outputs belonging to the
+in the ZIP 307 [#zip-0307]_ ``CompactBlock`` format, excluding zkproof data, for all
-transaction. For each output, the following elements are included in the hash:: 
+Sapling shielded outputs belonging to the transaction. For each output, the following
+elements are included in the hash:: 
 
-   * 3b.iii.1 ``cv``                    (field encoding bytes)
+   * T.4b.iii.1 ``cv``                    (field encoding bytes)
-   * 3b.iii.2 ``enc_ciphertext[564..]`` (post-memo suffix of field encoding)
+   * T.4b.iii.2 ``enc_ciphertext[564..]`` (post-memo suffix of field encoding)
-   * 4b.iii.3 ``out_ciphertext``        (field encoding bytes)
+   * T.4b.iii.3 ``out_ciphertext``        (field encoding bytes)
-   * 4b.iii.4 ``zkproof``               (field encoding bytes)
 
 The personalization field of this hash is set to::
 
   "ZTxIdSOutN__Hash" (2 underscore characters)
 
-Witness Digest
+Signature Digest
-==============
+================
+
+A new per-input transaction digest algorithm that constructs a hash that may be signed
+by a transaction creator to commit to the effects of the transaction. In the
+case that the transaction consumes no transparent inputs, it should be possible
+to just sign the transaction identifier produced by the ``TxId Digest`` algorithm.
+In the case that transparent inputs are present, this algorithm follows closely
+the ZIP 143 [#zip-0143]_ algorithm.
+
+The overall structure of the hash is as follows; each name referenced here will be
+described in detail below:
+
+    signature_digest
+    ├── header_digest
+    ├── transparent_digest
+    ├── sprout_digest
+    └── sapling_digest
+
+``signature_digest``
+--------------------
+A BLAKE2b-256 hash of the following values ::
+
+   * S.1: ``header_digest`` (32-byte hash output)
+   * S.2: ``transparent_digest`` (32-byte hash output)
+   * S.3: ``sprout_digest (32-byte hash output)
+   * S.4: ``sapling_digest (32-byte hash output)
+
+The personalization field of this hash is set to::
+
+  "ZcashTxHash_" || CONSENSUS_BRANCH_ID
+
+This value must have the same personalization as the top hash of the transaction
+identifier digest tree, in order to make it possible to sign the transaction id
+in the case that there are no transparent inputs.
+
+S.1: ``header_digest``
+`````````````````````````
+Identical to that specified for the transaction identifier.
+
+S.2: ``transparent_digest``
+`````````````````````````
+If we are producing a hash for the signature over a transparent input,
+the value of the digest produced here depends upon the value of a ``hash_type``
+flag as in ZIP 143 [#zip-0143]_ and BIP 143 [#bip-0143]_.
+
+The construction of each component below depends upon the values of the 
+hash_type flag bits. Each component will be described separately
+
+This digest is a BLAKE2b-256 hash of the following values ::
+
+   * S.2a. ``prevouts_digest`` (32-byte hash)
+   * S.2b. ``sequence_digest`` (32-byte hash)
+   * S.2c. ``outputs_digest`` (32-byte hash)
+   * S.2d. ``txin_sig_digest`` (32-byte hash)
+
+The personalization field of this hash is set to::
+
+   "ZTxIdTranspaHash"
+
+S.2a: ``prevouts_digest``
+'''''''''''''''''''''''
+This is a BLAKE2b-256 hash initialized with the personalization field value 
+"ZTxIdPrevoutHash". 
+
+If the ``SIGHASH_ANYONECANPAY`` flag is set::
+
+   * the hash is immediately finalized, without being updated with any
+     additional data
+
+otherwise::
+
+   * identical to the value of ``prevouts_digest`` as specified for the
+     transaction identifier in section T.2a.
+
+S.2b: ``sequence_digest``
+'''''''''''''''''''''''
+This is a BLAKE2b-256 hash initialized with the personalization field value 
+"ZTxIdSequencHash". 
+
+If any of the ``SIGHASH_ANYONECANPAY``, ``SIGHASH_SINGLE``, or ``SIGHASH_NONE`` flags are
+set::
+
+   * the hash is immediately finalized, without being updated with any
+     additional data
+
+otherwise::
+
+   * identical to the value of ``sequence_digest`` as specified for the
+     transaction identifier in section T.2b.
+
+S.2c: ``outputs_digest``
+'''''''''''''''''''''''
+This is a BLAKE2b-256 hash initialized with the personalization field value 
+"ZTxIdOutputsHash". 
+
+If the ``SIGHASH_SINGLE`` flag is set and the signature hash is being computed for a
+transparent input::
+
+   * the hash is updated with the field encoding of the ``prevout`` field value 
+     of the input, then finalized
+
+If the ``SIGHASH_SINGLE`` flag is set and the signature is being computed for
+a shielded input, or if the ``SIGHASH_NONE`` flag is set::
+
+   * the hash is immediately finalized, without being updated with any
+     additional data
+
+otherwise::
+
+   * identical to the value of ``outputs_digest`` as specified for the
+     transaction identifier in section T.2c.
+
+S.2d: ``txin_sig_digest``
+'''''''''''''''''''''''''
+This is a BLAKE2b-256 hash initialized with the personalization field value
+"Zcash___TxInHash" (3 underscores).
+
+If the signature hash is being computed for a transparent input, the hash
+is updated with the following properties of that input::
+
+   * S.2d.i.   ``prevout``     (field encoding)
+   * S.2d.ii.  ``script_code`` (field encoding)
+   * S.2d.iii. ``value``       (8-byte signed little-endian)
+   * S.2d.iv.  ``nSequence``   (4-byte unsigned little-endian)
+
+otherwise::
+   
+   * the hash is immediately finalized, without being updated with any
+     additional data
+
+S.3: ``sprout_digest``
+`````````````````````````
+Identical to that specified for the transaction identifier.
+
+S.4: ``sapling_digest``
+`````````````````````````
+Identical to that specified for the transaction identifier.
+
+Auth Commitment
+===============
 
 A new transaction digest algorithm is defined that constructs a digest which commits
 to the authorizing data of a transaction from a tree of BLAKE2b-256 hashes. 
@@ -312,21 +477,22 @@ The overall structure of the hash is as follows:
 
     auth_digest
     ├── transparent_scripts_digest
-    ├── tze_witnesses_digest
     ├── sprout_sigs_digest
     └── sapling_sigs_digest
 
 Each node written as ``snake_case`` in this tree is a BLAKE2b-256 hash of authorizing
 data of the transaction.
 
+The pair (Transaction Identifier, Auth Commitment) constitutes a commitment to all the
+data of a serialized transaction that may be included in a block. 
+
 ``auth_digest``
 --------------
 A BLAKE2b-256 hash of the following values ::
 
    * ``transparent_scripts_digest`` (32-byte hash output)
-   * ``tze_witnesses_digest (32-byte hash output)
+   * ``sprout_auth_digest (32-byte hash output)
-   * ``sprout_sigs_digest (32-byte hash output)
+   * ``sapling_auth_digest (32-byte hash output)
-   * ``sapling_sigs_digest (32-byte hash output)
 
 The personalization field of this hash is set to::
 
@@ -341,20 +507,28 @@ The personalization field of this hash is set to::
 
   "ZTxAuthTransHash"
 
-3: ``sprout_sigs_digest``
+2: ``sprout_auth_digest``
 ```````````````````````````
-A BLAKE2b-256 hash of the field encoding of the JoinSplit signature
+A BLAKE2b-256 hash of the field encoding of the zkproof values of each
-belonging to the transaction.
+``JSDescription`` belonging to the transaction.
+
+   * 2a. ``zkproofs``         (field encoding bytes)
+   * 2b. ``joinsplit_pubkey``    
+   * 2b. ``joinsplit_sig``     
 
 The personalization field of this hash is set to::
 
   "ZTxAuthSprouHash"
 
-3: ``sapling_sigs_digest``
+3: ``sapling_auth_digest``
 ```````````````````````````
-A BLAKE2b-256 hash of the field encoding of the Sapling signature
+A BLAKE2b-256 hash of the field encoding of the Sapling zkproof values
-of each Sapling spend description belonging to the transaction, followed by the
+of each Sapling spend description and output description belonging to 
-field encoding of the binding signature.
+the transaction, followed by the field encoding of the binding signature ::
+
+   * 3a. ``spend_zkproofs``  (field encoding bytes)
+   * 3b. ``output_zkproofs`` (field encoding bytes)
+   * 3c. ``binding_sig``     
 
 The personalization field of this hash is set to::
 
@@ -364,7 +538,13 @@ The personalization field of this hash is set to::
 Block Header Changes
 --------------------
 
-// TODO: Need @str4d's help here.
+Rationale
+=========
+
+We need to add a new hash commitment to the block header, the root of the
+witness hash.
+
+
 
 ========================
 Reference implementation
@@ -372,35 +552,6 @@ Reference implementation
 
 - https://github.com/zcash/librustzcash/pull/319/files
 
-============
-Alternatives
-============
-
-The zkproof components of Sapling spends and outputs could reasonably be
-construed as authorizing data, rather that information that describes 
-value transfer. As such, it was suggested that these proof values should
-not be committed to by in the transaction identifier, and should instead
-be used as inputs to the signature hash. Proof data is a potential source
-of transaction malleability, and as such this argument is worthy of 
-consideration.
-
-As was stated in :ref:`_requirements-anchor`, a desired property of transaction
-identifiers is that it should be possible for transaction signatures to commit
-to the transaction identifier directly in the case that the transaction contains
-no transparent inputs or in the case that only the ``SIGHASH_ALL`` flag is
-used. Including proofs for signature hash computation but not as part of the
-transaction identifier would make this goal unachievable.
-
-Unlike with transparent use cases where current sources of malleability represent
-a risk of double-spend attacks, in the case of a shielded-only transaction, 
-malleation of a zkproof value would invalidate any signatures associated with
-the transaction, since in the shielded scenario all signatures must commit to 
-all of the transaction's shielded spends, not just a subset, and so it is not
-possible for one party to a transaction to malleate their proofs in a way that
-does not break the signatures of any other party to the transaction. Thus, 
-this source of malleability is not considered to be of concern.
-
-
 ==========
 References
 ==========
@@ -409,5 +560,6 @@ References
 .. [#zip-0200] `ZIP 200: Network Upgrade Activation Mechanism <https://github.com/zcash/zips/blob/master/zip-0200.rst>`_
 .. [#zip-0076] `ZIP 76: Transaction Signature Validation before Overwinter <https://zips.z.cash/zip-0076>`_
 .. [#zip-0143] `ZIP 143: Transaction Signature Validation for Overwinter <https://zips.z.cash/zip-0143>`_
+.. [#bip-0143] `Transaction Signature Verification for Version 0 Witness Program <https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki>`_
 .. [#zip-0307] `ZIP 307: Light Client Protocol for Payment Detection <https://zips.z.cash/zip-0307>`_