$ironwood \leftarrow Setup (1^{λ})$

Ironwood is a new shielded pool, built to restore confidence for all Zcash'rs in the supply integrity of Zcash. It runs a formally verified Orchard circuit.

All code in this workspace is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Concepts

Ironwood is a proposed new shielded value pool for Zcash. It is designed as an Orchard successor pool: it keeps the Orchard action shape, keys, and proof system, while separating Ironwood state from Orchard state and using a new note plaintext format for quantum-recoverable notes.

At a high level, Ironwood introduces:

a new shielded value pool and value balance based on Orchard,
a new note commitment tree and nullifier set,
transaction version 6, which is version 5 with an Ironwood bundle added,
Ironwood quantum-recoverable note plaintexts,
a rule that no funds can flow into Orchard after NU7, and
a circuit update that lets Orchard notes be withdrawn or split into change notes, without allowing new value to enter Orchard.

Relationship To Orchard

Ironwood reuses the Orchard action and zero-knowledge proof structure. This keeps the transition smaller than introducing an entirely new shielded protocol from first principles.

The important distinction is that Ironwood is not "more Orchard state". It has its own value pool, tree, and nullifier set. An Ironwood note is represented with Orchard note machinery, but it is committed into the Ironwood note commitment tree and spent against the Ironwood nullifier set.

This lets existing Orchard receiver and viewing-key infrastructure remain useful while creating a clean state boundary between legacy Orchard funds and Ironwood funds.

Quantum-Recoverable Notes

ZIP 2005 defines the Ironwood note plaintext format with lead byte 0x03. This is the quantum-recoverable note plaintext format.

In wallet-facing code, Ironwood notes are Orchard-shaped notes using the Ironwood note plaintext format. Existing Orchard notes remain ordinary Orchard notes. Ironwood notes use Ironwood tree state when they are spent.

Transaction Version 6

Ironwood is carried by transaction version 6. Transaction version 6 is the same as version 5, except that it adds an Ironwood bundle. A version 6 transaction can contain:

transparent inputs and outputs,
a Sapling bundle,
an Orchard bundle, and
an Ironwood bundle.

Sapling and transparent components are unchanged from version 5. The Orchard and Ironwood bundles follow the same Orchard-style bundle structure, but they are separate bundles in the transaction. Ironwood uses different personalization strings for its transaction and authorization hashes.

Value Movement After NU7

After NU7 activation, no funds can flow into Orchard. Transactions can still spend Orchard funds, and zero-balance Orchard actions are still allowed, but Orchard value balance must not be negative.

Wallet-created payments and change that would previously have produced Orchard outputs are routed to Ironwood after NU7. This moves newly created shielded value into Ironwood while still allowing legacy Orchard notes to be spent.

Preliminaries

Quantum Recoverability

Quantum recoverability is the note-level change that defines Ironwood notes. It does not make the current Orchard-style protocol post-quantum. Instead, it changes how new Orchard-style notes are created so they can be recovered into a future shielded protocol if the current elliptic-curve-based protocol ever has to be disabled.

The threat model is supply integrity. If an attacker can break discrete logarithms on the curves used by Zcash, then the existing Sapling and Orchard note commitments are not binding against that attacker. Even if Zcash later upgraded its proof system and rebuilt note commitments with a post-quantum hash, an attacker could otherwise try to forge a note that was not actually in the commitment tree.

Quantum-recoverable notes address this by changing how note commitment randomness is derived.

Ironwood Notes

ZIP 2005 defines the Ironwood note plaintext format with lead byte 0x03. This is the quantum-recoverable note plaintext format.

Older Orchard notes use note plaintext lead byte 0x02. For those notes, the note commitment randomness is derived from rseed and the note position seed rho.

For Ironwood notes, the randomness is instead derived from the note contents. The derivation binds the randomness to:

the diversifier-derived point,
the recipient public key,
the note value,
rho, and
the note-specific psi value.

In effect, the note contents become part of the randomness derivation.

flowchart LR
    subgraph V2["Orchard note"]
        V2Inputs["rseed, rho"] --> V2Rcm["rcm"]
    end

    subgraph Ironwood["Ironwood / QR note"]
        IronwoodInputs["rseed, gd, pkd, value, rho, psi"] --> IronwoodRcm["rcm"]
    end

    IronwoodRcm --> Future["future recovery statement can check derivation"]

This makes it possible for a future recovery protocol to prove that a recovered note corresponds to a real note with fixed contents, rather than to a forged choice of note fields.

