ZIP: 248
Title: Extensible Transaction Format
Owners: Jack Grigg <[email protected]>
        Kris Nuttycombe <[email protected]>
        Daira-Emma Hopwood <[email protected]>
        Schell Scivally <[email protected]>
Status: Draft
Category: Consensus / Wallet
Created: 2025-12-17
License: MIT
Discussions-To: <https://github.com/zcash/zips/pull/1163>
Pull-Request: <https://github.com/zcash/zips/pull/1156>

Terminology

The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in BCP 14 1 when, and only when, they appear in all capitals.

The character § is used when referring to sections of the Zcash Protocol Specification. 2

The terms "Mainnet" and "Testnet" are to be interpreted as described in § 3.12 ‘Mainnet and Testnet’. 7

The term "full validator" in this document is to be interpreted as defined in § 3.3 ‘The Block Chain’. 3

The terms "Orchard protocol", "Orchard pool", and "Ironwood pool" are to be interpreted as described in ZIP 229. 19 Following the convention in the Zcash Protocol Specification, slanted text refers to pool names, to distinguish them from shielded protocols.

The functions \(\mathsf{TransactionFees}(\mathsf{height})\kern-0.03em\textsf{,}\) \(\mathsf{NSMFeeContribution}(\mathsf{height})\kern-0.03em\textsf{,}\) and \(\mathsf{MinerFees}(\mathsf{height})\) are to be interpreted as defined in ZIP 235. 21

The terms below are to be interpreted as follows:

v7 transaction format
The transaction format defined by this ZIP, identified by transaction version 7. Its version group ID is not yet assigned.
v7 transaction
A transaction that is encoded using the v7 transaction format.
pre-v7 transaction format
Any transaction format that precedes the v7 transaction format; that is, any of the v1 to v6 transaction formats.
transparent transaction value pool
An ephemeral balance within the scope of a single transaction, which is modified by additions and subtractions in the processing of the effects of transaction bundles. When all of the effects of a transaction are accounted for, this balance is zero; i.e., the total of additions to the balance equals the total of subtractions from it.

Abstract

This ZIP proposes an encoding for v7 Zcash transactions that reduces the impact of future transaction format changes on wallets and other clients. Previous format changes required clients to update their parsers even when they did not use newly introduced protocol features.

The format defines typecode-length-value encodings for protocol bundles and a value pool delta map describing each bundle's effect on the transparent transaction value pool. The entries of this map serve the same purpose as the Sapling and Orchard value balance fields have done in the past. Effecting data and authorizing data are encoded separately, allowing authorizing data to be pruned without removing the transaction's effects.

Clients can parse the common transaction envelope and enumerate public value flows without understanding every bundle type or variant. Computing the transaction identifier additionally requires a supplied digest for each unsupported effecting bundle. This does not eliminate the need to update wallets for consensus changes that alter how they must construct or interpret transactions.

Future additive bundle introductions can avoid making wallets' support for unused features distinguishable on-chain, reducing the need for further transaction-format changes and their associated privacy leakage.

Motivation

In the past, Zcash network upgrades that changed the transaction format have resulted in substantial disruption for wallets and other third-party clients in the Zcash ecosystem. In order to continue functioning after a network upgrade, clients were required to upgrade their Zcash transaction parsers to read the new format, even if the context in which those parsers were being used didn't need or couldn't make use of newly added transaction data. An example of this is that transparent-only wallets were forced to update their parsers to understand the Sapling and Orchard parts of transactions, even if they would never read or act upon those parts. This has led on occasion to significant problems in the Zcash ecosystem, including situations where funds have been locked and rendered unspendable from transparent-only wallets.

For some kinds of changes to consensus features, it's imperative that every wallet be aware of and be adapted to those changes, and in those cases making a major (breaking) transaction version update as we've done in the past is appropriate. For many new features, however, it is possible for a wallet to continue functioning correctly without having to fully understand a transaction using that feature.

For example, if TZEs were to be added to the protocol, it would be possible for wallets to continue operating with transparent/Sapling/Orchard functionality, ignoring TZE parts. There is substantial precedent for this sort of behavior; transparent-only hardware wallets are currently still important in the Zcash ecosystem, and many wallets didn't begin interacting with Orchard transaction parts until quite a while after Orchard activation.

After this change to transaction encoding, wallets and other third parties will not be required to update their transaction parsers in advance of a network upgrade for the introduction of many (and perhaps most) types of new protocol features. This will enable the Zcash ecosystem to make smaller and more incremental network upgrades without breaking existing wallets.

Privacy Implications

This change alters the encoding of transactions, but does not alter the information content of the transaction. As such, the only implication of this change is that the use of this transaction format acts as a 1-bit distinguisher that reveals that the wallet that generated the transaction has been updated to be aware of the new format. This information leakage is unavoidable for any transaction format change.

In the future, this change may reduce the amount of information leakage, since transactions created using the proposed TLV format will include bundles only for those protocols for which the transaction modifies chain state. For example, if this transaction format change is deployed in NU8 and a hypothetical NU9 defines a bundle type for TZE components, it will not be possible for a chain observer to distinguish whether or not the wallet that produced an Orchard-only transaction is one that has been updated to understand the TZE component. Under prior practices for changing the transaction format, this would have been distinguishable.

In summary, this proposal provides a net improvement in user privacy in addition to its other benefits.

Requirements

Non-requirements

  • It is not required to eliminate the need to update wallets for consensus changes that alter how they must construct or interpret transactions.

Specification

Protocol Bundles

This ZIP refines and codifies the concept of "protocol bundles" that emerged from the implementation of the ZIP 225 18 transaction format. It makes bundles first-class objects and defines a registry of bundle type and variant identifiers. Within the period that a given transaction format version is used on the Zcash network, the semantics of the bundle associated with a given (bundleType, bundleVariant) pair are fixed.

A protocol bundle is a self-contained component of a transaction that implements a specific piece of protocol functionality. Each bundle is identified by a (bundleType, bundleVariant) pair, where:

  • The bundle type identifies the protocol or value pool that the bundle operates on (e.g., Transparent, Sapling, Orchard).
  • The bundle variant identifies a specific variant of that protocol. New variants of an existing bundle type may be introduced by subsequent ZIPs to evolve a protocol's functionality while preserving the association with the same value pool.

A transaction MUST NOT contain more than one variant of any given bundle type. This constraint is enforced by the map structure of the transaction encoding: the maps mValuePoolDeltas, mEffectBundles, and mAuthBundles are each keyed by bundleType alone, and the parsing rules require the same bundleVariant for a given bundleType across all three maps.

Each bundle type/variant pair defines:

  • What effecting data the bundle contains — the data that determines what state changes the bundle produces (e.g., which notes are spent, which outputs are created, which transparent UTXOs are consumed or produced).
  • What authorizing data the bundle contains — the proofs and signatures that authorize the state changes specified by the effecting data.
  • How the bundle affects the transparent transaction value pool — whether the bundle adds value to, removes value from, or has no effect on this ephemeral pool that balances value flows within a transaction.

Rationale for Effecting Data and Authorizing Data

Click to show/hide

The separation of effecting data from authorizing data serves several purposes:

  1. Transaction identifier stability: The transaction identifier (txid) is computed only from the effecting data. This means that the txid is determined by what the transaction does, not by how it is authorized. Third parties cannot change a transaction's identifier by modifying signatures or proofs.
  2. Efficient pruning: Full nodes that have validated a transaction may prune the authorizing data while retaining the effecting data. Since authorizing data appears at the end of the encoded transaction, pruning is simply truncation.
  3. Partial processing: A wallet can parse a transaction's envelope without understanding every bundle type or variant. To compute the transaction identifier, it needs the corresponding bundle_effects_digest for each unsupported effecting bundle, as described in Implications for Wallets; hashing the opaque payload does not in general produce that digest.

The Transparent Transaction Value Pool

The transparent transaction value pool is an ephemeral concept that exists only within the scope of processing a single transaction. It serves as a balancing mechanism through which value flows between bundles.

Each bundle may contribute a value pool delta — a signed value indicating how much the bundle adds to or removes from the transparent transaction value pool. A positive delta means the bundle is adding value to the pool (e.g., a shielded spend releasing value), while a negative delta means the bundle is consuming value from the pool (e.g., a shielded output absorbing value, or a transaction fee).

For a valid transaction, the sum of all value pool deltas MUST equal zero. This ensures that value is neither created nor destroyed — it is only transferred between bundles within the transaction.

This holds for coinbase transactions as well. The part of the block subsidy that the transaction pays out enters the transparent transaction value pool as the value pool delta of the coinbase bundle, and the fees collected from the other transactions in the block enter it as the value pool delta of the fee bundle; the coinbase outputs then consume that value like any other bundle.

Bundle Type Registration

When a ZIP introduces a new bundle type or a new variant of an existing bundle type, it MUST:

  1. Request allocation of a (bundleType, bundleVariant) pair in the registry defined below. The bundleType and bundleVariant are each non-negative integers. If the ZIP introduces a new bundle type, it requests a new bundleType value with bundleVariant 0. If it introduces a new variant of an existing bundle type, it requests a new bundleVariant value for the existing bundleType.
  2. Specify whether entries for this bundle type are permitted in mValuePoolDeltas (the value pool delta map).
  3. Specify whether entries for this bundle type are permitted in mEffectBundles (the effecting data map).
  4. Specify whether entries for this bundle type are permitted in mAuthBundles (the authorizing data map).
  5. If effecting data is permitted, define the encoding of that data.
  6. If authorizing data is permitted, define the encoding of that data.
  7. Define the digest algorithm for the bundle's contribution to the transaction identifier, if effecting data is present.
  8. Define the digest algorithm for the bundle's contribution to the authorizing data commitment, if authorizing data is present.

A bundle type MUST NOT permit entries in mAuthBundles unless it also permits entries in mEffectBundles. That is, authorizing data cannot exist without corresponding effecting data for a given bundle type.

If a bundle's encoding defines a per-element sequence in its authorizing data as corresponding to a per-element sequence in its effecting data, it MUST specify that the two sequences have the same length and that elements at the same index correspond.

Once a (bundleType, bundleVariant) pair is assigned for a given transaction version, its semantics are fixed for the lifetime of that transaction version. A subsequent network upgrade may define a new transaction version that reassigns identifiers or changes bundle semantics, but within a single transaction version, bundle type and variant identifiers have stable, unchanging meanings.

A new variant of an existing bundle type MUST affect the same value pool(s) as the original bundle type. This ensures that a client that does not recognize a particular bundleVariant can still determine which pool(s) are affected by the bundle and inform its user accordingly.

v7 Transaction Bundle Type Registry

The following (bundleType, bundleVariant) pairs are registered for the v7 transaction format. All currently-defined values are encoded as single-byte compactSize values where they appear in the transaction format.

The mValuePoolDeltas column indicates whether or not an entry for this bundle type MAY appear in mValuePoolDeltas. For rows where an ❌ is present, the value pool delta for every pool is guaranteed to be zero, and so entries in mValuePoolDeltas MUST NOT be present.

The mEffectBundles column indicates whether or not an entry for this bundle type MAY appear in mEffectBundles. For rows where an ❌ is present, the bundle has no effecting data, and so an entry in mEffectBundles MUST NOT be present.

The mAuthBundles column indicates whether or not an entry for this bundle type MAY appear in mAuthBundles. For rows where an ❌ is present, the bundle has no authorizing data, and so an entry in mAuthBundles MUST NOT be present.

