ZIP: 246
Title: Digests for the Version 6 Transaction Format
Owners: Arya <arya@zfnd.org>
        Conrado Gouvea <conrado@zfnd.org>
        Daira-Emma Hopwood <daira-emma@electriccoin.co>
        Jack Grigg <str4d@electriccoin.co>
        Kris Nuttycombe <kris@electriccoin.co>
Status: Draft
Category: Consensus
Created: 2025-02-12
License: MIT

Terminology

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

The terms "consensus branch", "epoch", and "network upgrade" in this document are to be interpreted as described in ZIP 200. 7

The term "field encoding" refers to the binary serialized form of a Zcash transaction field, as specified in section 7.1 of the Zcash protocol specification 6.

Abstract

This ZIP defines the digest algorithms associated with the v6 transaction format.

This proposal also defines the new concept of "sighash versioning": where previously each transaction version had a single associated digest algorithm, going forward it will be possible for signers to use any digest algorithm within the closed set specified for a given transaction version (and made available in consensus via network upgrades).

Motivation

TBD

TODO: Motivate sighash versioning

Requirements

Non-requirements

TBD

Specification

Sighash versioning

Rough summary:

  • Sighash versions are numbered starting from 0 for each tx version.
  • v0 is by convention the "commit to everything" sighash digest. Other versions can commit to whatever makes sense for desired functionality within that tx version.
  • Have a single byte encoded alongside the signature (not appended the way transparent does) that permits the signer to specify which sighash version they are using.
  • Consensus rules choose the digest algorithm for each signer based on that byte.

v0 Digests

The v0 digests are based on the v5 transaction digest algorithm defined in ZIP 244 16.

TxId Digest

The overall structure of the TxID digest is as follows; each name referenced here will either be referenced or described in detail below:

txid_digest
├── header_digest *
├── transparent_digest
│   ├── prevouts_digest
│   ├── sequence_digest
│   └── outputs_digest
├── sapling_digest
│   ├── sapling_spends_digest
│   │   ├── sapling_spends_compact_digest
│   │   └── sapling_spends_noncompact_digest
│   ├── sapling_outputs_digest *
│   │   ├── sapling_outputs_compact_digest *
│   │   └── sapling_outputs_noncompact_digest *
│   └── valueBalance
├── orchard_digest *
│   ├── orchard_action_groups_digest *
│   │   ├── orchard_actions_compact_digest *
│   │   ├── orchard_actions_noncompact_digest *
│   │   ├── flagsOrchard
│   │   ├── anchorOrchard
│   │   ├── nAGExpiryHeight *
│   │   └── orchard_burn_digest *
│   └── valueBalanceOrchard
├── issuance_digest *
│   ├── issue_actions_digest *
│   │   ├── issue_notes_digest *
│   │   ├── assetDescHash *
│   │   └── flagsIssuance *
│   └── issuanceValidatingKey *
└── memo_digest *
    ├── nonce *
    └── memo_chunks_digest *
        └── memo_chunk_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.

The nodes with a * have new definitions given below. All other nodes have the same definition as in ZIP 244 16.

txid_digest

A BLAKE2b-256 hash of the following values

T.1: header_digest       (32-byte hash output)
T.2: transparent_digest  (32-byte hash output)
T.3: sapling_digest      (32-byte hash output)
T.4: orchard_digest      (32-byte hash output)
T.5: issuance_digest     (32-byte hash output)
T.6: memo_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 16, 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 overwinter flag)
T.1b: version_group_id    (4-byte little-endian version group identifier)
T.1c: consensus_branch_id (4-byte little-endian consensus branch id)
T.1d: lock_time           (4-byte little-endian nLockTime value)
T.1e: expiry_height       (4-byte little-endian block height)
T.1f: fee                 (8-byte little-endian fee amount)
T.1g: burn_amount         (8-byte little-endian burn amount)

The personalization field of this hash is set to:

"ZTxIdHeadersHash"
T.3b: sapling_outputs_digest

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

T.3b.i:  sapling_outputs_compact_digest    (32-byte hash)
T.3b.ii: 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.3b.i: sapling_outputs_compact_digest

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

