Skip to content

Add draft NU6.3 deployment and Version 6 Transaction Format ZIPs#1301

Merged
ebfull merged 14 commits into
zcash:mainfrom
daira:ironwood-zips
Jun 24, 2026
Merged

Add draft NU6.3 deployment and Version 6 Transaction Format ZIPs#1301
ebfull merged 14 commits into
zcash:mainfrom
daira:ironwood-zips

Conversation

@daira

@daira daira commented Jun 16, 2026

Copy link
Copy Markdown
Collaborator

This PR adds two draft ZIPs for NU6.3 ("Version 6 Transaction Format" and "Deployment of the NU6.3 Network Upgrade"), together with a retitle and terminology rework of ZIP 2005 ("Ironwood Quantum Recoverability").

Version 6 Transaction Format (draft-zodl-valargroup-ironwood-txformat)

A draft (modelled on ZIP 225) specifying version 6 of the Zcash transaction format: a version 5 transaction extended with an Ironwood component — a second Orchard-protocol shielded component that commits to, and spends from, the new Ironwood pool, reusing the Orchard Action encoding and proof system unchanged.

  • Framing (Abstract / Motivation / Privacy Implications): the Ironwood pool as a quantum-recoverable (ZIP 2005) Orchard-protocol successor; the supply-integrity motivation following the NU6.2 Orchard fix; the rule that Orchard outputs must be sent to an address the creator can authorize spends from (steering transfers into Ironwood); and the rationale for treating anchors as authorizing rather than effecting data.
  • Transaction format: the v6 field layout (Ironwood component = Orchard component shape; no ZSAs, no zip233Amount, no explicit fee, no per-input sighash info), with presence markers for conditionally-present fields.
  • Consensus rules: field presence and the flag bits (including enableCrossAddress at bit 2), with a pointer to ZIP 258 for the rules that gate on NU6.3 activation regardless of transaction version.
  • Transaction identifiers, signature hashing, and block commitments: the Ironwood txid and auth digests with their 16-byte personalizations; the v6 move of the Sapling, Orchard, and Ironwood anchors from effecting to authorizing data (binding is via the proofs, not the signatures), with the resulting digest trees and per-node personalization changes; and the hashAuthDataRoot update.
  • Changes to ZIP 221: Ironwood history-tree MMR node fields. (The ZIP 209 / § 4.17 chain-value-pool changes now live in ZIP 258.)

ZIP 258: Deployment of the NU6.3 Network Upgrade

Fixes the NU6.3 activation parameters (activation heights, consensus branch ID 0x37A5165B, v6 version-group ID) and the consensus rules that gate on NU6.3 activation regardless of transaction version:

  • coinbase transactions MUST have an empty Orchard component;
  • every Orchard-pool Action MUST set enableCrossAddress = 0 (enforced by the height-selected Action circuit verifying key, so it also covers Orchard Actions in v5 transactions);
  • no new value may enter the Orchard pool ($\mathsf{v}$OrchardPoolBalance $\geq 0$).

Also: the ZIP 209 Ironwood-chain-value-pool extension (with the corresponding § 4.17 protocol-spec change), ZIP 2005 activation at the NU6.3 height (note-plaintext lead byte 0x03), and the note that zcashd will not implement NU6.3 (so zebra is the full-validator of record). Closes #1304.

ZIP 2005 changes

Retitled to "Ironwood Quantum Recoverability" and aligned with the NU6.3 ZIP set: pool terminology ("Ironwood pool" naming, Raleway Italic pool names), cross-references, and the changes reviewed at the 2026-06-23 ZIP sync.

Status

The ZIPs were reviewed, ACKed, and feedback applied in the 2026-06-23 ZIP sync meeting.

A number of items are deferred to a follow-up PR:

  • move the Changes to ZIP 221 into ZIP 258 (alongside the ZIP 209 changes);
  • ZIP 317 changes: account for Ironwood actions in logical-action / fee accounting (they are counted the same as Orchard actions);
  • the "Signature Hashing" section-title fix;
  • a possible ZIP 246 cross-reference;
  • proof-system wording;
  • clarifying the anchor presence-conditions in the digest definitions;
  • whether the recovery-protocol detail belongs in the Ironwood book.

