Suggestion for "[ZIP 248]: Define a forward-compatible, extensible transaction format. #1156" by arya2 · Pull Request #1253 · zcash/zips

arya2 · 2026-04-04T01:44:47Z

Structured digest approach

This PR uses structured per-bundle digest trees for the transaction
identifier and authorizing data commitment. Each bundle type's defining
ZIP specifies its own digest algorithm, which SHOULD separate compact
data (for the light wallet protocol) from non-compact data to enable
trustless partial verification.

For bundle types a wallet does not understand, the wallet needs the
32-byte bundle_effects_digest to be supplied externally (e.g. by a
light wallet server or full node that implements the bundle type's
digest algorithm).

An alternative approach using flat hashes with a compact/noncompact
wire format split is proposed in #1258. That approach allows any
wallet to compute the txid without understanding all bundle types, at
the cost of requiring existing bundle types to switch from structured
to flat effect digests.

Changes in this update

Add Parsing Rules section consolidating parser-level invariants
Restructure Consensus Rules into bundle-local and cross-bundle subsections
Clarify anchorSapling handling at T.3.2c when nSpendsSapling = 0
Pad ZTxIdEffBndHash / ZTxAuthBndHash personalizations to 16 characters
Fix heading underline in Per-Signature Structures
Fix typos, RST syntax, and normative language (MUST)
Remove redundant normative constraints; cross-reference Parsing Rules
Specify key comparison for mValuePoolDeltas ordering
Define transparent bundle value pool delta computation
Clarify structured digest approach for bundle type registration

Ref impl: zcash/librustzcash@main...zip248

daira · 2026-04-07T20:30:03Z

      \forall \mathsf{a}. \sum_{\mathsf{d} \in \mathsf{mValuePoolDeltas} | \mathsf{AssetUuid}(\mathsf{d}) = \mathsf{a}} \mathsf{d.value} = 0

+Sighash Versioning
+-------------------


Suggested change

-------------------

------------------

nuttycom · 2026-04-07T20:36:07Z

+--------------------+-------------------------------------------------------+
+|                    |:math:`\hspace{4.5em}` ``associatedData``              |
+--------------------+-------------+-------------+-------------+-------------+
+| ``sighashVersion`` | Transparent |   Sapling   |   Orchard   |  Issuance   |


Issuance doesn't belong here. Also, this table seems like it might be malformed given the extensible nature of this transaction format.

nuttycom · 2026-04-07T21:29:25Z

+Sighash version information is present alongside each signature in the
+authorizing data of the transaction, via the per-signature structures defined
+below.
+


The process for introducing a new sighash version (including how that affects each bundle type) should be specified here. Add a TODO.

arya2 · 2026-04-10T22:29:01Z

+* For coinbase transactions, the ``enableSpendsOrchard`` bit of the Orchard
+  bundle's ``flagsOrchard`` field MUST be 0.


Do we want to make this a global rule in the protocol instead of applying it to V5 txs there and writing it again here?

arya2 · 2026-04-14T20:45:07Z

+   identifier, if effecting data is present. For bundle types not defined in
+   this ZIP, the ``bundle_effects_digest`` MUST be equal to
+   ``BLAKE2b-256(personalization, vBundleData)`` where
+   ``personalization`` is the `Opaque Effects Personalization`_ for the
+   bundle's ``(bundleType, bundleVariant)`` pair. This ensures that wallets
+   which do not understand the bundle type can still compute the correct
+   transaction identifier by hashing the raw effecting data.


@nuttycom did you have an argument against using flat hashes everywhere for computing transaction ids from effects/auth bundles? I've mixed legacy structured hashes and flat hashes here, but would like to update it to use flat hashes everywhere if there are no objections.

…tion format.

…les.