T.3b.i.1: cmu                  (field encoding bytes)
T.3b.i.2: ephemeral_key        (field encoding bytes)
T.3b.i.3: enc_ciphertext       (field encoding bytes)

The personalization field of this hash is set to:

"ZTxId6SOutC_Hash" (1 underscore character)

The field encodings are specified in ZIP 230 13.

T.3b.ii: sapling_outputs_noncompact_digest

A BLAKE2b-256 hash of the remaining subset of Sapling output information not included in the ZIP 307 19 CompactBlock format, excluding zkproof data, for all Sapling shielded outputs belonging to the transaction. For each output, the following elements are included in the hash:

T.3b.ii.1: cv                    (field encoding bytes)
T.3b.ii.3: out_ciphertext        (field encoding bytes)

The personalization field of this hash is set to:

"ZTxId6SOutN_Hash" (1 underscore character)

The field encodings are specified in ZIP 230 13.

T.4: orchard_digest

When OrchardZSA Actions Groups are present in the transaction, this digest is a BLAKE2b-256 hash of the following values:

T.4a: orchard_action_groups_digest   (32-byte hash output)
T.4b: valueBalanceOrchard            (64-bit signed little-endian)

The personalization field of this hash is set to:

"ZTxIdOrchardHash"

In the case that the transaction has no OrchardZSA Action Groups, orchard_digest is

BLAKE2b-256("ZTxIdOrchardHash", [])
T.4a: orchard_action_groups_digest

A BLAKE2b-256 hash of the subset of OrchardZSA Action Groups information for all OrchardZSA Action Groups belonging to the transaction. For each Action Group, the following elements are included in the hash:

T.4a.i   : orchard_actions_compact_digest      (32-byte hash output)
T.4a.ii  : orchard_actions_noncompact_digest   (32-byte hash output)
T.4a.iii : flagsOrchard                        (1 byte)
T.4a.iv  : anchorOrchard                       (32 bytes)
T.4a.v   : nAGExpiryHeight                     (4 bytes)
T.4a.vi  : orchard_burn_digest                 (32-byte hash output)

The personalization field of this hash is set to:

"ZTxIdOrcActGHash"
T.4a.i: orchard_actions_compact_digest

A BLAKE2b-256 hash of the subset of OrchardZSA Action information intended to be included in an updated version of the ZIP-307 19 CompactBlock format for all OrchardZSA Actions belonging to the Action Group. For each Action, the following elements are included in the hash:

T.4a.i.1 : nullifier            (field encoding bytes)
T.4a.i.2 : cmx                  (field encoding bytes)
T.4a.i.3 : ephemeralKey         (field encoding bytes)
T.4a.i.4 : encCiphertext        (field encoding bytes)

The personalization field of this hash is set to:

"ZTxId6OActC_Hash" (1 underscore character)

The field encodings are specified in ZIP 230 11.

T.4a.ii: orchard_actions_noncompact_digest

A BLAKE2b-256 hash of the remaining subset of OrchardZSA Action information not intended for inclusion in an updated version of the the ZIP 307 19 CompactBlock format, for all OrchardZSA Actions belonging to the Action Group. For each Action, the following elements are included in the hash:

T.4a.ii.1 : cv                    (field encoding bytes)
T.4a.ii.2 : rk                    (field encoding bytes)
T.4a.ii.3 : outCiphertext         (field encoding bytes)

The personalization field of this hash is set to:

"ZTxId6OActN_Hash" (1 underscore character)

The field encodings are specified in ZIP 230 11.

T.4a.vi: orchard_burn_digest

A BLAKE2b-256 hash of the data from the burn fields of the transaction. For each tuple in the \(\mathsf{assetBurn}\) set, the following elements are included in the hash:

T.4b.i : assetBase    (field encoding bytes)
T.4b.ii: valueBurn    (64-bit unsigned little-endian)

The personalization field of this hash is set to:

"ZTxIdOrcBurnHash"

In case the transaction does not perform the burning of any Assets (i.e. the \(\mathsf{assetBurn}\) set is empty), the orchard_burn_digest is:

BLAKE2b-256("ZTxIdOrcBurnHash", [])

The field encodings are specified in ZIP 230 12.