BundleType BundleVariant mValuePoolDeltas mEffectBundles mAuthBundles Defining ZIP Bundle kind
0 0 ✅ ✅ ✅ This ZIP Transparent
1 0 ✅ ✅ ❌ This ZIP Coinbase
2 0 ✅ ✅ ✅ This ZIP Sapling
3 0 ✅ ✅ ✅ This ZIP Orchard
4 0 ✅ ✅ ✅ This ZIP Ironwood
5 0 ✅ ❌ ❌ ZIP 2002 Transaction fee
6 0 ✅ ❌ ❌ ZIP 233 ZIP 233 NSM field

Additional bundle types or variants MAY be added to this registry via modifications to this ZIP specified in other ZIPs. Such modifications MUST specify all of the information required by the Bundle Type Registration section above.

Potential Future Bundle Types

Click to show/hide

This subsection is non-normative. The following bundle kinds illustrate possible future extensions; they do not register or activate any (bundleType, bundleVariant) pair. Where a bundle type is given, the kind is a new variant of that existing type and only its variant identifier is unassigned. Those proposed by a ZIP name it; the rest illustrate how potential future upgrades might affect the bundle registry:

BundleType BundleVariant mValuePoolDeltas mEffectBundles mAuthBundles Defining ZIP Bundle kind
2 1 (provisional) ✅ ✅ ✅ ZIP 231 Sapling-post-ZIP 231
3 1 (provisional) ✅ ✅ ✅ ZIP 231 Orchard post-ZIP 231
3 2 (provisional) ✅ ✅ ✅ ZIP 226 OrchardZSA
4 1 (provisional) ✅ ✅ ✅ ZIP 231 Ironwood post-ZIP 231
0 ❌ ✅ ✅ ZIP 270 Key rotation
0 ✅ ✅ ✅ TBD Lockbox disbursement
0 ❌ ✅ ❌ ZIP 231 Memos
0 ✅ ✅ ✅ ZIP 227 ZSA Issuance
0 ✅ ✅ ✅ TZEs
0 ✅ ✅ ✅ Pool that only has a long-term storage protocol (PQ, very simple thus insulated from counterfeiting fears, can be used for payments but higher latency for that purpose)
0 ✅ ✅ ✅ Tachyon
0 ✅ ✅ ❌ Staking
0 ✅ ✅ ✅ Unstaking (if it can't be combined with the Staking bundle)
0 ✅ ✅ ✅ Post-quantum fast payment protocol

Transaction Format

Bytes Name Data Type Description
Common Transaction Fields
4 header uint32

Contains:

  • fOverwintered flag (bit 31, always set)
  • version (bits 30 .. 0) – transaction version.
4 nVersionGroupId uint32 Version group ID (nonzero).
4 nConsensusBranchId uint32 Consensus branch ID (nonzero).
4 lock_time uint32 Unix-epoch UTC time or block height, encoded as in Bitcoin.
4 nExpiryHeight uint32 A block height in the range {1 .. 499999999} after which the transaction will expire, or 0 to disable expiry. 16
Transaction transparent value pool balance map
varies nValuePoolDeltas compactSize Number of entries in the mValuePoolDeltas map.
varies mValuePoolDeltas ValuePoolDelta[nValuePoolDeltas] A map describing the change to the transparent value pool produced by each bundle. Only bundles that produces changes to the transparent value balance will have corresponding entries in this map. For bundles that have no data except for a value, such as the ZIP 233 amount, no additional bundle data will be present in the Bundles section.
Bundles
varies nEffectBundles compactSize Number of bundles in the transaction that have per-bundle data.
varies mEffectBundles BundleData[nEffectBundles] A map from bundle identifier to the effecting data of a bundle.
varies nAuthBundles compactSize Number of bundles in the transaction that have per-bundle data.
varies mAuthBundles BundleData[nAuthBundles] A map from bundle identifier to the authorizing data of a bundle.

mValuePoolDeltas, mEffectBundles, and mAuthBundles are interpreted as maps keyed by bundleType. Lookups in mValuePoolDeltas are denoted with the syntax \(\mathsf{mValuePoolDeltas}[\mathsf{BundleType}]\kern-0.03em\textsf{.}\) A lookup for a key that is not present yields 0.

Encoding constraints on these maps (uniqueness, ordering, and cross-map consistency) are specified in Parsing Rules.

Rationale for non-extensible Common Transaction Fields

Click to show/hide

A transaction contains two kinds of information:

  • Changes enacted on global chain state. These belong in effecting bundles, including changes that move no value (such as the potential key rotation bundle in ZIP 270). Together with the value pool delta and authorizing data maps, these provide extensibility for the kinds of future changes currently envisaged.
  • Constraints on when the state change may be enacted. Pool-specific constraints are encoded within the corresponding effecting or authorizing bundles, while pool-agnostic constraints are encoded within the Common Transaction Fields.

There are no current proposals for pool-agnostic constraints that would require extensible Common Transaction Fields. Making them extensible without a concrete use would also require choosing commitment rules for fields whose semantics are not yet known. The Common Transaction Fields are therefore kept fixed rather than adding speculative flexibility. If future ZIPs require additions or modifications to the Common Transaction Fields, a new transaction version can introduce them while retaining compatibility with this ZIP's bundle registry (by explicitly importing those bundle definitions into its bundle registry).

ValuePoolDelta

Bytes Name Data Type Description
varies bundleType compactSize An encoding of the bundle type identifier.
varies bundleVariant compactSize An encoding of the bundle variant identifier.
8 value nonzero int64 The net change to the transparent transaction value pool, produced by the bundle with this bundle type identifier, in zatoshis. This value MUST be nonzero; if a ValuePoolDelta record would have zero value, it MUST be elided from the encoding of mValuePoolDeltas instead.

The values of all entries in mValuePoolDeltas are required to sum to zero; this balance rule is specified in Cross-bundle and chain-context rules.

Rationale for ValuePoolDelta

Click to show/hide

A previous version of ValuePoolDelta supported representing different asset kinds via an assetUuid. This was removed because it is unnecessary; any future ZIP proposing support for non-ZEC assets could instead propose a new bundle type with a non-ZEC asset value map in its effecting data, and consensus rules defining how to interpret and balance that map. This provides equivalent extensibility without adding fields to every value pool delta entry or requiring all transaction parsers to understand asset identifiers.

BundleData

Bytes Name Data Type Description
varies bundleType compactSize An encoding of the bundle type identifier.
varies bundleVariant compactSize An encoding of the bundle variant identifier.
varies nBundleDataLen compactSize The length of the vBundleData byte array.
varies vBundleData byte[nBundleDataLen] The effecting or authorizing data for the bundle, dependent upon whether the BundleData occurs in mEffectBundles or mAuthBundles.

Parsing Rules

The rules in this section are requirements on the byte encoding of a v7 transaction. A byte stream that violates any of these rules is not a well-formed v7 transaction and MUST be rejected by any parser, regardless of which bundle types the parser understands. Enforcement of these rules is what makes it safe for a wallet to parse, identify, and compute the transaction identifier for a transaction containing bundle types that the wallet does not itself implement.

  • Each of mValuePoolDeltas, mEffectBundles, and mAuthBundles MUST contain at most one entry per bundleType, and the entries MUST be encoded in strictly increasing bundleType order.
  • Every ValuePoolDelta record MUST have a nonzero value field. A ValuePoolDelta record that would have value = 0 MUST be elided from the encoding of mValuePoolDeltas.
  • For each bundleType that appears in any of mValuePoolDeltas, mEffectBundles, or mAuthBundles, all entries for that bundleType across all three maps MUST encode the same bundleVariant. (Together with the uniqueness rule above, this ensures that a transaction uses at most one variant of any given bundle type.)
  • For each bundleType that appears in mAuthBundles, a corresponding entry with the same bundleVariant MUST exist in mEffectBundles.

A wallet that successfully parses a v7 transaction under these rules is guaranteed to be able to compute the transaction identifier (given, for each (bundleType, bundleVariant) pair in mEffectBundles it does not understand, the corresponding 32-byte bundle_effects_digest value as described in Implications for Wallets), and to enumerate the transparent value flows of the transaction at the granularity of bundle types.

Let CoinbaseBundleId, SaplingBundleId, OrchardBundleId, IronwoodBundleId, and FeeBundleId be the identifiers of the coinbase, Sapling, Orchard, Ironwood, and fee bundles, respectively. In v7 transactions, \(\mathsf{CoinbaseBundleId} = 1\kern-0.03em\textsf{,}\) \(\mathsf{SaplingBundleId} = 2\kern-0.03em\textsf{,}\) \(\mathsf{OrchardBundleId} = 3\kern-0.03em\textsf{,}\) \(\mathsf{IronwoodBundleId} = 4\kern-0.03em\textsf{,}\) and \(\mathsf{FeeBundleId} = 5\) as defined in the table above.

Shielded balancing values

The logical Sapling, Orchard, and Ironwood balancing values are signed integers measured in zatoshis, as defined in the 'Balance and Binding Signature' sections of the protocol specification. 8 9 They are obtained from the v7 encoding as follows:

\(\begin{aligned} \mathsf{v}^{\textit{SaplingPoolBalance}} &= \mathsf{mValuePoolDeltas}[\mathsf{SaplingBundleId}] \\ \mathsf{v}^{\textit{OrchardPoolBalance}} &= \mathsf{mValuePoolDeltas}[\mathsf{OrchardBundleId}] \\ \mathsf{v}^{\textit{IronwoodPoolBalance}} &= \mathsf{mValuePoolDeltas}[\mathsf{IronwoodBundleId}] \end{aligned}\)

Each balancing value has the sign convention defined for its pool: a positive value takes net value from the corresponding chain value pool and adds it to the transparent transaction value pool; a negative value does the reverse.

Coinbase accounting values

For a v7 coinbase transaction, the transparent outputs used in the total output value definition in § 7.1.2 'Transaction Consensus Rules' are the entries in tx_out of its transparent bundle, or the empty sequence if that bundle is absent. 11 The shielded balancing values in that definition are obtained as specified above. The coinbase bundle's blockSubsidy and lockboxValue fields equal the protocol-defined block subsidy and \(\mathsf{totalDeferredOutput}(\mathsf{height})\kern-0.03em\textsf{,}\) respectively, as required by the Cross-bundle and chain-context rules.

Transaction inputs and outputs

For variant 0 of the corresponding bundle types, the logical counts and flags used in the protocol specification are obtained from the v7 effecting data as follows:

  • \(\mathtt{tx\_in\_count}\) and \(\mathtt{tx\_out\_count}\) are the transparent bundle's tx_in_count and tx_out_count fields.
  • \(\mathtt{nSpendsSapling}\) and \(\mathtt{nOutputsSapling}\) are the Sapling bundle's nSpendsSapling and nOutputsSapling fields.
  • \(\mathtt{nActionsOrchard}\) and \(\mathtt{nActionsIronwood}\) are the nActionsOrchard field of the Orchard and Ironwood bundles, respectively.
  • \(\mathtt{enableSpendsOrchard}\) and \(\mathtt{enableOutputsOrchard}\) are the enableSpends and enableOutputs bits of the Orchard bundle's flagsOrchard field. \(\mathtt{enableSpendsIronwood}\) and \(\mathtt{enableOutputsIronwood}\) are the corresponding bits of the Ironwood bundle's flagsOrchard field.

Counts are nonnegative integers and flags are bits. If a bundle is absent, its counts and flags are zero.

Changes to the Protocol Specification

Consensus Rules

This ZIP requires the following modifications to the consensus rules in the Zcash Protocol Specification. These rules are additional to the parsing rules above; a transaction that satisfies the parsing rules but violates any of these consensus rules is well-formed but invalid.

Bundle availability

For every (bundleType, bundleVariant) pair appearing in any of mValuePoolDeltas, mEffectBundles, or mAuthBundles, a full validator MUST verify that the pair is registered for v7 and activated for the consensus epoch of the block containing the transaction. A full validator MUST reject a transaction containing an unregistered or unactivated pair. Registration alone does not activate a bundle type or variant.

These consensus checks do not prevent a wallet from parsing an unsupported bundle type or variant opaquely under Parsing Rules.

Bundle-local rules

The following rules constrain the contents of individual bundles. Full validators MUST enforce every applicable rule. A wallet only needs to enforce a given rule in this subsection if it understands the bundle type and variant that the rule applies to.

  • A bundle type MUST NOT appear in any map for which the corresponding column of the v7 Transaction Bundle Type Registry is marked ❌, and MUST NOT appear in any map at all if its row in the registry is marked as Reserved.
  • Each entry in mValuePoolDeltas for variant 0 of the transparent, coinbase, Sapling, Orchard, or Ironwood bundle MUST have a corresponding entry in mEffectBundles.
  • If a transparent effecting bundle has tx_in_count > 0, a corresponding entry in mAuthBundles MUST be present.
  • For each TransparentInputAuth whose sighashInfo specifies sighash variant 0, the hash_type byte of every nonempty signature supplied to OP_CHECKSIG, OP_CHECKSIGVERIFY, OP_CHECKMULTISIG, or OP_CHECKMULTISIGVERIFY when validating that input MUST be SIGHASH_ALL (0x01).
  • Every Sapling, Orchard, or Ironwood effecting bundle MUST have a corresponding entry in mAuthBundles.
  • A coinbase transaction MUST NOT spend any transparent output. If a transparent bundle is present in a coinbase transaction, its effecting data MUST have tx_in_count = 0.
  • For coinbase transactions, the nSpendsSapling field of the Sapling bundle's effecting data MUST be 0.
  • For coinbase transactions, the enableSpends bit of the flagsOrchard field of every Orchard protocol bundle MUST be 0.
  • In an Orchard bundle, the enableCrossAddress bit of flagsOrchard MUST be 0; that is, transfers into the Orchard pool are restricted to the protocol-level address of the action's spend. 27 The bit is unrestricted in an Ironwood bundle.
Cross-bundle and chain-context rules

The following rules relate the contents of a bundle to the other bundles of its transaction, or to the block that contains it. They MUST be enforced by full validators.

  • For coinbase transactions, the value of \(\mathsf{mValuePoolDeltas}[\mathsf{FeeBundleId}]\) MUST be nonnegative. This represents the total transaction fees collected from all other transactions in the block.
  • For non-coinbase transactions, the value of \(\mathsf{mValuePoolDeltas}[\mathsf{FeeBundleId}]\) MUST be nonpositive. This represents the transaction fee paid by the transaction (expressed as a negative value, since it is removed from the transparent transaction value pool).
  • The fees collected by the coinbase transaction MUST equal the sum of the fees paid by all other transactions in the block, regardless of their transaction formats. For each non-coinbase transaction, its fee is:
    • for a v7 transaction, the negation of \(\mathsf{mValuePoolDeltas}[\mathsf{FeeBundleId}]\kern-0.03em\textsf{;}\)
    • for a pre-v7 transaction, the implicit fee defined in § 3.4 'Transactions and Treestates'. 5

    For a v7 coinbase transaction, its fee bundle value MUST equal this sum. In a block containing only v7 transactions, this is equivalent to requiring the sum of fee bundle values to equal zero.

  • Exactly one transaction in a block MUST be a coinbase transaction, and it MUST be the first transaction in the block.
  • The blockHeight field of the coinbase bundle's effecting data MUST equal the height of the block containing the transaction.
  • The blockSubsidy field of the coinbase bundle's effecting data MUST equal the block subsidy for that block, as defined in § 7.8 'Block Subsidy and Founders' Reward'. 14
  • The lockboxValue field of the coinbase bundle's effecting data MUST equal the total value that the funding streams for that block deposit into the deferred pool, as defined in § 7.10 'Payment of Funding Streams, Deferred Lockbox, and Lockbox Disbursement'. 15
  • The value of \(\mathsf{mValuePoolDeltas}[\mathsf{CoinbaseBundleId}]\) MUST equal the block subsidy less the lockbox deposit and \(\mathsf{NSMFeeContribution}(\mathsf{height})\) for the block containing the transaction.
    \(\mathsf{mValuePoolDeltas}[\mathsf{CoinbaseBundleId}] = \mathsf{blockSubsidy} - \mathsf{lockboxValue} - \mathsf{NSMFeeContribution}(\mathsf{height})\)

    Note that the coinbase value pool delta can be negative.

  • For every transaction, the sum of all value pool delta values MUST equal 0.
    \(\sum_{\mathsf{d} \in \mathsf{mValuePoolDeltas}} \mathsf{d.value} = 0\)

    For v7 transactions, this rule replaces the remaining-value treatment of the transparent transaction value pool in § 3.4 'Transactions and Treestates', including the implicit transaction fee. 5 It does not change the balance or implicit-fee rules for pre-v7 transactions.

In § 7.1.2 'Transaction Consensus Rules', 11 change:

[NU6.3 onward] If \(\mathsf{effectiveVersion} \geq 6\) then this rule MUST hold: \(\mathtt{tx\_in\_count} > 0\) or \(\mathtt{nSpendsSapling} > 0\) or ( \(\mathtt{nActionsOrchard} > 0\) and \(\mathtt{enableSpendsOrchard} = 1\kern-0.15em\) ) or ( \(\mathtt{nActionsIronwood} > 0\) and \(\mathtt{enableSpendsIronwood} = 1\kern-0.15em\) ).

[NU6.3 onward] If \(\mathsf{effectiveVersion} \geq 6\) then this rule MUST hold: \(\mathtt{tx\_out\_count} > 0\) or \(\mathtt{nOutputsSapling} > 0\) or ( \(\mathtt{nActionsOrchard} > 0\) and \(\mathtt{enableOutputsOrchard} = 1\kern-0.15em\) ) or ( \(\mathtt{nActionsIronwood} > 0\) and \(\mathtt{enableOutputsIronwood} = 1\kern-0.15em\) ).

to:

[NU6.3 onward] If \(\mathsf{effectiveVersion} \geq 6\kern-0.03em\textsf{,}\) at least one of these input-side conditions MUST be satisfied:

  • \(\mathsf{effectiveVersion} \geq 7\) and mEffectBundles contains an entry with bundleType = CoinbaseBundleId.
  • \(\mathtt{tx\_in\_count} > 0\kern-0.03em\textsf{.}\)
  • \(\mathtt{nSpendsSapling} > 0\kern-0.03em\textsf{.}\)
  • \(\mathtt{nActionsOrchard} > 0\) and \(\mathtt{enableSpendsOrchard} = 1\kern-0.03em\textsf{.}\)
  • \(\mathtt{nActionsIronwood} > 0\) and \(\mathtt{enableSpendsIronwood} = 1\kern-0.03em\textsf{.}\)

[NU6.3 onward] If \(\mathsf{effectiveVersion} \geq 6\kern-0.03em\textsf{,}\) at least one of these output-side conditions MUST be satisfied:

  • \(\mathtt{tx\_out\_count} > 0\kern-0.03em\textsf{.}\)
  • \(\mathtt{nOutputsSapling} > 0\kern-0.03em\textsf{.}\)
  • \(\mathtt{nActionsOrchard} > 0\) and \(\mathtt{enableOutputsOrchard} = 1\kern-0.03em\textsf{.}\)
  • \(\mathtt{nActionsIronwood} > 0\) and \(\mathtt{enableOutputsIronwood} = 1\kern-0.03em\textsf{.}\)
  • \(\mathsf{zip233\_amount} > 0\kern-0.03em\textsf{,}\) as defined in ZIP 233. 20

Signature hash references

In § 4.10 'SIGHASH Transaction Hashing', 12 change:

The means of authorization differs between transparent inputs, inputs to Sprout JoinSplit transfers, and Sapling Spend transfers or Orchard Action transfers, but for a given transaction version the same SIGHASH transaction hash algorithm is used.

to:

The means of authorization differs between transparent inputs, inputs to Sprout JoinSplit transfers, and Sapling Spend transfers or Orchard Action transfers. For a given pre-v7 transaction version the same SIGHASH transaction hash algorithm is used. For v7 transactions, the algorithm is selected for each signer as specified in ZIP 248, 'Sighash Variants'.

In the same section, after:

[NU6.3 onward] The SIGHASH algorithm used for version 6 transactions is defined in ZIP 229.

add:

The SIGHASH algorithms used for v7 transactions are defined in ZIP 248.

In § 4.13 'Balance and Binding Signature (Sapling)', 8 change:

Let \(\mathsf{SigHash}\) be the SIGHASH transaction hash for the appropriate transaction version, not associated with an input, using the SIGHASH type \(\mathsf{SIGHASH\_ALL}\kern-0.03em\textsf{.}\) This is defined in ZIP 243 for a version 4 transaction, or in ZIP 244 for a version 5 transaction, or in ZIP 229 for a version 6 transaction.

to:

For a pre-v7 transaction, let \(\mathsf{SigHash}\) be the SIGHASH transaction hash for the appropriate transaction version, not associated with an input, using the SIGHASH type \(\mathsf{SIGHASH\_ALL}\kern-0.03em\textsf{.}\) This is defined in ZIP 243 for a version 4 transaction, or in ZIP 244 for a version 5 transaction, or in ZIP 229 for a version 6 transaction.

For a v7 transaction, let \(\mathsf{SigHash}\) be the digest selected by the binding signature's sighashInfo, as specified in ZIP 248, 'Sapling Sighash Algorithms'.

In § 4.14 'Balance and Binding Signature (Orchard)', 9 change:

Let \(\mathsf{SigHash}\) be the SIGHASH transaction hash for the appropriate transaction version, not associated with an input, using the SIGHASH type \(\mathsf{SIGHASH\_ALL}\kern-0.03em\textsf{.}\) This is defined in ZIP 244 for a version 5 transaction, or in ZIP 229 for a version 6 transaction.

to:

For a pre-v7 transaction, let \(\mathsf{SigHash}\) be the SIGHASH transaction hash for the appropriate transaction version, not associated with an input, using the SIGHASH type \(\mathsf{SIGHASH\_ALL}\kern-0.03em\textsf{.}\) This is defined in ZIP 244 for a version 5 transaction, or in ZIP 229 for a version 6 transaction.

For a v7 transaction, let \(\mathsf{SigHash}\) be the digest selected by the sighashInfo of the binding signature for this bundle, as specified in ZIP 248, 'Orchard Protocol Sighash Algorithms'.

In § 4.15 'Spend Authorization Signature (Sapling and Orchard)', 13 change:

Let \(\mathsf{SigHash}\) be the SIGHASH transaction hash as defined in ZIP 243 or as defined in ZIP 244 modified by ZIP 225, not associated with an input, using the SIGHASH type \(\mathsf{SIGHASH\_ALL}\kern-0.03em\textsf{.}\)

to:

For a pre-v7 transaction, let \(\mathsf{SigHash}\) be the SIGHASH transaction hash as defined in ZIP 243 or as defined in ZIP 244 modified by ZIP 225, not associated with an input, using the SIGHASH type \(\mathsf{SIGHASH\_ALL}\kern-0.03em\textsf{.}\)

For a v7 transaction, let \(\mathsf{SigHash}\) be the digest selected by this spend authorization signature's sighashInfo, as specified in ZIP 248, 'Sapling Sighash Algorithms' for Sapling signatures or ZIP 248, 'Orchard Protocol Sighash Algorithms' for Orchard and Ironwood signatures.

Coinbase identification and metadata

In § 3.11 'Coinbase Transactions', 6 change:

A transaction that has a single transparent input with a null prevout field, is called a coinbase transaction.

to:

A pre-v7 transaction that has a single transparent input with a null prevout field is called a coinbase transaction. A v7 transaction is a coinbase transaction if and only if its mEffectBundles map contains an entry with bundleType = CoinbaseBundleId.

In § 7.1.2 'Transaction Consensus Rules', 11 change the paragraph starting with:

A coinbase transaction for a block at block height greater than 0

to instead start with:

A pre-v7 coinbase transaction for a block at block height greater than 0

In the same section, change:

A coinbase transaction script MUST have length in \(\{2 .. 100\}\) bytes.

to:

A pre-v7 coinbase transaction script MUST have length in \(\{2 .. 100\}\) bytes.

A v7 coinbase transaction has no coinbase script. Its block height and miner-chosen data are encoded in the coinbase bundle.

Shielded balance encoding

In § 4.13 'Balance and Binding Signature (Sapling)', 8 change:

\(\mathsf{v}^{\textit{SaplingPoolBalance}}\) is encoded in a transaction as the field valueBalanceSapling. For a v4 transaction, \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) is always explicitly encoded. For v5, \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) is implicitly zero if the transaction has no Spend descriptions or Output descriptions. Transaction fields are described in § 7.1 'Transaction Encoding and Consensus'.