Ironwood outputs are Orchard-style notes using the Ironwood note plaintext format. Ironwood still uses Orchard-shaped actions, receivers, and note encryption. The distinction is that Ironwood notes use the QR note plaintext format, are committed into the Ironwood note commitment tree, and are spent against the Ironwood nullifier set.

What This Does Not Do

Quantum recoverability is not a post-quantum shielded protocol by itself.

It does not:

make current Orchard-style spends post-quantum secure,
define the future recovery protocol in full,
choose a future post-quantum proof system, or
choose a future post-quantum note commitment tree.

It is a forward-compatibility change. The goal is to make funds created as recoverable notes usable by a later recovery protocol, without requiring Zcash to choose that future protocol today.

Why This Matters For Ironwood

Ironwood is the pool where new Orchard-style shielded value goes after NU7. Using Ironwood notes means new Ironwood funds are created in the recoverable format from the start.

This gives Zcash a migration path: existing value can be moved into Ironwood, and Ironwood notes are structured so that a future post-quantum transition has the information it needs to recover those funds.

User Documentation

Design

This page summarizes the main design decisions behind Ironwood.

Goals

Ironwood is intended to introduce a new shielded pool without discarding the parts of Orchard that are still useful. The design therefore separates consensus state while reusing Orchard-shaped actions, proofs, receivers, and wallet infrastructure where possible.

The result is a new pool with a smaller implementation and deployment surface than a fully independent shielded protocol.

New Shielded Pool

Ironwood is a new shielded value pool and value balance based on Orchard. This is consensus-relevant: transactions account for Ironwood value separately from Sapling and Orchard.

Version 6 transactions support the following pools:

transparent,
Sapling,
Orchard, and
Ironwood.

Transaction version 6 is the same as transaction version 5, except that it adds an Ironwood bundle. Sapling, Orchard, and transparent transaction components are otherwise unchanged from version 5.

Separate State

Ironwood has a separate note commitment tree and a separate nullifier set.

This is the main boundary between Orchard and Ironwood. Even though an Ironwood action has the Orchard action shape, its note commitments are appended to the Ironwood tree, and its nullifiers are checked against the Ironwood nullifier set.

This prevents Orchard and Ironwood from sharing anonymity-set state by accident and gives the protocol a clean migration path away from legacy Orchard state.

Orchard-Style Bundle

The Ironwood bundle reuses Orchard action and bundle structure. In the implementation this appears as a second Orchard-shaped bundle with an Ironwood bundle protocol marker.

This means Ironwood inherits:

Orchard action layout,
Orchard authorization structure,
Orchard note encryption shape,
Orchard proof construction, and
Orchard bundle padding behavior.

Quantum recoverability is the only note-level change for new Ironwood outputs. The rest of the bundle structure follows Orchard.

Orchard Circuit Constraint

After NU7, Orchard is constrained so that it can only remove value from Orchard or split existing Orchard notes into change notes. It must not allow new value to enter Orchard.

This means Orchard remains usable for legacy note handling:

an Orchard note can be withdrawn out of Orchard,
an Orchard note can be split into multiple Orchard change notes, and
zero-balance Orchard actions remain possible.

But transactions cannot use Orchard as a destination for newly created value. New shielded outputs that would previously have been Orchard outputs are routed to Ironwood instead.

Quantum-Recoverable Ironwood Notes

ZIP 2005 defines the Ironwood note plaintext format with lead byte 0x03. This is the quantum-recoverable note plaintext format.

This gives Ironwood a concrete note-level distinction while preserving Orchard keys and receiver handling. Wallet code can therefore model Ironwood notes as Orchard-shaped notes, but classify them by note plaintext format:

Orchard notes use the existing Orchard note plaintext format,
Ironwood notes use the Ironwood / QR note plaintext format.

When an Ironwood note is spent, the witness is obtained from the Ironwood note commitment tree, not the Orchard tree.

Version 6 Transaction Format

Transaction version 6 adds the Ironwood bundle to the transaction format. The bundle order is:

transparent bundle,
Sapling bundle,
Orchard bundle,
Ironwood bundle.

The Ironwood bundle uses the same Orchard-style bundle serialization as the Orchard bundle, but is interpreted under the Ironwood protocol context.

Version 6 is the default transaction version for NU7. Version 5 remains the transaction version for NU5 through NU6.2.

Transaction Hashing

Ironwood uses Orchard-style bundle and action hashing, but with Ironwood-specific personalization strings.

This applies to:

Ironwood bundle txid hashing,
Ironwood action compact hashing,
Ironwood action memo hashing,
Ironwood action non-compact hashing, and
Ironwood authorization hashing.

The version 6 transaction ID tree includes an Ironwood digest after the Orchard digest. Empty Ironwood bundles are represented by the Ironwood empty-bundle digest, not by reusing Orchard's empty-bundle digest.