T.5: issuance_digest

A BLAKE2b-256 hash of the following values

T.5a: issue_actions_digest    (32-byte hash output)
T.5b: issuanceValidatingKey   (field encoding bytes)

The personalization field of this hash is set to:

"ZTxIdSAIssueHash"

In case the transaction has no issuance components, issuance_digest is:

BLAKE2b-256("ZTxIdSAIssueHash", [])

The field encodings are specified in ZIP 230 9.

T.5a: issue_actions_digest

A BLAKE2b-256 hash of Issue Action information for all Issuance Actions belonging to the transaction. For each Action, the following elements are included in the hash:

T.5a.i  : notes_digest            (32-byte hash output)
T.5a.ii : assetDescHash           (field encoding bytes)
T.5a.iii: flagsIssuance           (1 byte)

The personalization field of this hash is set to:

"ZTxIdIssuActHash"

The field encodings are specified in ZIP 230 14.

T.5a.i: issue_notes_digest

A BLAKE2b-256 hash of Note information for all Notes belonging to the Issuance Action. For each Note, the following elements are included in the hash:

T.5a.i.1: recipient                    (field encoding bytes)
T.5a.i.2: value                        (field encoding bytes)
T.5a.i.3: rho                          (field encoding bytes)
T.5a.i.4: rseed                        (field encoding bytes)

The personalization field of this hash is set to:

"ZTxIdIAcNoteHash"

In case the transaction has no Issue Notes, issue_notes_digest is:

BLAKE2b-256("ZTxIdIAcNoteHash", [])

The field encodings are specified in ZIP 230 15.

T.6: memo_digest

A BLAKE2b-256 hash of the following values

T.6a: nonce                 (field encoding bytes)
T.6b: memo_chunks_digest    (32-byte hash output)

The personalization field of this hash is set to:

"ZTxIdMemo___Hash" (3 underscore characters)

In case the transaction has no memo chunks, memo_digest is:

BLAKE2b-256("ZTxIdMemo___Hash", [])

The field encodings are specified in ZIP 230 9.

T.6b: memo_chunks_digest

A BLAKE2b-256 hash of the concatenated memo_chunk_digest values of all memo chunks within the memo bundle.

The personalization field of this hash is set to:

"ZTxIdMemoCksHash"

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

BLAKE2b-256("ZTxIdMemoCksHash", [])
T.6b.i: memo_chunk_digest

A BLAKE2b-256 hash of the field encoding of a single encrypted Memo Chunk.

The personalization field of this hash is set to:

"ZTxIdMemoCk_Hash" (1 underscore character)

The field encodings are specified in ZIP 230 14.

Signature Digest

The per-input transaction digest algorithm to generate the signature digest in ZIP 244 17 is modified so that a signature digest is produced for each transparent input, each Sapling input, each OrchardZSA Action, and additionally for each Issuance Action. The modifications replace the orchard_digest in ZIP 244 with a new orchard_digest, and add a new branch, issuance_digest, for the Issuance Action information.

The overall structure of the hash is as follows. We omit the descriptions of the sections that do not change for the OrchardZSA protocol:

signature_digest
├── header_digest
├── transparent_sig_digest
├── sapling_digest
├── orchard_digest
├── issuance_digest
└── memo_digest
signature_digest

A BLAKE2b-256 hash of the following values

S.1: header_digest          (32-byte hash output)
S.2: transparent_sig_digest (32-byte hash output)
S.3: sapling_digest         (32-byte hash output)
S.4: orchard_digest         (32-byte hash output)
S.5: issuance_digest        (32-byte hash output)
S.6: memo_digest            (32-byte hash output)

The personalization field remains the same as in ZIP 244 16, namely:

"ZcashTxHash_" || CONSENSUS_BRANCH_ID

ZcashTxHash_ has 1 underscore character.

S.4: orchard_digest

Identical to that specified for the transaction identifier.

S.5: issuance_digest

Identical to the issuance_digest specified for the transaction identifier in ZIP 227 zip-0227-txiddigest.

S.6: memo_digest

Identical to that specified for the transaction identifier.

Authorizing Data Commitment