to:

For a pre-v7 transaction, \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) is encoded in the transaction as the field valueBalanceSapling. For a v4 transaction, \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) is always explicitly encoded. For v5, \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) is implicitly zero if the transaction has no Spend descriptions or Output descriptions. Transaction fields are described in § 7.1 'Transaction Encoding and Consensus'.

For a v7 transaction, \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) is obtained as specified in ZIP 248, 'Shielded balancing values'.

In § 4.14 'Balance and Binding Signature (Orchard)', 9 using \(\textit{pool}\) as defined there, change:

\(\mathsf{v}^{\textit{poolBalance}}\) is encoded in a transaction as the field valueBalanceOrchard/Ironwood. If a transaction has no Action descriptions for \(\textit{pool}\kern-0.03em\textsf{,}\) \(\mathsf{v}^{\textit{poolBalance}}\) is implicitly zero. Transaction fields are described in § 7.1 'Transaction Encoding and Consensus'.

to:

For a pre-v7 transaction, \(\mathsf{v}^{\textit{poolBalance}}\) is encoded in the transaction as the field valueBalanceOrchard/Ironwood. If a pre-v7 transaction has no Action descriptions for \(\textit{pool}\kern-0.03em\textsf{,}\) \(\mathsf{v}^{\textit{poolBalance}}\) is implicitly zero. Transaction fields are described in § 7.1 'Transaction Encoding and Consensus'.

