Zcash in Simplified Technical English

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]:

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

BytesNameData TypeDescription
Common Transaction Fields
4headeruint32The field contains:
  • The fOverwintered flag (bit 31, always set).
  • version (bits 30 .. 0): the transaction version.
4nVersionGroupIduint32The version group ID. The value is nonzero. It is specified in § 7.1.2.
4nConsensusBranchIduint32The consensus branch ID. The value is nonzero. It is constrained in § 7.1.2.
4lock_timeuint32A Unix-epoch UTC time or a block height. It is encoded as in Bitcoin.
4nExpiryHeightuint32A 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
variestx_in_countcompactSizeThe number of transparent inputs in tx_in.
variestx_intx_inThe transparent inputs. They are encoded as in Bitcoin.
variestx_out_countcompactSizeThe number of transparent outputs in tx_out.
variestx_outtx_outThe transparent outputs. They are encoded as in Bitcoin.
Sapling Transaction Fields
variesnSpendsSaplingcompactSizeThe number of Sapling Spend descriptions in vSpendsSapling.
96 * nSpendsSaplingvSpendsSaplingSpendDescriptionV5[nSpendsSapling]A sequence of Sapling Spend descriptions. They are encoded as specified in protocol §7.3 ‘Spend Description Encoding and Consensus’.
variesnOutputsSaplingcompactSizeThe number of Sapling Output descriptions in vOutputsSapling.
756 * nOutputsSaplingvOutputsSaplingOutputDescriptionV5[nOutputsSapling]A sequence of Sapling Output descriptions. They are encoded as specified in protocol §7.4 ‘Output Description Encoding and Consensus’.
8valueBalanceSaplingint64The net value of Sapling Spends minus Outputs
32anchorSaplingbyte[32]A root of the Sapling note commitment tree at some block height in the past.
192 * nSpendsSaplingvSpendProofsSaplingbyte[192 * nSpendsSapling]The encodings of the zk-SNARK proofs for each Sapling Spend.
64 * nSpendsSaplingvSpendAuthSigsSaplingbyte[64 * nSpendsSapling]The authorizing signatures for each Sapling Spend.
192 * nOutputsSaplingvOutputProofsSaplingbyte[192 * nOutputsSapling]The encodings of the zk-SNARK proofs for each Sapling Output.
64bindingSigSaplingbyte[64]A Sapling binding signature on the SIGHASH transaction hash.
Orchard Transaction Fields
variesnActionsOrchardcompactSizeThe number of Orchard Action descriptions in vActionsOrchard.
820 * nActionsOrchardvActionsOrchardOrchardAction[nActionsOrchard]A sequence of Orchard Action descriptions. They are encoded as specified in §7.5 ‘Action Description Encoding and Consensus’.
1flagsOrchardbyteAn 8-bit value that contains a set of flags. The order of the flags is from LSB to MSB:
  • enableSpendsOrchard
  • enableOutputsOrchard
  • The remaining bits are set to \(0\!\).
8valueBalanceOrchardint64The net value of Orchard spends minus outputs.
32anchorOrchardbyte[32]A root of the Orchard note commitment tree at some block height in the past.
variessizeProofsOrchardcompactSizeThe length in bytes of proofsOrchard. The value is \(2720 + 2272 \cdot \mathtt{nActionsOrchard}\!\).
sizeProofsOrchardproofsOrchardbyte[sizeProofsOrchard]The encoding of the aggregated zk-SNARK proofs for Orchard Actions.
64 * nActionsOrchardvSpendAuthSigsOrchardbyte[64 * nActionsOrchard]The authorizing signatures for each Orchard Action.
64bindingSigOrchardbyte[64]An Orchard binding signature on the SIGHASH transaction hash.
  • The fields valueBalanceSapling and bindingSigSapling are present if and only if \(\mathtt{nSpendsSapling} + \mathtt{nOutputsSapling} > 0\). If valueBalanceSapling is not present, then \(\mathsf{v^{balanceSapling}}\) is defined to be \(0\).
  • The field anchorSapling is present if and only if \(\mathtt{nSpendsSapling} > 0\).
  • These fields are present if and only if \(\mathtt{nActionsOrchard} > 0\):
    • flagsOrchard
    • valueBalanceOrchard
    • anchorOrchard
    • sizeProofsOrchard
    • proofsOrchard
    • bindingSigOrchard
    If valueBalanceOrchard is not present, then \(\mathsf{v^{balanceOrchard}}\) is defined to be \(0\).
  • The elements of vSpendProofsSapling and vSpendAuthSigsSapling have a 1:1 correspondence to the elements of vSpendsSapling. These elements must be in an order such that the proof or signature at a given index is for the SpendDescriptionV5 at the same index.
  • The elements of vOutputProofsSapling have a 1:1 correspondence to the elements of vOutputsSapling. These elements must be in an order such that the proof at a given index is for the OutputDescriptionV5 at the same index.
  • The proofs that are aggregated in proofsOrchard, and the elements of vSpendAuthSigsOrchard, each have a 1:1 correspondence to the elements of vActionsOrchard. These items must be in an order such that the proof or signature at a given index is for the OrchardAction at the same index.
  • For coinbase transactions, the enableSpendsOrchard bit 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:

  • SpendDescriptionV5
  • OutputDescriptionV5
  • OrchardAction

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)

BytesNameData TypeDescription
32cvbyte[32]A value commitment to the net value of the input note.
32nullifierbyte[32]The nullifier of the input note.
32rkbyte[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)

BytesNameData TypeDescription
32cvbyte[32]A value commitment to the net value of the output note.
32cmubyte[32]The \(u\!\)-coordinate of the note commitment for the output note.
32ephemeralKeybyte[32]An encoding of an ephemeral Jubjub public key.
580encCiphertextbyte[580]The encrypted contents of the note plaintext.
80outCiphertextbyte[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)

BytesNameData TypeDescription
32cvbyte[32]A value commitment to the net value of the input note minus the output note.
32nullifierbyte[32]The nullifier of the input note.
32rkbyte[32]The randomized validating key for the element of spendAuthSigsOrchard that is for this Action.
32cmxbyte[32]The \(x\!\)-coordinate of the note commitment for the output note.
32ephemeralKeybyte[32]An encoding of an ephemeral Pallas public key.
580encCiphertextbyte[580]The encrypted contents of the note plaintext.
80outCiphertextbyte[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:

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:

Without these fields, the NU5 network upgrade is less complex in these ways:

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
variesnJoinSplitcompactSizeThe number of JoinSplit descriptions in vJoinSplit.
1698 * nJoinSplitvJoinSplitJSDescriptionGroth16[nJoinSplit]A sequence of JoinSplit descriptions that use Groth16 proofs. They are encoded as specified in §7.2 ‘JoinSplit Description Encoding and Consensus’.
32joinSplitPubKeybyte[32]An encoding of a JoinSplitSig public validating key.
64joinSplitSigbyte[64]A signature on a prefix of the transaction encoding. The signature is verified with joinSplitPubKey, as specified in §4.11 ‘Non-malleability (Sprout)’.

Reference implementation

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