… and Orchard. Specifies the effecting and authorizing data structures for each bundle type, with value balance moved to mValuePoolDeltas as per the extensible tx format design. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…ment. Specifies the V6 transaction digest algorithms: - TxId digest with separate value_pool_deltas_digest and dynamic effects_bundles_digest - Signature digest for transparent input signing with hash_type support - Authorizing data commitment for witness data Key design decisions: - Value balances committed via top-level value_pool_deltas_digest (not per-bundle) - effects_bundles_digest uses tagged concatenation (bundle_type_id || root_hash) - Unknown bundle types supported by accepting their root hash externally Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…tion process. Restructure the specification to begin with a comprehensive introduction to protocol bundles, explaining effecting data, authorizing data, and the transparent transaction value pool concepts. Define the bundle type registration process that ZIPs must follow when introducing new bundle types. Move the bundle type registry to appear before the transaction format specification for better readability. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Update PR URL to 1156 and fix email addresses - Use conformance language (MAY/MUST NOT) for registry column descriptions - Add constraint that map keys must be in increasing order - Change "ordered by" to "in increasing order of" throughout - Fix "transparent transaction value pool" terminology - Change AssetUuid subscript notation to function notation - Add registry update mechanism language - Add "Defining ZIP" column to bundle type registry table - Rephrase consensus rules section to clarify modifications to protocol spec - Add clarifying text for fee bundle semantics (coinbase collects, others pay) - Add mutual exclusion consensus rule for Sapling/Orchard bundle variants Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Register bundle type 4 (Transaction fee) in the V6 bundle registry - Update consensus rules to use mValuePoolDeltas terminology - Replace header_digest modification with value_pool_deltas_digest reference - Add reference to extensible transaction format ZIP Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Register bundle type 5 (NSM field) in the V6 bundle registry - Update consensus rules to use mValuePoolDeltas terminology - Replace header_digest modification with value_pool_deltas_digest reference - Add reference to extensible transaction format ZIP Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Register Memos, Sapling-post-ZIP 231, and Orchard-post-ZIP 231 bundle types - Update encoding section to clarify it describes effecting data - Replace Transaction sighash section with Transaction Digest referencing ZIP XXX - Specify BLAKE2b-256 personalization strings for memo digest computation - Add reference to extensible transaction format ZIP - Fix zip-0230-note-plaintexts reference Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Register ZSA Issuance bundle type in the V6 bundle registry - Update digest section to reference effects_bundles_digest and auth_bundles_digest - Add reference to extensible transaction format ZIP - Remove unused ZIP 244 and ZIP 246 references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Register OrchardZSA bundle type in the V6 bundle registry - Update digest section to reference effects_bundles_digest and auth_bundles_digest - Add reference to extensible transaction format ZIP - Remove unused ZIP 244 and ZIP 246 references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…uples. This makes the mutual exclusivity of bundle variants (e.g. Orchard vs OrchardZSA) implicit in the map structure, and allows clients that do not recognize a specific bundleVersion to still identify which pool is affected. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add a section to ZIP 248 describing wallet requirements for handling unknown bundle types and versions. Update ZIP 226 to reference ZIP 248 instead of ZIP 230 for transaction format and wallet implications. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…tions Co-Authored-By: Claude (unknown version) <noreply@anthropic.com>

Co-Authored-By: Claude (unknown version) <noreply@anthropic.com>