For a v7 transaction, \(\mathsf{v}^{\textit{poolBalance}}\) is obtained as specified in ZIP 248, 'Shielded balancing values'.

Shielded balance ranges

In § 7.1.2 'Transaction Consensus Rules', 11 change:

  • [Sapling onward] valueBalanceSapling, if it exists, MUST be in the range \(\{-\mathsf{MAX\_MONEY} \,..\, \mathsf{MAX\_MONEY}\}\kern-0.03em\textsf{.}\)
  • [NU5 onward] valueBalanceOrchard, if it exists, MUST be in the range \(\{-\mathsf{MAX\_MONEY} \,..\, \mathsf{MAX\_MONEY}\}\kern-0.03em\textsf{.}\)
  • [NU6.3 onward] valueBalanceIronwood, if it exists, MUST be in the range \(\{-\mathsf{MAX\_MONEY} \,..\, \mathsf{MAX\_MONEY}\}\kern-0.03em\textsf{.}\)
  • [NU6.3 onward] valueBalanceOrchard, if it exists, MUST be nonnegative.

to:

  • [Sapling onward] \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) MUST be in the range \(\{-\mathsf{MAX\_MONEY} \,..\, \mathsf{MAX\_MONEY}\}\kern-0.03em\textsf{.}\)
  • [NU5 onward] \(\mathsf{v}^{\textit{OrchardPoolBalance}}\) MUST be in the range \(\{-\mathsf{MAX\_MONEY} \,..\, \mathsf{MAX\_MONEY}\}\kern-0.03em\textsf{.}\)
  • [NU6.3 onward] \(\mathsf{v}^{\textit{IronwoodPoolBalance}}\) MUST be in the range \(\{-\mathsf{MAX\_MONEY} \,..\, \mathsf{MAX\_MONEY}\}\kern-0.03em\textsf{.}\)
  • [NU6.3 onward] \(\mathsf{v}^{\textit{OrchardPoolBalance}}\) MUST be nonnegative.

Chain value pool balance definitions

In § 4.17 'Chain Value Pool Balances', 10 change:

As defined in ZIP 209, the Sapling chain value pool balance for a given block chain is the negation of the sum of all valueBalanceSapling values for transactions in the chain.

to:

As defined in ZIP 209, the Sapling chain value pool balance for a given block chain is the negation of the sum of all \(\mathsf{v}^{\textit{SaplingPoolBalance}}\) values for transactions in the chain.

In the same section, change:

Similarly to the Sapling chain value pool balance defined in ZIP 209, the Orchard chain value pool balance for a given block chain is the negation of the sum of all valueBalanceOrchard field values for transactions in the chain.

to:

Similarly to the Sapling chain value pool balance defined in ZIP 209, the Orchard chain value pool balance for a given block chain is the negation of the sum of all \(\mathsf{v}^{\textit{OrchardPoolBalance}}\) values for transactions in the chain.

In the same section, change:

The Ironwood chain value pool balance for a given block chain is the negation of the sum of all valueBalanceIronwood field values for transactions in the block chain.

to:

The Ironwood chain value pool balance for a given block chain is the negation of the sum of all \(\mathsf{v}^{\textit{IronwoodPoolBalance}}\) values for transactions in the block chain.

Sighash Variants

This ZIP introduces sighash algorithm variants. Where previously each transaction version had a single associated sighash algorithm, going forward it is possible for signers to use any sighash algorithm within the closed set specified for a given transaction version (and made available in consensus via network upgrades).

The sighash variant is encoded as a single byte alongside any associated data that the sighash algorithm variant requires (for deterministically computing the digest):

sighashInfo = [sighashVariant] || associatedData

where associatedData is specific to the bundle it appears in.

The preimage of each signature digest MUST begin with the single-byte sighashVariant, to domain-separate the sighash algorithm variants.

Each bundle type defines the sighash algorithm variants available to its signers, the associatedData that each variant requires, and the digest that a signature using it commits to. Those definitions are given for the bundle types registered by this ZIP in Bundle Definitions.

Variant 0 is the "commit to all effecting data" sighash algorithm. Other variants can define different commitments, including partial commitments across bundles, within a given transaction version. Consensus rules choose the digest algorithm for each signer based on sighashVariant.

Sighash variant information is present alongside each signature in the authorizing data of each bundle.

Digest Algorithms

All digests are personalized BLAKE2b-256 hashes. In cases where no elements are available for hashing (for example, if there are no transparent transaction inputs), a personalized hash of the empty byte array will be used. The personalization string therefore provides domain separation for the hashes of even empty data fields.

The notation BLAKE2b-256(personalization_string, []) is used to refer to hashes constructed in this manner.

TxId Digest

A new transaction digest algorithm is defined that constructs the identifier for a v7 transaction from a tree of hashes. The overall structure of the hash is as follows:

txid_digest
├── header_digest
├── value_pool_deltas_digest
└── effects_bundles_digest
    ├─ (bundle_type_id || bundle_variant || transparent_effects_digest)
    ├─ (bundle_type_id || bundle_variant || coinbase_effects_digest)
    ├─ (bundle_type_id || bundle_variant || sapling_effects_digest)
    │   ├── sapling_spends_digest
    │   │   ├── sapling_spends_compact_digest
    │   │   └── sapling_spends_noncompact_digest
    │   └── sapling_outputs_digest
    │       ├── sapling_outputs_compact_digest
    │       ├── sapling_outputs_memos_digest
    │       └── sapling_outputs_noncompact_digest
    ├─ (bundle_type_id || bundle_variant || orchard_effects_digest)
    │   ├── orchard_actions_compact_digest
    │   ├── orchard_actions_memos_digest
    │   └── orchard_actions_noncompact_digest
    ├─ (bundle_type_id || bundle_variant || ironwood_effects_digest)
    │   ├── ironwood_actions_compact_digest
    │   ├── ironwood_actions_memos_digest
    │   └── ironwood_actions_noncompact_digest
    └─ (bundle_type_id || bundle_variant || unknown_bundle_effects_digest) ...

Each node written as snake_case in this tree is a BLAKE2b-256 hash of its children, initialized with a personalization string specific to that branch of the tree. Nodes that are not themselves digests are written in camelCase. In the specification below, nodes of the tree are presented in depth-first order.

txid_digest

A BLAKE2b-256 hash of the following values:

T.1: header_digest             (32-byte hash output)
T.2: value_pool_deltas_digest  (32-byte hash output)
T.3: effects_bundles_digest    (32-byte hash output)

The personalization field of this hash is set to:

"ZcashTxHash_" || CONSENSUS_BRANCH_ID

ZcashTxHash_ has 1 underscore character.

As in ZIP 244 23, CONSENSUS_BRANCH_ID is the 4-byte little-endian encoding of the consensus branch ID for the epoch of the block containing the transaction.

T.1: header_digest

A BLAKE2b-256 hash of the following values:

T.1a: version             (4-byte little-endian version identifier including overwintered flag)
T.1b: nVersionGroupId    (4-byte little-endian version group identifier)
T.1c: nConsensusBranchId (4-byte little-endian consensus branch id)
T.1d: lock_time           (4-byte little-endian nLockTime value)
T.1e: nExpiryHeight       (4-byte little-endian block height)

The personalization field of this hash is set to:

"ZTxIdHeadersHash"
T.2: value_pool_deltas_digest

A BLAKE2b-256 hash of the concatenated encodings of all entries in mValuePoolDeltas, in transaction order. For each entry, the following values are concatenated:

T.2a: bundleType    (compactSize encoding)
T.2b: bundleVariant (compactSize encoding)
T.2c: value         (8-byte signed little-endian)

The personalization field of this hash is set to:

"ZTxIdVPDeltaHash"

In the case that the transaction has no value pool delta entries, value_pool_deltas_digest is:

BLAKE2b-256("ZTxIdVPDeltaHash", [])
T.3: effects_bundles_digest

A BLAKE2b-256 hash of the concatenated tagged bundle effect digests for all bundles present in mEffectBundles, in transaction order. For each bundle, the following values are concatenated:

T.3a: bundleType            (compactSize encoding)
T.3b: bundleVariant         (compactSize encoding)
T.3c: bundle_effects_digest (32-byte hash output)

where bundle_effects_digest is the root hash of the bundle's effecting data tree, as defined for each bundle type in Bundle Definitions.

The personalization field of this hash is set to:

"ZTxIdEffBnd_Hash" (1 underscore character)

In the case that the transaction has no effect bundles, effects_bundles_digest is:

BLAKE2b-256("ZTxIdEffBnd_Hash", [])
Rationale for Per-Bundle Effects Digests
Click to show/hide

Each effecting bundle contributes a fixed-size digest to this hash. A wallet can therefore use a supplied digest for an unsupported bundle without parsing its internal structure, while computing the other bundle digests itself. The bundleType and bundleVariant tags remain committed to alongside each digest, and the header and complete value pool delta map remain separate commitments in the transaction identifier. This permits bundle-specific hash trees, including the subtrees used in compact representations, without requiring every receiving wallet to understand every bundle's hash tree.

Variant 0 Signature Digest

A new per-input transaction digest algorithm is defined that constructs a hash that may be signed by a transaction creator to commit to the effects of the transaction. This follows closely the algorithm from ZIP 244 23.

The digest algorithm used for a given signature is determined by the sighashVariant from the signer's sighashInfo, as specified in the Sighash Variants section. For sighash variant 0 (the only variant currently defined for v7 transactions), the digest algorithm is as specified below. Future network upgrades may define additional sighash algorithm variants with divergent behavior.

All variant 0 signatures commit to the complete transaction effects, using the same commitment as the transaction identifier, and to the amounts and script public keys of all transparent inputs. These transaction-wide commitments are separate from the bundle-defined context of the signature being made:

signature_digest
├── sighashVariant
├── txid_digest
├── amounts_sig_digest
├── scriptpubkeys_sig_digest
├── bundleType
├── bundleVariant
└── signature_context
signature_digest

A BLAKE2b-256 hash of the following values:

S.1: sighashVariant            (1 byte, 0x00)
S.2: txid_digest               (32-byte hash output)
S.3: amounts_sig_digest        (32-byte hash output)
S.4: scriptpubkeys_sig_digest  (32-byte hash output)
S.5: bundleType                (compactSize encoding)
S.6: bundleVariant             (compactSize encoding)
S.7: signature_context         (bundle-defined byte string)

The personalization field of this hash is set to:

"ZcashSigHash_v7_" (2 underscore characters)

bundleType and bundleVariant identify the bundle containing the signature. signature_context is defined for that bundle type and variant in Bundle Definitions. It is the final field, with no additional length prefix.

Every signature uses the amounts_sig_digest and scriptpubkeys_sig_digest defined in Transparent Digests, independently of which bundle contains the signature.

Rationale for Variant 0 Commitments
Click to show/hide

The signature digest algorithms previously defined for Zcash have three distinct variants:

  • For v1 and v2 transactions, it followed the Bitcoin convention of using the "hash the transaction" transaction ID digest algorithm while including or omitting information as relevant for the transparent sighash kind.
  • For v3 and v4, a SegWit-style signature hash algorithm used a two-level hash: the outer digest was over commitments to the various different parts of the transaction, while the TxId was unaltered.
  • For v5 and v6, both the TxId and the sighash were tree commitments to the transaction data, with the sighash digest algorithm reusing as many of the inner commitments computed by the TxId digest as possible, but substituting in different digests where signature-relevant data was included or omitted.

All of these variants diverged from the TxId digest because of how the transparent sighash kinds carried over from Bitcoin were defined. Due to a combination of subtleties around the interpretation of the sighash kinds for transparent-only wallets being ported from Bitcoin, and the lack of equivalent information exposed by the shielded actions, the sighash kinds were not adapted to include equivalent logic on the shielded pools. Instead, they always acted as if the shielded components of a transaction were defined with SIGHASH_ALL. As a consequence, the sighash kinds are only effective in transparent-only transactions.

When transaction ID malleability was addressed for v5 transactions in ZIP 244 23, the TxId and sighash digest algorithms were defined such that if you were signing a transaction that contained no transparent information, you just signed the TxId. In addition to being more efficient (as TxIds are usually computed at parsing time and cached), it is clear that this has the property one expects for a signature that is committing to all of the effecting data in a transaction.

For this ZIP's variant 0 digest, we instead commit directly to the TxId in a wrapping digest; the additional signature-specific information that previously was committed in-situ with the effecting data is instead committed beside the TxId. This has the same overall binding property, while improving the efficiency for all shielded signatures as well as SIGHASH_ALL transparent signatures.

This simplicity and efficiency is only possible by dropping support for non SIGHASH_ALL transparent signatures from variant 0. This is justified for several reasons:

  • These transparent signatures can still be created on the network today with v5 or v6 transactions. There are no functionality changes to the transparent signing capabilities in transparent bundle variant 0.
  • The sighash variants introduced in this ZIP provide an equivalent mechanism that does not inherit the semantic baggage of the transparent sighash kinds. A future ZIP could define a sighash variant that provides equivalent functionality, while potentially also expanding it to compatible shielded logic, if demand for such functionality in v7 transactions appears.
    • One difference between the transparent sighash kinds and sighash variants is that a sighash variant is specified at a per-input level, whereas sighash kinds are specified at a per-signature level. The latter can be leveraged in P2SH scripts, albeit being tricky to reason about. However, this difference can be eliminated by either defining the future sighash variant to use the sighash kind bytes that remain embedded into scripts, or by leveraging the associatedData field to store any additional per-signature metadata necessary for the variant.
  • TODO collect data about observed usage of non SIGHASH_ALL sighash kinds.

The additional transaction-wide amount and script commitments preserve the hardware-wallet protections of ZIP 244. 23 The explicit fee defined in ZIP 2002 26 allows a signer to display the committed fee without reconstructing it from input amounts. However, in a transaction with inputs from multiple parties, the signer must also be able to identify which inputs belong to it and their values. Committing to every input's amount and script public key prevents a host from obtaining signatures in separate sessions using inconsistent descriptions of the other inputs, even when those descriptions have the same total input value. All signers commit to these digests, including shielded signers. Their positional correspondence with the transparent inputs binds them to the previous-output references already committed to by the transaction identifier; they need not be adjacent to those references in the hash tree.

Each spend signature's context includes the zero-based index of the input being signed within its bundle's effecting-data array. This binds the signature to that position, even when another input uses the same authorization key. The bundle type and variant distinguish indices belonging to different bundles. Shielded binding signatures have an empty context, distinct from every spend-signature context.

The index is encoded as a fixed two-byte unsigned little-endian integer. The Sapling spend and Orchard protocol action counts are already constrained by consensus to be less than \(2^{16}\kern-0.03em\textsf{.}\) 11 Each transparent input's effecting data occupies 40 bytes, so the 2,000,000-byte block size limit also bounds its index below \(2^{16}\kern-0.03em\textsf{.}\) 4 No additional count limit is needed.

The transaction identifier and the two aggregate input digests can each be computed once per transaction and reused for every signature. The aggregate input digests require the referenced UTXO data, but their computation does not require changing or recomputing the transaction identifier. Implementations can also clone a BLAKE2b state containing the common prefix before appending the signature context, and can reuse the completed digest for multiple signatures authorizing the same input.

BLAKE2b processes 128-byte blocks. With the currently defined one-byte bundle type and variant encodings, the prefix through bundleVariant is 99 bytes. A shielded spend signature has a two-byte context, giving a 101-byte preimage; a shielded binding signature's empty context gives a 99-byte preimage. Both fit in one block. For a transparent input with a script public key of \(L\) bytes, the preimage length is \(149 + \mathsf{CompactSizeLen}(L) + L\) bytes, where \(\mathsf{CompactSizeLen}(L)\) is the length in bytes of the CompactSize encoding of \(L\kern-0.03em\textsf{.}\) A 25-byte P2PKH script gives 175 bytes (47 bytes in the second block); a 23-byte P2SH script gives 173 bytes (45 bytes in the second block). The latter commits to the script public key, not the redeem script. The shared 99-byte prefix does not fill a block: the first block also contains the first 29 bytes of the input's prevout_hash. In general, each of these transparent digests therefore requires two compressions. Inputs spending outputs of the same previous transaction share the first block, allowing its non-final hash state to be reused. Longer scripts can require additional blocks. No transaction-wide input list or bundle effects need to be rehashed for each signature.

Authorizing Data Commitment

A transaction digest algorithm is defined that constructs a digest committing to the authorizing data of a transaction. The overall structure is:

auth_digest
└── auth_bundles_digest
    ├─ (bundle_type_id || bundle_variant || transparent_auth_digest)
    ├─ (bundle_type_id || bundle_variant || sapling_auth_digest)
    ├─ (bundle_type_id || bundle_variant || orchard_auth_digest)
    ├─ (bundle_type_id || bundle_variant || ironwood_auth_digest)
    └─ (bundle_type_id || bundle_variant || unknown_bundle_auth_digest) ...
auth_digest

A BLAKE2b-256 hash of the following value:

A.1: auth_bundles_digest (32-byte hash output)

The personalization field of this hash is set to:

"ZTxAuthHash_" || CONSENSUS_BRANCH_ID
A.1: auth_bundles_digest

A BLAKE2b-256 hash of the concatenated tagged bundle auth digests for all bundles present in mAuthBundles, in transaction order. For each bundle, the following values are concatenated:

A.1a: bundleType          (compactSize encoding)
A.1b: bundleVariant       (compactSize encoding)
A.1c: bundle_auth_digest  (32-byte hash output)

The personalization field of this hash is set to:

"ZTxAuthBnd__Hash" (2 underscore characters)

In the case that the transaction has no auth bundles, auth_bundles_digest is:

BLAKE2b-256("ZTxAuthBnd__Hash", [])

Implications for Wallets

Choice of transaction format when sending

When creating a transaction, a wallet SHOULD use the oldest transaction format that is valid at the height at which the transaction is expected to be mined, and that supports every protocol feature the transaction requires. A wallet SHOULD use the v7 transaction format only for transactions that require a feature that no older valid format supports.

Rationale for choice of transaction format

Click to show/hide

The oldest format that can express a transaction is the format that the largest number of receiving wallets can parse. A wallet that has not yet added support for parsing v7 transactions can still detect funds sent to it in a transaction that does not use v7 features.

Support for receiving funds in v7 transactions

Zcash wallets MUST support parsing v7 transactions by the time they are allowed on the network.

Because the v7 transaction format uses a type-length-value encoding for bundles, a wallet is not required to understand the internal encoding of every bundle in order to parse a transaction. However, a wallet that encounters a bundle with an unrecognized bundleType SHOULD alert the user that the transaction contains components it does not understand. A wallet that encounters a bundle with a recognized bundleType but unrecognized bundleVariant SHOULD alert the user that the transaction affects a pool the wallet is aware of, but in a way the wallet does not fully understand.