Open spec item: the [0, MAX_MONEY] chain-value-pool check in the ZIP 209 changes (now in ZIP 258), pending the ZIP 256 update (#1295).

Drafted with the assistance of Claude Opus 4.8 (1M context).

A draft (modelled on ZIP 225) specifying version 6 of the transaction format
for NU6.3: version 5 plus an appended Ironwood bundle, an Orchard-protocol
shielded bundle committing to the Ironwood pool.

Covers the v6 field layout (Ironwood bundle = Orchard bundle shape; no ZIP 233
amount and no per-input sighash info); the consensus rules (lead byte, field
presence, the flag bits including enableCrossAddressOrchard at bit 2, and the
no-new-value-into-Orchard turnstile rule); changes to ZIP 209 and § 4.17 for the
Ironwood chain value pool balance; and the transaction-hashing changes — the
Ironwood txid and auth bundle digests with their 16-byte personalizations, and
the version 6 move of the Orchard and Ironwood anchors from effecting data to
authorizing data.

Open issues remain (the explicit fee field, the enableCrossAddress flag name,
placement of the turnstile rules, and confirmation of the personalization
strings).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
daira added a commit to daira/zips that referenced this pull request Jun 17, 2026
- Title -> "Version 6 Transaction Format"; drop the fee field; coinbase
  empty-Orchard-bundle note; reword the Orchard/Ironwood tree/nullifier-set
  separation.
- Sighash: extend the v6 anchor move (effecting -> auth data) to Sapling as
  well as Orchard and Ironwood; full txid/auth digest trees and the per-node
  personalization table (with _v6 personalizations where the encoding changed).
- Add a "Changes to ZIP 221" section: the Ironwood chain-history MMR node
  fields (hashEarliest/LatestIronwoodRoot, nIronwoodTxCount) [NU6.3 onward],
  mirroring the NU5 Orchard fields.
- Add a ZIP 209 intro citing [^zip-0209]; add the [^zip-0221], [^zip-0252],
  [^zip-0244-txiddigest], and [^zip-0244-authorizingdatacommitment] references.
- Fix the #openissues internal anchor (MMD strips hyphens).

The [0, MAX_MONEY] ZIP 209 change is left as a TODO pending the ZIP 256 update
in zcash#1295.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
- Title -> "Version 6 Transaction Format"; drop the fee field; coinbase
  empty-Orchard-bundle note; reword the Orchard/Ironwood tree/nullifier-set
  separation.
- Sighash: extend the v6 anchor move (effecting -> auth data) to Sapling as
  well as Orchard and Ironwood; full txid/auth digest trees and the per-node
  personalization table (with _v6 personalizations where the encoding changed).
- Add a "Changes to ZIP 221" section: the Ironwood chain-history MMR node
  fields (hashEarliest/LatestIronwoodRoot, nIronwoodTxCount) [NU6.3 onward],
  mirroring the NU5 Orchard fields.
- Add a ZIP 209 intro citing [^zip-0209]; add the [^zip-0221], [^zip-0252],
  [^zip-0244-txiddigest], and [^zip-0244-authorizingdatacommitment] references.
- Fix the #openissues internal anchor (MMD strips hyphens).

The [0, MAX_MONEY] ZIP 209 change is left as a TODO pending the ZIP 256 update
in zcash#1295.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
daira and others added 2 commits June 18, 2026 14:01
…inology

Recoverable notes are now created in the Ironwood pool (introduced by the
version 6 transaction format), not directly in the Orchard pool. Retitle
accordingly, distinguish "Orchard[ZSA] protocol" from the pools, and define
the Ironwood/Orchard pool terms by reference to the v6 transaction format draft.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Substantial revision of the v6 transaction format draft:

- Reframe around the Ironwood pool: Abstract/Motivation/Privacy Implications
  covering quantum recoverability, the supply-integrity motivation, the
  Orchard-address restriction, and the v5-vs-v6 anchor (effecting -> authorizing
  data) rationale; Requirements and Non-requirements reworked.
- Terminology: Orchard protocol vs Orchard pool vs Ironwood pool.
- Consensus rules split out; full txid/auth digest trees and the per-node
  personalization table.
- Resolve all references: split the deployment citations into ZIP 257 (the NU6.2
  deployment / vulnerability) and the NU6.3 deployment draft; add the ZIP 248,
  ZIP 2002, action-circuit-update, deploy-nu6.3, and ironwood-migration
  references; fix the action-circuit-update URL.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
@daira daira changed the title Add draft ZIP: Ironwood Transaction Format Add draft ZIP: Version 6 Transaction Format Jun 18, 2026
@daira daira requested review from ValarDragon, ebfull and nuttycom June 18, 2026 13:15
@TalDerei TalDerei self-requested a review June 18, 2026 13:35
daira and others added 2 commits June 18, 2026 23:55
- Drop the "...Orchard" suffix from the flag bit names: enableSpendsOrchard →
  enableSpends, enableOutputsOrchard → enableOutputs, enableCrossAddressOrchard
  → enableCrossAddress. These bits have the same meaning in both flagsOrchard
  and flagsIronwood, so the suffix was misleading; add a note for the
  rename relative to v5.
- State explicitly that version 4, version 5, and version 6 transactions are
  all valid from NU6.3 onward, and that the Orchard-protocol cross-address
  restriction is enforced for every Orchard-pool Action regardless of
  transaction version, so version 5 cannot be used to bypass it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
…wledgement

- Add a "Note" column to the transaction-format table with †/‡/§/◊ markers
  for conditionally-present fields, and a legend giving each presence
  condition (matching the protocol spec § 7.1 convention). Move the presence
  conditions out of the Consensus Rules into that legend, leaving the 1:1
  proofs/signatures correspondence rule.
- Cosmetic improvements to the table presentations.
- Acknowledge the developers of Penumbra for demonstrating the advantages
  of treating the note commitment tree anchor as authorizing rather than
  effecting data.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>

@TalDerei TalDerei left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some first pass observations over draft.

Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md
Comment on lines +154 to +157
The v6 transaction format need not support ZSAs, the `zip233Amount` field, the explicit
`fee` field, or per-transparent-input sighash information that appeared in the withdrawn
ZIP 230 [^zip-0230], or those features and other extensibility affordances planned for
ZIP 248 [^zip-0248].

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question, wondering what the v6 transaction format's relation to ZIP 246 is (specifically their overlapping digest sections), and whether it warrants a reference?

that the `enableCrossAddress` bit of `flagsOrchard` must be 0; and that
$\mathsf{v}^{\textit{OrchardPoolBalance}}$ must be nonnegative.)