A "Parsing Rules" section, ahead of the per-bundle format definitions and "Consensus Rules", lists the parser-level invariants that any v6 parser must enforce regardless of which bundle types it understands. This makes it explicit that parsing the format is safe even for parsers that don't recognize every bundle type, and gives wallets a single place to look for the constraints they need to check before they can compute the txid or enumerate transparent value flows. Move the cross-map "all entries for the same bundleType across the three maps must encode the same bundleVariant" rule, the per-element 1:1 correspondences in the Sapling authorizing-data section, and the analogous rules in the Orchard authorizing-data section into the new section. Their previous locations are replaced with one-line forward references. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ndle subsections. The bundle-local rules ("assetClass = 0 for fee bundle entries", and "coinbase transactions must have enableSpendsOrchard = 0") only need to be enforced by parties that understand the bundle type they apply to, while the cross-bundle / chain-context rules (per-block fee sum, coinbase ZEC subsidy sum, non-coinbase per-asset value pool delta sum) require full validators with block context. The "coinbase transactions must have enableSpendsOrchard = 0" rule was previously stated in passing in the prose under the Orchard flagsOrchard field; lift it into the new bundle-local subsection so all consensus rules are in one place. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ng = 0. The wire format for v6 Sapling effecting data omits anchorSapling when there are no Sapling spends, but T.3.2c lists anchorSapling as an unconditional 32-byte component of sapling_effects_digest. State explicitly that the value hashed at T.3.2c is 32 zero bytes in that case, so the digest structure remains fixed for any non-empty Sapling bundle. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… 16 characters. Every other personalization string in the digest tree is exactly 16 characters, but ZTxIdEffBndHash (15) and ZTxAuthBndHash (14) were shorter, leaving the padding for the trailing bytes ambiguous. Rename them to ZTxIdEffBnd_Hash (1 underscore) and ZTxAuthBnd__Hash (2 underscores), matching the existing underscore-padding convention used elsewhere in this ZIP (e.g. ZTxIdSOutC__Hash) and in ZIP 244. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use "'" instead of "." for the sub-headings, so they're level 4 (matching the rest of the document) instead of level 5. The previous underline triggered a docutils "Title level inconsistent" SEVERE error and the document failed to render. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix "wouild" → "would", "advertizing" → "advertising", "inaccessiblity" → "inaccessibility", "i.e," → "i.e.,", and "[^BCP14]" (Markdown footnote) → "[#BCP14]_" (RST). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… section. Consensus Rules and Transaction Format prose use lowercase "must" for requirements that are normative. Per BCP 14, these carry conformance meaning only when in ALL CAPS in the Specification section. Requirements section left as-is per ZIP 0 (must not contain conformance requirements). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…rsing Rules. The uniqueness, ordering, and cross-map consistency constraints on mValuePoolDeltas, mEffectBundles, and mAuthBundles were stated in three places: the prose after the Transaction Format table, the prose after the ValuePoolDelta table, and the Parsing Rules section. Keep Parsing Rules as the single normative source and replace the earlier prose with descriptive text and a cross-reference. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The Parsing Rules required entries in strictly increasing key order but did not specify the comparison operation for the 64-byte assetUuid field. State explicitly that the key tuple (bundleType, assetClass, assetUuid) is compared lexicographically, with assetUuid compared as a byte string. Also fix a circular cross-reference: Parsing Rules said "as defined in Transaction Format" but Transaction Format now cross-references Parsing Rules. Make the Parsing Rules bullet self-contained instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The transparent bundle has no cryptographic binding between its contents and its mValuePoolDeltas entry (unlike Sapling/Orchard where value commitments and binding signatures enforce the relationship). Specify the consensus rule that full validators MUST verify the transparent delta equals total input value minus total output value, for both non-coinbase and coinbase transactions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ation. Make explicit that each new bundle type's defining ZIP specifies its own digest algorithm (point 7 of Bundle Type Registration), SHOULD use a structured sub-tree separating compact from non-compact data for trustless partial verification, and that wallets unable to compute the digest themselves may obtain it from any source that implements the algorithm (e.g. a light wallet server or full node). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

daira changed the base branch from main to draft/extensible_tx_format April 7, 2026 20:09

nuttycom reviewed Apr 7, 2026

View reviewed changes

Comment thread zips/zip-0248.rst Outdated

daira reviewed Apr 7, 2026

View reviewed changes

Comment thread zips/zip-0248.rst Outdated

daira reviewed Apr 7, 2026

View reviewed changes

nuttycom reviewed Apr 7, 2026

View reviewed changes

daira force-pushed the suggestion-extensible_tx_format branch from 3b9fefb to b1a46d8 Compare April 9, 2026 04:24

daira changed the base branch from draft/extensible_tx_format to main April 9, 2026 04:25

daira marked this pull request as draft April 9, 2026 04:31

daira force-pushed the suggestion-extensible_tx_format branch from b1a46d8 to b31e49d Compare April 9, 2026 04:36

arya2 commented Apr 10, 2026

View reviewed changes

arya2 commented Apr 14, 2026

View reviewed changes

daira force-pushed the suggestion-extensible_tx_format branch from cf2a3f6 to ab81ac2 Compare April 15, 2026 00:26

daira mentioned this pull request Apr 15, 2026

[ZIP 248]: Alternative — flat effect digests with compact/noncompact wire split #1260

Open

nuttycom and others added 16 commits April 21, 2026 14:18

[ZIP 248]: Add motivation & notes for design of an extensible transac…

bc0ee7a

…tion format.

[ZIP 248]: Fill in Privacy Implications section.

cf39577

[ZIP 248]: Add BundleDescription

ba21f8b

[ZIP 248]: Add bundle ID registry

03ab3ce

[ZIP 248]: Fix rst rendering

9cb099c

[ZIP 248]: Render update to README.rst

1b1751e

[ZIP 248]: Add consensus rules for transaction value balance.

a01e827

[ZIP 248]: Separate effecting data bundles from authorizing data bund…

92fbaae

…les.

[ZIP 248]: Fix table rendering

c8b6e83

[ZIP 248]: Fold away rationale & potental future bundle types spec.

3f4eb52

nuttycom and others added 22 commits April 21, 2026 14:25

[ZIP 248]: Rename bundleVersion to bundleVariant

6564e41

[ZIP 248]: Specify mValuePoolDeltas encoding order.

0520e08

[ZIP 248]: Fix ordering constraint in signature hashing.

a161fef

[ZIP 248]: Address comments from code review.

1e02d2f

Add sighash versioning and associated data definitions for V6 transac…

42e1c56

…tions Co-Authored-By: Claude (unknown version) <noreply@anthropic.com>

Remove references to ZIP 230 and ZIP 246

498fd85

Co-Authored-By: Claude (unknown version) <noreply@anthropic.com>

[ZIP 248]: Fix typos and RST syntax.

d4b9810

Fix "wouild" → "would", "advertizing" → "advertising", "inaccessiblity" → "inaccessibility", "i.e," → "i.e.,", and "[^BCP14]" (Markdown footnote) → "[#BCP14]_" (RST). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

nuttycom force-pushed the suggestion-extensible_tx_format branch from ab81ac2 to de8b429 Compare April 21, 2026 20:28

nuttycom changed the base branch from main to draft/extensible_tx_format April 21, 2026 20:28

daira added the F-transaction-v6 Feature: v6 transactions label Apr 24, 2026

nuttycom force-pushed the draft/extensible_tx_format branch from 1e02d2f to 5c49035 Compare May 13, 2026 18:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Suggestion for "[ZIP 248]: Define a forward-compatible, extensible transaction format. #1156"#1253

Suggestion for "[ZIP 248]: Define a forward-compatible, extensible transaction format. #1156"#1253
arya2 wants to merge 38 commits into
draft/extensible_tx_formatfrom
suggestion-extensible_tx_format

arya2 commented Apr 4, 2026 •

edited by daira

Loading

Uh oh!

Uh oh!

Uh oh!

daira Apr 7, 2026

Uh oh!

nuttycom Apr 7, 2026

Uh oh!

nuttycom Apr 7, 2026

Uh oh!

arya2 Apr 10, 2026

Uh oh!

arya2 Apr 14, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		* For coinbase transactions, the ``enableSpendsOrchard`` bit of the Orchard
		bundle's ``flagsOrchard`` field MUST be 0.

Conversation

arya2 commented Apr 4, 2026 • edited by daira Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Structured digest approach

Changes in this update

Uh oh!

Uh oh!

Uh oh!

daira Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

nuttycom Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

nuttycom Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

arya2 Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

arya2 Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

arya2 commented Apr 4, 2026 •

edited by daira

Loading

arya2 Apr 14, 2026 •

edited

Loading