For each unsupported (bundleType, bundleVariant) pair in mEffectBundles, a wallet needs the corresponding 32-byte bundle_effects_digest value in order to compute the transaction identifier. This includes an unsupported variant of a recognized bundle type. For each such bundle, the wallet uses the supplied digest as T.3c, together with the bundleType and bundleVariant encoded in that transaction's mEffectBundles entry, in T.3: effects_bundles_digest. It computes the digests of supported bundles normally and includes all bundles in transaction order. The header and complete value pool delta map are hashed as specified in T.1 and T.2. Thus access to the unsupported bundles' digests enables the wallet to compute the transaction identifier without interpreting those bundles' internal payloads. How those digests are made available to the wallet is outside the scope of this ZIP.

The supplied digests act as commitments to subtrees that the wallet does not need to compute. If the resulting transaction identifier matches one obtained from a trusted source, this authenticates the effecting data the wallet understands, the header, and the value pool delta map. Without a transaction identifier obtained from a trusted source, computing the correct identifier instead depends on the supplied bundle digests being correct.

Recognizing a bundle type identifies the affected value pool or protocol component, but does not imply that the wallet understands or can operate under the semantics of an unsupported variant.

A wallet MUST NOT construct or sign a transaction containing a bundle type or variant that it does not fully understand.

Bundle Definitions

The sections above are independent of any particular bundle type. This section defines the bundle types that this ZIP registers: the encoding of their effecting and authorizing data, the sighash algorithm variants available to their signers, and their contributions to the digests defined in Digest Algorithms. A ZIP that registers a further bundle type defines the same things for it, as required by Bundle Type Registration. In particular, each bundle type and variant defines when its entries are present or omitted; the canonical omission rules below apply to the bundle kinds that specify them.

For the bundle types defined by this ZIP, the corresponding authorizing sequences take their lengths from the effecting data:

  • tx_in_auth has tx_in_count elements;
  • vSpendProofsSapling and vSpendAuthSigsSapling each have nSpendsSapling elements;
  • vOutputProofsSapling has nOutputsSapling elements;
  • in each Orchard protocol bundle, vSpendAuthSigsOrchard has nActionsOrchard elements.

Decoding a recognized vBundleData payload MUST consume exactly nBundleDataLen bytes; missing fields, truncated fields, or trailing bytes MUST cause rejection. Unsupported payloads are treated as opaque byte arrays of their declared lengths.

Transparent Bundle

The transparent bundle's value pool delta in mValuePoolDeltas represents the net value flowing from the transparent inputs to the transparent outputs.

An entry for this bundle in mEffectBundles MUST contain at least one transparent input or output. If both tx_in_count and tx_out_count would be zero, the effecting bundle MUST be omitted instead. An entry in mAuthBundles MUST NOT be present when tx_in_count = 0; the empty authorizing bundle is omitted.

A full validator MUST verify that the value pool delta for bundleType = 0 equals the total value of the transparent inputs minus the total value of the transparent outputs. (The input values are not encoded in the transaction itself; they are obtained from the UTXOs being spent.)

This rule applies to coinbase transactions unchanged. A coinbase transaction has no transparent inputs, so its transparent value pool delta is the negation of the total value of its transparent outputs; the value that those outputs consume is contributed to the transparent transaction value pool by the coinbase bundle and the fee bundle.

Transparent Effecting Data

The effecting data for the transparent bundle describes the transparent inputs being spent and the transparent outputs being created.

Bytes Name Data Type Description
varies tx_in_count compactSize Number of transparent inputs.
varies tx_in_effecting TransparentInputEffecting[tx_in_count] Effecting data for each transparent input.
varies tx_out_count compactSize Number of transparent outputs.
varies tx_out TransparentOutput[tx_out_count] Transparent outputs.
TransparentInputEffecting
Bytes Name Data Type Description
32 prevout_hash byte[32] The transaction ID of the output being spent.
4 prevout_index uint32 The index of the output being spent within that transaction.
4 nSequence uint32 Sequence number, encoded as in Bitcoin.
TransparentOutput
Bytes Name Data Type Description
8 value int64 The value of the output in zatoshi.
varies scriptPubKeyLen compactSize Length of the scriptPubKey.
scriptPubKeyLen scriptPubKey byte[scriptPubKeyLen] The script that must be satisfied to spend this output.
Transparent Authorizing Data

The authorizing data for the transparent bundle contains the scripts that authorize spending of the referenced transparent inputs.