The transaction digest algorithm defined in ZIP 244 18 which commits to the authorizing data of a transaction is modified by the OrchardZSA protocol to have the structure specified in this section. There is a new branch added for issuance information, and the orchard_auth_digest in ZIP 244 is replaced with orchard_auth_digest to account for the presence of Action Groups.

We omit the descriptions of the sections that do not change for the OrchardZSA protocol:

auth_digest
├── transparent_scripts_digest
├── sapling_auth_digest
├── orchard_auth_digest
└── issuance_auth_digest

The pair (Transaction Identifier, Auth Commitment) constitutes a commitment to all the data of a serialized transaction that may be included in a block.

auth_digest

A BLAKE2b-256 hash of the following values

A.1: transparent_scripts_digest (32-byte hash output)
A.2: sapling_auth_digest        (32-byte hash output)
A.3: orchard_auth_digest        (32-byte hash output)
A.4: issuance_auth_digest       (32-byte hash output)

The personalization field of this hash remains the same as in ZIP 244.

A.3: orchard_auth_digest

In the case that OrchardZSA Action Groups are present, this is a BLAKE2b-256 hash of the following values:

A.3a: orchard_action_groups_auth_digest  (32-byte hash output)
A.3b: bindingSigOrchard                      (field encoding bytes)

The personalization field of this hash is the same as in ZIP 244, that is:

"ZTxAuthOrchaHash"

In case that the transaction has no OrchardZSA Action Groups, orchard_auth_digest is:

BLAKE2b-256("ZTxAuthOrchaHash", [])

The field encodings are specified in ZIP 230 9.

A.3a: orchard_action_groups_auth_digest

This is a BLAKE2b-256 hash of the proofsOrchard field of all OrchardZSA Action Groups belonging to the transaction; followed by the spendAuthSigsOrchard fields corresponding to every OrchardZSA Action in the OrchardZSA Action Group, for all OrchardZSA Action Groups belonging to the transaction:

A.3a.i:  proofsOrchard               (field encoding bytes)
A.3a.ii: spendAuthSigsOrchard        (field encoding bytes)

The personalization field of this hash is set to:

"ZTxAuthOrcAGHash"

The field encodings are specified in ZIP 230 10.

A.4: issuance_auth_digest

In the case that Issuance Actions are present, this is a BLAKE2b-256 hash of the field encoding of the issueAuthSig field of the transaction:

A.4a: issueAuthSig            (field encoding bytes)

The personalization field of this hash is set to:

"ZTxAuthZSAOrHash"

In the case that the transaction has no Orchard Actions, issuance_auth_digest is

BLAKE2b-256("ZTxAuthZSAOrHash", [])

The field encodings are specified in ZIP 230 9.

Rationale

TBD

Reference implementation

TBD

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 2024.5.1 or later [NU6]
3 Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.4: Spend Descriptions
4 Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.5: Output Descriptions
5 Zcash Protocol Specification, Version 2024.5.1 [NU6]. Section 4.6: Action Descriptions
6 Zcash Protocol Specification, Version 2022.3.8. Section 7.1: Transaction Encoding and Consensus
7 ZIP 200: Network Upgrade Mechanism
8 ZIP 227: Issuance of Zcash Shielded Assets: TODO (issuance digest anchor missing)
9 ZIP 230: Version 6 Transaction Format. Specification: Transaction Format
10 ZIP 230: Version 6 Transaction Format. Specification: OrchardZSA Action Group Description
11 ZIP 230: Version 6 Transaction Format. Specification: OrchardZSA Action Description
12 ZIP 230: Version 6 Transaction Format. Specification: OrchardZSA Asset Burn Description
13 ZIP 230: Version 6 Transaction Format. Specification: Sapling Output Description (OutputDescriptionV6)
14 ZIP 230: Version 6 Transaction Format. Specification: Issuance Action Description
15 ZIP 230: Version 6 Transaction Format. Specification: Issue Note Description
16 ZIP 244: Transaction Identifier Non-Malleability
17 ZIP 244: Transaction Identifier Non-Malleability: Signature Digest
18 ZIP 244: Transaction Identifier Non-Malleability: Authorizing Data Commitment
19 ZIP 307: Light Client Protocol for Payment Detection