Version 6 signature hashing uses the version 6 transaction hash path. This ensures signatures bind to the Ironwood bundle when it is present.

Post-NU7 Orchard Value Rule

After NU7 activation, no funds can flow into Orchard. Transactions must not have a negative Orchard value balance.

The rule still permits:

spending existing Orchard value,
positive Orchard value balances, where value exits Orchard, and
zero-balance Orchard actions.

This lets wallets spend existing Orchard funds while preventing newly created shielded value from being placed back into Orchard.

Wallet Routing

Wallet-created Orchard receiver outputs are routed to Ironwood after NU7.

Before NU7, an Orchard receiver produces an Orchard output. After NU7, the same receiver produces an Ironwood output using the QR note plaintext format. Change follows the same rule: Orchard change after NU7 is emitted as Ironwood change.

When spending notes, wallets split Orchard-shaped notes by note plaintext format:

Orchard notes use the Orchard anchor and Orchard witness path,
Ironwood notes use the Ironwood anchor and Ironwood witness path.

This allows legacy Orchard notes to migrate out through ordinary spends while ensuring new outputs land in Ironwood.

Wallet Storage And APIs

Ironwood is exposed as a distinct pool in wallet-facing state, while reusing Orchard-shaped note data internally.

Wallet storage tracks:

Ironwood tree metadata,
Ironwood shardtree state,
Ironwood nullifier observations,
Ironwood balances,
Ironwood Orchard-shaped received notes, and
pool-code distinctions for sent and received outputs.

Compact block and lightwallet protocol data also grow Ironwood fields:

Ironwood action data,
Ironwood commitment tree size,
Ironwood tree state, and
Ironwood subtree roots.

This gives light clients enough information to maintain the Ironwood note commitment tree and detect Ironwood spends and outputs independently of Orchard.

PCZT

Partially-created Zcash transactions include an Ironwood bundle in the updated PCZT format.

PCZT version 2 can carry:

transparent data,
Sapling data,
Orchard data, and
Ironwood data.

The PCZT Orchard action fields also include note plaintext version, because verifiers and provers need the note version to reconstruct note commitments.

Open Placeholders

The current design still has placeholders that should be finalized before a production protocol specification:

the NU7 consensus branch ID,
the exact circuit/proof-system changes, if any, beyond Orchard reuse,
final ZIP text for transaction version 6 and Ironwood hashing, and
final activation heights and deployment rules.

Transaction Format

Version 6 follows the version 5 transaction format, with an Ironwood bundle added after the Orchard bundle.

At the transaction ID layer, Ironwood is another child in the transaction hash tree:

flowchart TD
    TxId["txid<br/>ZcashTxHash_ || consensusBranchId"]

    Header["header digest<br/>version, branch ID, lock time, expiry height"]
    Transparent["transparent digest"]
    Sapling["Sapling digest"]
    Orchard["Orchard bundle digest"]
    Ironwood["Ironwood bundle digest"]

    TxId --> Header
    TxId --> Transparent
    TxId --> Sapling
    TxId --> Orchard
    TxId --> Ironwood

The Orchard and Ironwood bundle digests have the same structure. The difference is that Ironwood uses its own personalization strings at each bundle-hash node:

flowchart TD
    OrchardBundle["Orchard bundle digest<br/>ZTxIdOrchardHash"]
    IronwoodBundle["Ironwood bundle digest<br/>ZTxIdIronwd_Hash"]

    subgraph Shape["Same Orchard-style bundle hash shape"]
        Compact["actions compact hash<br/>nf, cmx, epk, compact ciphertext"]
        Memos["actions memo hash<br/>memo ciphertext"]
        NonCompact["actions non-compact hash<br/>cv, rk, remaining ciphertext"]
        Flags["bundle flags"]
        Value["value balance"]
        Anchor["bundle anchor"]
    end

    OrchardBundle --> Compact
    OrchardBundle --> Memos
    OrchardBundle --> NonCompact
    OrchardBundle --> Flags
    OrchardBundle --> Value
    OrchardBundle --> Anchor

    IronwoodBundle -. same fields .-> Compact
    IronwoodBundle -. same fields .-> Memos
    IronwoodBundle -. same fields .-> NonCompact
    IronwoodBundle -. same fields .-> Flags
    IronwoodBundle -. same fields .-> Value
    IronwoodBundle -. same fields .-> Anchor

The same rule applies to authorization hashing: Ironwood follows the Orchard bundle authorization structure, but uses Ironwood-specific personalization strings.

Keyboard shortcuts

The Ironwood Book