Bytes Name Data Type Description
varies tx_in_auth TransparentInputAuth[tx_in_count] Authorizing data for each transparent input. The number of entries MUST equal tx_in_count from the effecting data.
TransparentInputAuth
Bytes Name Data Type Description
varies sighashInfo TransparentSighashInfo The sighash variant and associated information for this input, as defined in Transparent Sighash Information (``TransparentSighashInfo`)`_.
varies scriptSigLen compactSize Length of the scriptSig.
scriptSigLen scriptSig byte[scriptSigLen] The script satisfying the conditions of the referenced output's scriptPubKey.
Transparent Sighash Information (TransparentSighashInfo)
Bytes Name Data Type Description
varies sizeSighashInfo compactSize The size in bytes of sighashInfo.
sizeSighashInfo sighashInfo byte[sizeSighashInfo] The sighash variant and associated information, as defined in Sighash Variants.
Transparent Sighash Algorithms

For the transparent bundle at bundleVariant = 0, sighash variant 0 is the only variant defined, and its associatedData is the empty byte string. A signature made with it commits to the digest defined in Variant 0 Signature Digest, with bundleType = 0, bundleVariant = 0, and the signature_context defined in S.7: Transparent Signature Context.

Transparent Digests
T.3.0: transparent_effects_digest

In the case that transparent inputs or outputs are present, the transparent effects digest is a BLAKE2b-256 hash of the following values:

T.3.0a: prevouts_digest  (32-byte hash)
T.3.0b: sequence_digest  (32-byte hash)
T.3.0c: outputs_digest   (32-byte hash)

The personalization field of this hash is set to:

"ZTxIdTranspaHash"

If there are no transparent inputs or outputs, there is no transparent effecting bundle and no entry for it in effects_bundles_digest.

T.3.0a: prevouts_digest

A BLAKE2b-256 hash of the field encoding of all (prevout_hash, prevout_index) pairs from the transparent effecting data.

The personalization field of this hash is set to:

"ZTxIdPrevoutHash"

In the case that the transaction has transparent outputs but no transparent inputs, prevouts_digest is:

BLAKE2b-256("ZTxIdPrevoutHash", [])
T.3.0b: sequence_digest

A BLAKE2b-256 hash of the 32-bit little-endian representation of all nSequence field values from the transparent effecting data.

The personalization field of this hash is set to:

"ZTxIdSequencHash"

In the case that the transaction has transparent outputs but no transparent inputs, sequence_digest is:

BLAKE2b-256("ZTxIdSequencHash", [])
T.3.0c: outputs_digest

A BLAKE2b-256 hash of the concatenated field encodings of all transparent outputs. The field encoding of each output consists of the encoded output value (8-byte little endian) followed by the scriptPubKey byte array (with leading compactSize length).

The personalization field of this hash is set to:

"ZTxIdOutputsHash"

In the case that the transaction has transparent inputs but no transparent outputs, outputs_digest is:

BLAKE2b-256("ZTxIdOutputsHash", [])
S.3: amounts_sig_digest

A BLAKE2b-256 hash of the concatenation, in tx_in_effecting order, of the 8-byte signed little-endian representations of all value fields for the coins spent by the transparent inputs to the transaction.

The personalization field of this hash is set to:

"ZTxTrAmountsHash"

If there are no transparent inputs, including when the transparent bundle is absent, amounts_sig_digest is:

BLAKE2b-256("ZTxTrAmountsHash", [])
S.4: scriptpubkeys_sig_digest

A BLAKE2b-256 hash of the concatenation, in tx_in_effecting order, of the field encodings (each including a leading compactSize) of all scriptPubKey fields for the coins spent by the transparent inputs.

The personalization field of this hash is set to:

"ZTxTrScriptsHash"

If there are no transparent inputs, including when the transparent bundle is absent, scriptpubkeys_sig_digest is:

BLAKE2b-256("ZTxTrScriptsHash", [])
S.7: Transparent Signature Context

For variant 0 of the transparent bundle, signature_context is the concatenation of the following fields for the input being signed:

S.7.i:   prevout      (36 bytes: 32-byte hash + 4-byte index)
S.7.ii:  value        (8-byte signed little-endian)
S.7.iii: scriptPubKey (with compactSize length prefix)
S.7.iv:  nSequence    (4-byte unsigned little-endian)
S.7.v:   input_index  (2-byte unsigned little-endian)

input_index is the zero-based position of the input being signed in tx_in_effecting, in the range \(0 \leq \mathtt{input\_index} < \mathtt{tx\_in\_count}\kern-0.03em\textsf{.}\) It is not the prevout_index of the output being spent.

A.1.0: transparent_auth_digest

In the case that the transaction contains transparent inputs, this is a BLAKE2b-256 hash of the following concatenated values for each transparent input:

A.1.0a: TransparentSighashInfo (field encoding bytes)
A.1.0b: scriptSig              (field encoding bytes, with compactSize length prefix)

The field encoding of TransparentSighashInfo is defined in Transparent Sighash Information (``TransparentSighashInfo`)`_.

The personalization field of this hash is set to:

"ZTxAuthTransHash"

If there are no transparent inputs, there is no transparent authorizing bundle and no entry for it in auth_bundles_digest.

Coinbase Bundle

A v7 transaction is a coinbase transaction if and only if mEffectBundles contains an entry with bundleType = 1. The coinbase bundle replaces the otherwise-unspendable transparent input that identified a coinbase transaction in previous transaction versions, and carries the block height that that input was required to encode.

The block subsidy is the whole of the new issuance for the block, which consensus splits between the miner, the funding streams that pay to an address, and the funding streams that deposit into the deferred pool (the "lockbox") 25. Only the part that is not deposited into the lockbox is paid out by this transaction. The full fees collected from the other transactions in the block are contributed separately, as the value pool delta of the fee bundle. The coinbase bundle's value pool delta is the block subsidy less the lockbox deposit and the fee contribution removed from circulation under ZIP 235. 21 It can therefore be positive, zero, or negative. Together with the gross fee delta, it leaves the subsidy less the lockbox deposit plus \(\mathsf{MinerFees}(\mathsf{height})\) available to the output bundles.

The bundle's own effecting data carries blockSubsidy and lockboxValue, so that these amounts are recoverable from the transaction. The fee contribution is derived from the gross fee delta using ZIP 235's calculation.

The coinbase bundle has no authorizing data.

Coinbase Effecting Data
Bytes Name Data Type Description
4 blockHeight uint32 The height of the block in which the transaction is mined.
8 blockSubsidy uint64 The block subsidy for that block, in zatoshis.
8 lockboxValue uint64 The part of that block subsidy deposited into the lockbox, in zatoshis.
varies coinbaseDataLen compactSize Length of the coinbaseData byte array.
coinbaseDataLen coinbaseData byte[coinbaseDataLen] Data chosen by the miner. Consensus assigns no meaning to its contents.
  • blockHeight MUST be in the range {1 .. 499999999}.
  • lockboxValue MUST be in the range {0 .. blockSubsidy}.
  • coinbaseDataLen MUST be at most 94.
Coinbase Digests
T.3.1: coinbase_effects_digest

A BLAKE2b-256 hash of the following values:

T.3.1a: blockHeight   (4-byte little-endian block height)
T.3.1b: blockSubsidy  (8-byte unsigned little-endian)
T.3.1c: lockboxValue  (8-byte unsigned little-endian)
T.3.1d: coinbaseData  (byte array with leading ``compactSize`` length)

The personalization field of this hash is set to:

"ZTxIdCoinbasHash"

This digest is present only for coinbase transactions; a transaction that has no coinbase bundle contributes no entry for it to effects_bundles_digest.

Sapling Bundle

An entry for this bundle in mEffectBundles MUST contain at least one Sapling Spend or Output description. If both nSpendsSapling and nOutputsSapling would be zero, the bundle MUST be omitted instead.

Sapling Effecting Data

The effecting data for the Sapling bundle describes the Sapling spends and outputs. Unlike the v5 transaction format defined in ZIP 225 18, the value balance is not included here; it appears in mValuePoolDeltas instead.

Bytes Name Data Type Description
varies nSpendsSapling compactSize Number of Sapling Spend descriptions.
96 * nSpendsSapling vSpendsSapling SaplingSpendEffecting[nSpendsSapling] Effecting data for each Sapling Spend.
varies nOutputsSapling compactSize Number of Sapling Output descriptions.
756 * nOutputsSapling vOutputsSapling SaplingOutput[nOutputsSapling] Sapling Output descriptions.

The anchor is not part of the effecting data; it appears in Sapling Authorizing Data.

SaplingSpendEffecting
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 this Spend.
SaplingOutput

This is identical to OutputDescriptionV5 as defined in ZIP 225 18.

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 created by concatenation of the transmission key with the ephemeral secret key.
Sapling Authorizing Data

The authorizing data for the Sapling bundle contains the proofs and signatures that authorize the spends and validate the outputs.

Bytes Name Data Type Description
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] Encodings of the zk-SNARK proofs for each Sapling Spend.
varies vSpendAuthSigsSapling SaplingSignature[nSpendsSapling] Authorizing signatures for each Sapling Spend.
192 * nOutputsSapling vOutputProofsSapling byte[192 * nOutputsSapling] Encodings of the zk-SNARK proofs for each Sapling Output.
varies bindingSigSapling SaplingSignature A Sapling binding signature on the SIGHASH transaction hash.
  • The field anchorSapling is present if and only if \(\mathtt{nSpendsSapling} > 0\kern-0.03em\textsf{.}\) A Sapling bundle with outputs but no spends references no anchor.
  • The values of nSpendsSapling and nOutputsSapling are not re-encoded in the authorizing data; they are taken from the corresponding effecting data.
  • The field bindingSigSapling is present if and only if \(\mathtt{nSpendsSapling} + \mathtt{nOutputsSapling} > 0\kern-0.03em\textsf{.}\)
Sapling Signature (SaplingSignature)
Bytes Name Data Type Description
varies sizeSighashInfo compactSize The size in bytes of sighashInfo.
sizeSighashInfo sighashInfo byte[sizeSighashInfo] The sighash variant and associated information, as defined in Sighash Variants.
64 signature byte[64] An encoding of a RedJubjub signature, which may be either a spendAuthSig or bindingSig depending on context.

The 1:1 correspondences between Sapling authorizing-data elements and the elements of the corresponding effecting data are required by the parsing rules in Parsing Rules.

Sapling Sighash Algorithms

For the Sapling bundle at bundleVariant = 0, sighash variant 0 is the only variant defined, and its associatedData is the empty byte string. A Sapling spendAuthSig or bindingSig made with it commits to the digest defined in Variant 0 Signature Digest, with bundleType = 2 and bundleVariant = 0.

For vSpendAuthSigsSapling[i], signature_context is the two-byte unsigned little-endian encoding of \(i\kern-0.03em\textsf{,}\) the zero-based position of the corresponding spend in vSpendsSapling, where \(0 \leq i < \mathtt{nSpendsSapling}\kern-0.03em\textsf{.}\) For bindingSigSapling, signature_context is the empty byte string.

Sapling Digests
T.3.2: sapling_effects_digest

In the case that Sapling spends or outputs are present, the Sapling effects digest is a BLAKE2b-256 hash of the following values:

T.3.2a: sapling_spends_digest   (32-byte hash)
T.3.2b: sapling_outputs_digest  (32-byte hash)

The personalization field of this hash is set to:

"ZTxIdSaplingH_v7"

If there are no Sapling spends or outputs, there is no Sapling effecting bundle and no entry for it in effects_bundles_digest.

T.3.2a: sapling_spends_digest

In the case that Sapling spends are present, this digest is a BLAKE2b-256 hash of the following values:

T.3.2a.i:  sapling_spends_compact_digest    (32-byte hash)
T.3.2a.ii: sapling_spends_noncompact_digest (32-byte hash)

The personalization field of this hash is set to:

"ZTxIdSSpendsHash"

In the case that the transaction has Sapling outputs but no Sapling spends, sapling_spends_digest is:

BLAKE2b-256("ZTxIdSSpendsHash", [])
T.3.2a.i: sapling_spends_compact_digest

A BLAKE2b-256 hash of the field encoding of all nullifier field values of Sapling spends belonging to the transaction.

The personalization field of this hash is set to:

"ZTxIdSSpendCHash"
T.3.2a.ii: sapling_spends_noncompact_digest

A BLAKE2b-256 hash of the non-nullifier information for all Sapling spends belonging to the transaction. For each spend, the following elements are included in the hash:

T.3.2a.ii.1: cv (32 bytes)
T.3.2a.ii.2: rk (32 bytes)

The personalization field of this hash is set to:

"ZTxIdSSpendNH_v6"
T.3.2b: sapling_outputs_digest

In the case that Sapling outputs are present, this digest is a BLAKE2b-256 hash of the following values:

T.3.2b.i:   sapling_outputs_compact_digest    (32-byte hash)
T.3.2b.ii:  sapling_outputs_memos_digest      (32-byte hash)
T.3.2b.iii: sapling_outputs_noncompact_digest (32-byte hash)

The personalization field of this hash is set to:

"ZTxIdSOutputHash"

In the case that the transaction has Sapling spends but no Sapling outputs, sapling_outputs_digest is:

BLAKE2b-256("ZTxIdSOutputHash", [])
T.3.2b.i: sapling_outputs_compact_digest

A BLAKE2b-256 hash of the subset of Sapling output information included in the ZIP 307 24 CompactBlock format for all Sapling outputs belonging to the transaction. For each output, the following elements are included:

T.3.2b.i.1: cmu                  (32 bytes)
T.3.2b.i.2: ephemeralKey         (32 bytes)
T.3.2b.i.3: encCiphertext[..52]  (first 52 bytes)

The personalization field of this hash is set to:

"ZTxIdSOutC__Hash" (2 underscore characters)
T.3.2b.ii: sapling_outputs_memos_digest

A BLAKE2b-256 hash of the memo field data for all Sapling outputs belonging to the transaction. For each output:

T.3.2b.ii.1: encCiphertext[52..564] (512 bytes, encrypted memo)

The personalization field of this hash is set to:

"ZTxIdSOutM__Hash" (2 underscore characters)
T.3.2b.iii: sapling_outputs_noncompact_digest

A BLAKE2b-256 hash of the remaining Sapling output information not included in the CompactBlock format. For each output:

T.3.2b.iii.1: cv                    (32 bytes)
T.3.2b.iii.2: encCiphertext[564..]  (post-memo AEAD tag, 16 bytes)
T.3.2b.iii.3: outCiphertext         (80 bytes)

The personalization field of this hash is set to:

"ZTxIdSOutN__Hash" (2 underscore characters)
A.1.2: sapling_auth_digest

In the case that Sapling spends or outputs are present, this is a BLAKE2b-256 hash of the following concatenated values:

A.1.2a: anchorSapling          (32 bytes, present iff nSpendsSapling > 0)
A.1.2b: vSpendProofsSapling    (192 bytes per spend)
A.1.2c: vSpendAuthSigsSapling  (SaplingSignature field encoding per spend)
A.1.2d: vOutputProofsSapling   (192 bytes per output)
A.1.2e: bindingSigSapling      (SaplingSignature field encoding)

The SaplingSignature field encoding is defined in Sapling Signature (``SaplingSignature`)`_ and includes sighashInfo.

The personalization field of this hash is set to:

"ZTxAuthSapliH_v7"

If there are no Sapling spends or outputs, there is no Sapling authorizing bundle and no entry for it in auth_bundles_digest.

Orchard Protocol Bundles

The Orchard protocol supports two value pools, each with its own note commitment tree, nullifier set, and chain value pool balance. Each is acted upon by its own bundle type: the Orchard bundle, bundleType = 3, acts on the Orchard pool, and the Ironwood bundle, bundleType = 4, acts on the Ironwood pool.

An entry for either bundle type in mEffectBundles MUST contain at least one Action description (nActionsOrchard > 0 or nActionsIronwood > 0). If there would be no Actions for that bundle type, the bundle MUST be omitted instead.

Both bundle types use the encoding defined in this section. Where a field is described below as belonging to the bundle's pool, that pool is the Orchard pool for an Orchard bundle and the Ironwood pool for an Ironwood bundle.

The bits of flagsOrchard have the same meaning for both pools, and so are named without the Orchard suffix they carried in the v5 transaction format, following ZIP 229 19. Their values are constrained per pool by the Bundle-local rules.

Orchard Protocol Effecting Data

The effecting data for an Orchard protocol bundle describes the Orchard actions. Unlike the v5 transaction format defined in ZIP 225 18, the value balance is not included here; it appears in mValuePoolDeltas instead.

Bytes Name Data Type Description
varies nActionsOrchard compactSize The number of Orchard Action descriptions.
820 * nActionsOrchard vActionsOrchard OrchardActionEffecting[nActionsOrchard] Effecting data for each Orchard Action.
1 flagsOrchard byte

An 8-bit value representing a set of flags. Ordered from LSB to MSB:

  • enableSpends
  • enableOutputs
  • enableCrossAddress 27
  • The remaining bits are set to \(0\!\) .
  • The field flagsOrchard is present if and only if \(\mathtt{nActionsOrchard} > 0\kern-0.03em\textsf{.}\)

The anchor is not part of the effecting data; it appears in Orchard Protocol Authorizing Data.

OrchardActionEffecting
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 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 created by concatenation of the transmission key with the ephemeral secret key.
Orchard Protocol Authorizing Data

The authorizing data for an Orchard protocol bundle contains the proofs and signatures that authorize the actions.

Bytes Name Data Type Description
32 anchorOrchard byte[32] A root of the note commitment tree of the bundle's pool, at some block height in the past.
varies sizeProofsOrchard compactSize Length in bytes of proofsOrchard. Value is \(2720 + 2272 \cdot \mathtt{nActionsOrchard}\!\) .
sizeProofsOrchard proofsOrchard byte[sizeProofsOrchard] Encoding of aggregated zk-SNARK proofs for Orchard Actions.
varies vSpendAuthSigsOrchard OrchardSignature[nActionsOrchard] Authorizing signatures for each Orchard Action.
varies bindingSigOrchard OrchardSignature An Orchard binding signature on the SIGHASH transaction hash.
  • The value of nActionsOrchard is not re-encoded in the authorizing data; it is taken from the corresponding effecting data.
  • The fields anchorOrchard, sizeProofsOrchard, proofsOrchard, and bindingSigOrchard are present if and only if \(\mathtt{nActionsOrchard} > 0\kern-0.03em\textsf{.}\)
Orchard Signature (OrchardSignature)
Bytes Name Data Type Description
varies sizeSighashInfo compactSize The size in bytes of sighashInfo.
sizeSighashInfo sighashInfo byte[sizeSighashInfo] The sighash variant and associated information, as defined in Sighash Variants.
64 signature byte[64] An encoding of a RedPallas signature, which may be either a spendAuthSig or bindingSig depending on context.

The 1:1 correspondences between the authorizing-data elements of an Orchard protocol bundle and the elements of the corresponding effecting data are required by the parsing rules in Parsing Rules.

Orchard Protocol Sighash Algorithms

For the Orchard and Ironwood bundles at bundleVariant = 0, sighash variant 0 is the only variant defined, and its associatedData is the empty byte string. An Orchard protocol spendAuthSig or bindingSig made with it commits to the digest defined in Variant 0 Signature Digest, with bundleType = 3 for Orchard or bundleType = 4 for Ironwood, and bundleVariant = 0.

In either an Orchard or an Ironwood bundle, the signature_context for vSpendAuthSigsOrchard[i] is the two-byte unsigned little-endian encoding of \(i\kern-0.03em\textsf{,}\) the zero-based position of the corresponding action in that bundle's vActionsOrchard, where \(0 \leq i < \mathtt{nActionsOrchard}\kern-0.03em\textsf{.}\) These field names refer to the shared encoding used by both bundle types. The index is local to the bundle containing the signature; it does not count actions in other bundles. For the bindingSigOrchard of either bundle type, signature_context is the empty byte string.

Orchard Protocol Digests
T.3.3: orchard_effects_digest

The digest defined here and in its child sections is the Orchard bundle's instance of a digest shape shared with the Ironwood bundle; T.3.4 gives the Ironwood instance.

In the case that Orchard actions are present, the Orchard effects digest is a BLAKE2b-256 hash of the following values:

T.3.3a: orchard_actions_compact_digest    (32-byte hash)
T.3.3b: orchard_actions_memos_digest      (32-byte hash)
T.3.3c: orchard_actions_noncompact_digest (32-byte hash)
T.3.3d: flagsOrchard                      (1 byte)

The personalization field of this hash is set to:

"ZTxIdOrchardH_v7"

If there are no Orchard actions, there is no Orchard effecting bundle and no entry for it in effects_bundles_digest.

T.3.3a: orchard_actions_compact_digest

A BLAKE2b-256 hash of the subset of Orchard action information intended for inclusion in the CompactBlock format. For each action:

T.3.3a.i:   nullifier            (32 bytes)
T.3.3a.ii:  cmx                  (32 bytes)
T.3.3a.iii: ephemeralKey         (32 bytes)
T.3.3a.iv:  encCiphertext[..52]  (first 52 bytes)

The personalization field of this hash is set to:

"ZTxIdOrcActCHash"
T.3.3b: orchard_actions_memos_digest

A BLAKE2b-256 hash of the memo field data for all Orchard actions. For each action:

T.3.3b.i: encCiphertext[52..564] (512 bytes, encrypted memo)

The personalization field of this hash is set to:

"ZTxIdOrcActMHash"
T.3.3c: orchard_actions_noncompact_digest

A BLAKE2b-256 hash of the remaining Orchard action information not intended for inclusion in the CompactBlock format. For each action:

T.3.3c.i:   cv                   (32 bytes)
T.3.3c.ii:  rk                   (32 bytes)
T.3.3c.iii: encCiphertext[564..] (post-memo AEAD tag, 16 bytes)
T.3.3c.iv:  outCiphertext        (80 bytes)

The personalization field of this hash is set to:

"ZTxIdOrcActNHash"
T.3.4: ironwood_effects_digest

The Ironwood bundle uses the same effecting data encoding as the Orchard bundle, and ironwood_effects_digest is computed over that data exactly as orchard_effects_digest and its children are computed (T.3.3), except that each personalization string is replaced as follows:

Digest Orchard bundle Ironwood bundle
effects digest ZTxIdOrchardH_v7 ZTxIdIronwd_Hash
actions compact digest ZTxIdOrcActCHash ZTxIdIrnActCH_v6
actions memos digest ZTxIdOrcActMHash ZTxIdIrnActMH_v6
actions noncompact digest ZTxIdOrcActNHash ZTxIdIrnActNH_v6

If there are no Ironwood actions, there is no Ironwood effecting bundle and no entry for it in effects_bundles_digest.

A.1.3: orchard_auth_digest

In the case that Orchard actions are present, this is a BLAKE2b-256 hash of the following concatenated values:

A.1.3a: anchorOrchard         (32 bytes)
A.1.3b: proofsOrchard         (aggregated proofs)
A.1.3c: vSpendAuthSigsOrchard (OrchardSignature field encoding per action)
A.1.3d: bindingSigOrchard     (OrchardSignature field encoding)

The OrchardSignature field encoding is defined in Orchard Signature (``OrchardSignature`)`_ and includes sighashInfo.

The personalization field of this hash is set to:

"ZTxAuthOrchaH_v7"

If there are no Orchard actions, there is no Orchard authorizing bundle and no entry for it in auth_bundles_digest.

A.1.4: ironwood_auth_digest

The Ironwood bundle uses the same authorizing data encoding as the Orchard bundle, and ironwood_auth_digest is computed over that data exactly as orchard_auth_digest (A.1.3), including its commitment to the anchor, except that the personalization field of the hash is set to:

"ZTxAuthIrnwdHash"

If there are no Ironwood actions, there is no Ironwood authorizing bundle and no entry for it in auth_bundles_digest.

Rationale

Effecting data bundles and authorizing data bundles are stored separately in the transaction format so that the authorizing data may be pruned by straightforward truncation of the encoded representation of the transaction.

Representing the coinbase as a bundle makes the value pool delta balance rule universal. Previously the coinbase transaction was the sole exception: its deltas summed to the negation of the block subsidy rather than to zero, because the subsidy entered the transparent transaction value pool implicitly. With the subsidy carried in the coinbase bundle's value pool delta, every transaction balances to zero, and a wallet can enumerate the value flows of a coinbase transaction using the same rule it applies to any other transaction.

The input and output requirements prevent trivial transactions (with no inputs or outputs). They allow fee-free transfers within a single shielded pool: such a transaction can satisfy both requirements through its spends and outputs even when it has no value pool delta entries. A zero net delta does not imply that no value moves within a pool.

Carrying blockSubsidy and lockboxValue in the effecting data states both components of the issuance in the bundle they belong to, and commits them to the transaction identifier along with the rest of that data. The value pool delta combines their difference with the fee contribution removed from circulation under ZIP 235. Without the explicit fields, a client could see the net delta but not how much was issued or how much went to the lockbox. Deriving them instead is not open to every client: the subsidy is not a function of the block height alone once issuance depends on accumulated chain state, so evaluating the issuance schedule would require a client to track that state. The NSM fee contribution is derivable from the gross fee bundle value already present in the coinbase transaction, so it needs neither an additional coinbase effecting field nor a ZIP 233 entry. ZIP 233 separately provides an explicit bundle for voluntary removal from circulation. 20

The Orchard and Ironwood bundles share one encoding because the Orchard pool and the Ironwood pool are two pools of the same shielded protocol. The action encoding, proving system, authorization, and note encryption are common to both; the pools differ in their note commitment trees, nullifier sets, and chain value pool balances.

Each pool gets its own bundle type rather than a variant of a single type because a variant is required to affect the same value pool(s) as the type it varies, so that a client encountering an unrecognized variant still knows which pools the bundle touches. Two pools therefore cannot share a bundle type, and separate types also keep the two value pool deltas separable, which a client needs in order to report the two chain value pool balances independently.

The Sapling and Orchard protocol anchors are authorizing data rather than effecting data. An anchor selects the note commitment tree state that the bundle's proofs are verified against, which is a property of how the spends are authorized rather than of what the transaction does. Placing it there lets a bundle be re-anchored to a more recent root without changing the transaction identifier, while the proofs still bind to the anchor actually used.

Bundle digests retain the input formats and personalizations of ZIP 229 19 wherever the committed data is unchanged. Effects roots have different personalizations because value balances are committed separately in the value pool delta map. Authorizing digests have different personalizations because signatures include sighashInfo and anchors precede the proofs and signatures. Orchard and Ironwood use distinct personalizations to separate commitments for their respective pools.

The coinbase bundle also gives the coinbase metadata a place of its own. In previous transaction versions that metadata was encoded as the scriptSig of a single transparent input whose previous output reference pointed at nothing, so a coinbase transaction had to be recognized by that unspendable reference, and the block height had to be encoded as a script push. The coinbase bundle encodes the height directly, and its presence identifies the transaction. The coinbaseData limit of 94 bytes holds the encoded size of that field to what the previous encoding spent on the same content. A coinbase scriptSig was limited to 100 bytes, of which the leading push of the block height took 5; of the 95 bytes that remained, the compactSize length prefix of coinbaseData now takes one.

Neither the previous output reference nor the sequence number of the input being replaced is carried over. Both were artifacts of encoding the coinbase metadata as a transparent input: the reference identified no output, and the sequence number had no effect on the validity of a transaction that spends nothing.

Deployment

Reference implementation

References

1 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
2 Zcash Protocol Specification, Version 2025.6.3 [NU6.1] or later
3 Zcash Protocol Specification, Version 2025.6.3 [NU6.1]. Section 3.3: The Block Chain
4 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Block Header Encoding and Consensus
5 Zcash Protocol Specification, Version 2025.6.3 [NU6.1]. Section 3.4: Transactions and Treestates
6 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Section 3.11: Coinbase Transactions
7 Zcash Protocol Specification, Version 2025.6.3 [NU6.1]. Section 3.12: Mainnet and Testnet
8 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Section 4.13: Balance and Binding Signature (Sapling)
9 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Section 4.14: Balance and Binding Signature (Orchard)
10 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Section 4.17: Chain Value Pool Balances
11 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Section 7.1.2: Transaction Consensus Rules
12 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Section 4.10: SIGHASH Transaction Hashing
13 Zcash Protocol Specification, Version 2026.8.0 [NU6.3]. Section 4.15: Spend Authorization Signature (Sapling and Orchard)
14 Zcash Protocol Specification, Version 2025.6.3 [NU6.1]. Section 7.8: Block Subsidy and Founders' Reward
15 Zcash Protocol Specification, Version 2025.6.3 [NU6.1]. Section 7.10: Payment of Funding Streams, Deferred Lockbox, and Lockbox Disbursement
16 ZIP 203: Transaction Expiry
17 ZIP 212: Allow Recipient to Derive Ephemeral Secret from Note Plaintext
18 ZIP 225: Version 5 Transaction Format
19 ZIP 229: Version 6 Transaction Format
20 ZIP 233: Network Sustainability Mechanism: Removing Funds From Circulation
21 ZIP 235: Remove 60% of Transaction Fees From Circulation
22 ZIP 239: Relay of Version 5 Transactions
23 ZIP 244: Transaction Identifier Non-Malleability
24 ZIP 307: Light Client Protocol for Payment Detection
25 ZIP 2001: Lockbox Funding Streams
26 ZIP 2002: Explicit Fees
27 ZIP 2006: Restricting Transfers into the Orchard Pool