## Transaction Identifiers, Signature Hashing, and Block Commitments

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

misleading section title; mentions "signature hashing", but doesn't define a signature digest like ZIP 244. it correctly defines txid_digest_v6 and auth_digest_v6, but not what spend authorization / binding signatures actually sign in this context.

Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md
Comment on lines +308 to +310
- `sapling_spends_noncompact_digest_v6`, `orchard_digest_v6`, and `ironwood_digest_v6` omit the anchor.
- `sapling_auth_digest_v6`, `orchard_auth_digest_v6`, and `ironwood_auth_digest_v6` additionally commit
to `anchorSapling`, `anchorOrchard`, or `anchorIronwood` respectively, after the existing fields.

@TalDerei TalDerei Jun 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

small spec ambiguity: the way sapling_auth_digest_v6 is defined reads to me like it unconditionally commits to anchorSapling. i get that the serialization table only includes anchorSapling when nSpendsSapling > 0, but it'd be clearer if the digest section carried that condition over explicitly. mostly just trying to keep the consistency local here rather than make readers reason across sections. for instance, i'd need to figure out how to handle the anchor in the case of a transparent to sapling transfer wherenOutputsSapling > 0 && nSpendsSapling == 0.

Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated

* In each of `flagsOrchard` and `flagsIronwood`:
* Bits 3..7 inclusive MUST be 0.
* The semantics of the `enableSpends` and `enableOutputs` bits are as in ZIP 224 [^zip-0224].

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

