[ZIP 248]: Alternative — flat effect digests with compact/noncompact wire split#1260
Open
daira wants to merge 38 commits into
Open
[ZIP 248]: Alternative — flat effect digests with compact/noncompact wire split#1260daira wants to merge 38 commits into
daira wants to merge 38 commits into
Conversation
daira
force-pushed
the
zip248-flat-split
branch
from
2bad097 to
433600a
Compare
… 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>
…format.
Replace the single-blob `BundleData` framing for `mEffectBundles`
with `EffectBundleData`, which separates each bundle's effecting data
into compact and noncompact portions at the wire level. The txid tree
hashes each portion as a flat BLAKE2b-256 using opaque personalizations
("ZTxIdCompctHash" and "ZTxIdNoncmpHash") with a
`compactSize(bundleType) || compactSize(bundleVariant)` prefix for
domain separation between bundle types.
This enables two properties simultaneously:
- Any wallet can compute the txid for any well-formed v6 transaction,
even one containing bundle types it doesn't understand.
- Light clients can verify compact data against the txid without
needing the noncompact data (trustless partial verification).
The auth side retains per-bundle structured digests (defined by each
bundle type's defining ZIP), with a note that this is still under
discussion. Rationale sections explain the reasoning for both choices.
`mAuthBundles` continues to use the existing `BundleData` framing.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
nuttycom
force-pushed
the
zip248-flat-split
branch
from
433600a to
8c1a2a8
Compare
nuttycom
force-pushed
the
draft/extensible_tx_format
branch
from
1e02d2f to
5c49035
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Flat effect digests with compact/noncompact wire split
This is an alternative to #1253 (structured digests) for computing
per-bundle effect digests in the v6 transaction identifier.
Design
The
mEffectBundleswire format separates each bundle's effecting datainto compact and noncompact portions at the framing level
(
EffectBundleData). The txid tree hashes each portion as a flatBLAKE2b-256 using fixed opaque personalizations (
ZTxIdCEffectHash,ZTxIdNEffectHash) with acompactSize(bundleType) || compactSize(bundleVariant)prefix for domain separation.
The auth side retains per-bundle structured digests (defined by each
bundle type's defining ZIP), with a note that this is still under
discussion.
Properties
even one containing bundle types it doesn't understand — no external
digest oracle needed.
needing the noncompact data (trustless partial verification).
the compact/noncompact field split, not a full digest tree.
Trade-offs vs structured (#1253)
Shared changes
Both PRs share the same base commits for spec quality improvements
(typo fixes, normative language, Parsing Rules consolidation, etc.).
Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com