This page is the Simplified Technical English version of ZIP 225. The source ZIP is the normative text. Read the writing rules to understand the marked words.
ZIP 225: Version 5 Transaction Format
ZIP: 225
Title: Version 5 Transaction Format
Owners: Daira-Emma Hopwood <daira@jacaranda.org>
Jack Grigg <thestr4d@gmail.com>
Sean Bowe <ewillbefull@gmail.com>
Kris Nuttycombe <kris@nutty.land>
Original-Authors: Ying Tong Lai
Status: Final
Category: Consensus
Created: 2021-02-28
License: MIT
Discussions-To: <https://github.com/zcash/zips/issues/440>
Terminology
On this page, STE words are in the place of the BCP 14 key words of the source. Refer to the key word table.
The character § is used for references to sections of the Zcash Protocol Specification [protocol].
Abstract
This ZIP contains an update to the Zcash peer-to-peer transaction format. The new format has the data elements that are necessary for the Orchard protocol [protocol].
The new transaction format has well-bounded regions of the serialized form for each of the existing pools of funds. It also has a new region that contains Orchard-specific elements. This ZIP contains the description of that region.
This ZIP also depends on, and contains, changes to the computation of these values that are defined in ZIP 244 [zip-0244]:
- TxId Digest
- Signature Digest
- Authorizing Data Commitment
Motivation
The serialized data elements that are necessary for the new Orchard shielded pool are different from the data elements of any previous Zcash transaction.
In addition, from the activation of ZIP 244, the serialized transaction format is no longer consensus-critical. At this point, it is reasonable to define a format that is easy to extend in a systematic way in the future. In such a format, the elements that are necessary for the support of a given pool stay separate.
Requirements
The new format must have full support for the Orchard protocol.
We recommend that the new format is easy to extend or to prune in the future, to add or to remove value pools.
The computation of the non-malleable transaction identifier hash must include all the new elements except the elements that are evidence of transaction validity.
The computation of the commitment to authorizing data for a transaction must include all the new elements that are evidence of transaction validity.
Non-requirements
More general forms of extensibility are not necessary. An example is the definition of a key/value format. With such a format, a parser does not have to know all the components.
Specification
All fields in this specification are encoded as little-endian.
The Zcash transaction format for transaction version 5 is as follows:
Transaction Format
| Bytes | Name | Data Type | Description |
|---|---|---|---|
| Common Transaction Fields | |||
4 | header | uint32 | The field contains:
|
4 | nVersionGroupId | uint32 | The version group ID. The value is nonzero. It is specified in § 7.1.2. |
4 | nConsensusBranchId | uint32 | The consensus branch ID. The value is nonzero. It is constrained in § 7.1.2. |
4 | lock_time | uint32 | A Unix-epoch UTC time or a block height. It is encoded as in Bitcoin. |
4 | nExpiryHeight | uint32 | A block height in the range {1 .. 499999999}, or 0. After this block height, the transaction expires. If the value is 0, the transaction does not expire. Refer to ZIP 203. |
| Transparent Transaction Fields | |||
varies | tx_in_count | compactSize | The number of transparent inputs in tx_in. |
varies | tx_in | tx_in | The transparent inputs. They are encoded as in Bitcoin. |
varies | tx_out_count | compactSize | The number of transparent outputs in tx_out. |
varies | tx_out | tx_out | The transparent outputs. They are encoded as in Bitcoin. |
| Sapling Transaction Fields | |||
varies | nSpendsSapling | compactSize | The number of Sapling Spend descriptions in vSpendsSapling. |
96 * nSpendsSapling | vSpendsSapling | SpendDescriptionV5[nSpendsSapling] | A sequence of Sapling Spend descriptions. They are encoded as specified in protocol §7.3 ‘Spend Description Encoding and Consensus’. |
varies | nOutputsSapling | compactSize | The number of Sapling Output descriptions in vOutputsSapling. |
756 * nOutputsSapling | vOutputsSapling | OutputDescriptionV5[nOutputsSapling] | A sequence of Sapling Output descriptions. They are encoded as specified in protocol §7.4 ‘Output Description Encoding and Consensus’. |
8 | valueBalanceSapling | int64 | The net value of Sapling Spends minus Outputs |
32 | anchorSapling | byte[32] | A root of the Sapling note commitment tree at some block height in the past. |
192 * nSpendsSapling | vSpendProofsSapling | byte[192 * nSpendsSapling] | The encodings of the zk-SNARK proofs for each Sapling Spend. |
64 * nSpendsSapling | vSpendAuthSigsSapling | byte[64 * nSpendsSapling] | The authorizing signatures for each Sapling Spend. |
192 * nOutputsSapling | vOutputProofsSapling | byte[192 * nOutputsSapling] | The encodings of the zk-SNARK proofs for each Sapling Output. |
64 | bindingSigSapling | byte[64] | A Sapling binding signature on the SIGHASH transaction hash. |
| Orchard Transaction Fields | |||
varies | nActionsOrchard | compactSize | The number of Orchard Action descriptions in vActionsOrchard. |
820 * nActionsOrchard | vActionsOrchard | OrchardAction[nActionsOrchard] | A sequence of Orchard Action descriptions. They are encoded as specified in §7.5 ‘Action Description Encoding and Consensus’. |
1 | flagsOrchard | byte | An 8-bit value that contains a set of flags. The order of the flags is from LSB to MSB:
|
8 | valueBalanceOrchard | int64 | The net value of Orchard spends minus outputs. |
32 | anchorOrchard | byte[32] | A root of the Orchard note commitment tree at some block height in the past. |
varies | sizeProofsOrchard | compactSize | The length in bytes of proofsOrchard. The value is \(2720 + 2272 \cdot \mathtt{nActionsOrchard}\!\). |
sizeProofsOrchard | proofsOrchard | byte[sizeProofsOrchard] | The encoding of the aggregated zk-SNARK proofs for Orchard Actions. |
64 * nActionsOrchard | vSpendAuthSigsOrchard | byte[64 * nActionsOrchard] | The authorizing signatures for each Orchard Action. |
64 | bindingSigOrchard | byte[64] | An Orchard binding signature on the SIGHASH transaction hash. |
- The fields
valueBalanceSaplingandbindingSigSaplingare present if and only if \(\mathtt{nSpendsSapling} + \mathtt{nOutputsSapling} > 0\). IfvalueBalanceSaplingis not present, then \(\mathsf{v^{balanceSapling}}\) is defined to be \(0\). - The field
anchorSaplingis present if and only if \(\mathtt{nSpendsSapling} > 0\). - These fields are present if and only if \(\mathtt{nActionsOrchard} > 0\):
flagsOrchardvalueBalanceOrchardanchorOrchardsizeProofsOrchardproofsOrchardbindingSigOrchard
valueBalanceOrchardis not present, then \(\mathsf{v^{balanceOrchard}}\) is defined to be \(0\). - The elements of
vSpendProofsSaplingandvSpendAuthSigsSaplinghave a 1:1 correspondence to the elements ofvSpendsSapling. These elements must be in an order such that the proof or signature at a given index is for theSpendDescriptionV5at the same index. - The elements of
vOutputProofsSaplinghave a 1:1 correspondence to the elements ofvOutputsSapling. These elements must be in an order such that the proof at a given index is for theOutputDescriptionV5at the same index. - The proofs that are aggregated in
proofsOrchard, and the elements ofvSpendAuthSigsOrchard, each have a 1:1 correspondence to the elements ofvActionsOrchard. These items must be in an order such that the proof or signature at a given index is for theOrchardActionat the same index. - For coinbase transactions, the
enableSpendsOrchardbit must be set to \(0\).
The encodings of tx_in and tx_out are as in a version 4 transaction. That is, they are the same as in Canopy. The encodings of these items are in the sections that follow:
SpendDescriptionV5OutputDescriptionV5OrchardAction
For Sapling Spends and Outputs, the encoding is different from the encoding in previous versions. The change has two reasons. The first reason is a better separation of two kinds of data. One kind is the description of the effects of the transaction. The other kind is the proofs of those effects and the commitments to those effects. The second reason is symmetry with this separation in the Orchard-related parts of the transaction format.
Sapling Spend Description (SpendDescriptionV5)
| Bytes | Name | Data Type | Description |
|---|---|---|---|
32 | cv | byte[32] | A value commitment to the net value of the input note. |
32 | nullifier | byte[32] | The nullifier of the input note. |
32 | rk | byte[32] | The randomized validating key for the element of spendAuthSigsSapling that is for this Spend. |
The encodings of each of these elements are defined in §7.3 ‘Spend Description Encoding and Consensus’ of the Zcash Protocol Specification [protocol-spenddesc].
Sapling Output Description (OutputDescriptionV5)
| Bytes | Name | Data Type | Description |
|---|---|---|---|
32 | cv | byte[32] | A value commitment to the net value of the output note. |
32 | cmu | byte[32] | The \(u\!\)-coordinate of the note commitment for the output note. |
32 | ephemeralKey | byte[32] | An encoding of an ephemeral Jubjub public key. |
580 | encCiphertext | byte[580] | The encrypted contents of the note plaintext. |
80 | outCiphertext | byte[80] | The encrypted contents of the byte string that is the concatenation of the transmission key and the ephemeral secret key. |
The encodings of each of these elements are defined in §7.4 ‘Output Description Encoding and Consensus’ of the Zcash Protocol Specification [protocol-outputdesc].
Orchard Action Description (OrchardAction)
| Bytes | Name | Data Type | Description |
|---|---|---|---|
32 | cv | byte[32] | A value commitment to the net value of the input note minus the output note. |
32 | nullifier | byte[32] | The nullifier of the input note. |
32 | rk | byte[32] | The randomized validating key for the element of spendAuthSigsOrchard that is for this Action. |
32 | cmx | byte[32] | The \(x\!\)-coordinate of the note commitment for the output note. |
32 | ephemeralKey | byte[32] | An encoding of an ephemeral Pallas public key. |
580 | encCiphertext | byte[580] | The encrypted contents of the note plaintext. |
80 | outCiphertext | byte[80] | The encrypted contents of the byte string that is the concatenation of the transmission key and the ephemeral secret key. |
The encodings of each of these elements are defined in §7.5 ‘Action Description Encoding and Consensus’ of the Zcash Protocol Specification [protocol-actiondesc].
Alternatives
The original version of this ZIP included these Sprout-related fields in the V5 transaction format:
nJoinSplitvJoinSplitjoinSplitPubKeyjoinSplitSig
The Electric Coin Company and Zcash Foundation teams decided to remove these fields from the V5 transaction format. This removal is part of the continuing process of deprecation of the Sprout shielded pool. The removal of these fields has this consequence:
- Migration transactions for the direct movement of funds from the Sprout pool to the Orchard pool are in effect prohibited. Migration transactions from Sprout to Transparent and from Sprout to Sapling are still supported with the V4 transaction format.
Without these fields, the NU5 network upgrade is less complex in these ways:
- Code for V5 parsing and serialization does not have to take these fields into account.
- These computations of ZIP 244 [zip-0244] are simpler, because they do not include these fields:
- The transaction identifier.
- The signature hash.
- The authorizing data commitment.
The removal of these fields has a consequence for the future. If the support for the V4 transaction format is removed, the support for Sprout transactions on the Zcash network also ends in effect. But limited support for migration can possibly be restored with a future ZIP 222 [zip-0222] extension, or by other means that are not yet determined.
The original definitions for the transaction fields that were removed are:
| Sprout Transaction Fields | |||
varies | nJoinSplit | compactSize | The number of JoinSplit descriptions in vJoinSplit. |
1698 * nJoinSplit | vJoinSplit | JSDescriptionGroth16[nJoinSplit] | A sequence of JoinSplit descriptions that use Groth16 proofs. They are encoded as specified in §7.2 ‘JoinSplit Description Encoding and Consensus’. |
32 | joinSplitPubKey | byte[32] | An encoding of a JoinSplitSig public validating key. |
64 | joinSplitSig | byte[64] | A signature on a prefix of the transaction encoding. The signature is verified with joinSplitPubKey, as specified in §4.11 ‘Non-malleability (Sprout)’. |
- The
joinSplitPubKeyandjoinSplitSigfields were specified to be present if and only if \(\mathtt{nJoinSplit} > 0\).
Reference implementation
- https://github.com/zcash/zcash/pull/5202 (in
zcashd) - https://github.com/zcash/librustzcash/pull/375 (in
librustzcash)
References
- [BCP14]
- Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
- [protocol]
- Zcash Protocol Specification, Version 2021.2.16 or later [NU5 proposal]
- [protocol-spenddesc]
- Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.4: Spend Descriptions
- [protocol-outputdesc]
- Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.5: Output Descriptions
- [protocol-actiondesc]
- Zcash Protocol Specification, Version 2021.2.16 [NU5 proposal]. Section 4.6: Action Descriptions
- [zip-0222]
- ZIP 222: Transparent Zcash Extensions
- [zip-0244]
- ZIP 244: Transaction Identifier Non-Malleability
- [zip-0307]
- ZIP 307: Light Client Protocol for Payment Detection