semantics are normative to ZIP 225 instead of ZIP 224?

Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated

[^zip-0257]: [ZIP 257: Deployment of the Orchard Temporary Vulnerability Mitigation and NU6.2 Network Upgrade](zip-0257.md)

[^zip-2002]: [ZIP 2002: Explicit Fees](zip-2002.rst)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

related to fees, can you remind me why the conventional fee logic in ZIP 317 doesn't need to be modified in an update ZIP to account for ironwood bundles? it may still be worth an explicit note that Ironwood actions are counted the same as Orchard actions for logical action accounting.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Daira in ZIP call says it does

This requires a new transaction version that can hold an **Ironwood component**:
a second Orchard-protocol shielded component that commits to, and spends from, the
Ironwood shielded pool, rather than the Orchard pool. The Ironwood component reuses
the Orchard Action encoding and proof system unchanged. This ZIP defines the

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revisit proof system wording in follow-up

Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md
@daira daira changed the title Add draft ZIP: Version 6 Transaction Format Add draft NU6.3 deployment and Version 6 Transaction Format ZIPs Jun 23, 2026
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated

* In each of `flagsOrchard` and `flagsIronwood`:
* Bits 3..7 inclusive MUST be 0.
* The semantics of the `enableSpends` and `enableOutputs` bits are as in ZIP 224 [^zip-0224].

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The words "flag" or "enableSpends" do not appear in 224, likely as 225 as a ref?

@ValarDragon ValarDragon Jun 23, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed that this does not block merge, it's in the protocol spec

Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md
Comment thread zips/zip-0258.md Outdated
Comment thread zips/zip-0258.md
Comment thread zips/zip-0258.md
: TBD

ACTIVATION_HEIGHT (NU6.3)
: Testnet: TBD

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4096000

@nuttycom says:

ghci> activationDate 4096000 4088173
2026-06-30 16:41:01.781410625 UTC

Comment thread zips/draft-zodl-valargroup-ironwood-txformat.md Outdated
ebfull
ebfull previously approved these changes Jun 23, 2026
ValarDragon
ValarDragon previously approved these changes Jun 23, 2026

@ValarDragon ValarDragon left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, we reviewed in ZIP editor meeting

daira and others added 8 commits June 24, 2026 08:23
draft-zodl-valargroup-ironwood-txformat. Also disambiguate protocol
and pool for some cases.

Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
* Updates to activate QR only for the Ironwood pool, and consequences
  such as being able to identify the QR nullifier set.
* Remove references to ZSAs other than to say that the QR proposal is
  compatible with them.
* Harmonize the Abstract wording with the Motivation section of
  draft-zodl-valargroup-ironwood-txformat.
* Add a note about recovery not being possible from the Sprout,
  Sapling, or Orchard pools.
* Add "It should be possible for wallets to identify what subset of a
  user's funds have been made recoverable." to the Requirements.
* Update the reference timeframe for updates to other ZIPs.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
of funds in shielded pools other than Ironwood.

Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Co-authored-by: Daira-Emma Hopwood <daira@jacaranda.org>
Co-authored-by: Tal Derei <tal@bowe.tech>
Co-authored-by: Dev Ojha <ValarDragon@users.noreply.github.com>
* Set the `Discussions-To` field to zcash#1304
* Add a TODO about updates to ZIP 209.
* Add a section heading before the ZIP 209-related changes to the protocol
  specification.
* Cosmetic line-wrap and header fix.

Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
echo "I want freedom, the right to self-expression, everybody's right to beautiful, radiant things." |sha256sum |head --bytes=8

Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
@ebfull ebfull merged commit 889752f into zcash:main Jun 24, 2026
3 checks passed
@TalDerei

TalDerei commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

post-merge ACK, assuming follow-ups.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[ZIP 258] Deployment of the NU6.3 Network Upgrade

4 participants