Skip to content

[ZIP 2005] Update the Quantum Recoverability deployment plan#1207

Open
ValarDragon wants to merge 3 commits into
zcash:mainfrom
valargroup:dev/qr_deployment
Open

[ZIP 2005] Update the Quantum Recoverability deployment plan#1207
ValarDragon wants to merge 3 commits into
zcash:mainfrom
valargroup:dev/qr_deployment

Conversation

@ValarDragon
Copy link
Copy Markdown
Collaborator

@ValarDragon ValarDragon commented Mar 9, 2026

This PR suggests amendments to ZIP 2005 allowing us to get started on getting wallets quantum recoverable very quickly.

TL;DR:

  • Unbundle this change from the v6 transaction format
  • Have wallets upgrade as soon as code is ready to allow receiving QR notes, and make their internal change notes QR
  • After monitoring deployment across all wallets, decide when
  • In Tx format v6, require wallets to only allow receiving QR notes.

Example code for doing this integration (Will properly integration test, and demo on mainnet later in the week w/ @greg0x after further governance work):

Crate Scope
orchard Add a NoteVersion enum
Add QR rcm derivation: RandomSeed::qr_rcm()
Add version-aware note commitment, plaintext encoding, and decryption
Add per-output Builder::add_versioned_output()zcash_primitives (librustzcash)
zcash_client_backend (librustzcash) Calls add_versioned_orchard_output(..., NoteVersion::V3_Qr) for change outputs (ZIP-2005 phase 1)

@ValarDragon
Copy link
Copy Markdown
Collaborator Author

Something that came up is that this will require a keystone firmware update. So deployment strategy needs to be adapted accordingly.

I am testing the UX of keystone firmware updates from my phone, and what we can do to make ZODL alert a user if their keystone isn't updated. There is not yet keystone version negotiation in ZODL, I don't yet have an answer if its possible without a keystone firmware update.

An alternative design would be to adapt QR to not need a note commitment change, e.g. via editing the binding signature which is purely wallet only

str4d
str4d previously requested changes Mar 10, 2026
Copy link
Copy Markdown
Collaborator

@str4d str4d left a comment

Choose a reason for hiding this comment

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

Editorial review as of 5d80e6f in ZIP Sync with @daira, @nuttycom, @aphelionz.

@daira intends to make additional comments.

Comment thread zips/zip-2005.md
Comment on lines +453 to +455
October 2025 (as proposed for the NU6.1 upgrade). Another revision
may be needed to merge with other changes in a future v6 transaction
format (memo bundles [^zip-0231] and
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.

"Revision" has a specific meaning in ZIPs - it is our backwards-incompatible change indicator (similar to major SemVer).

This paragraph is not about making a revision. It is an editorial note, about the fact that once the ZIP transitions from Draft to Proposed, the ZIP Editors will take the updates in this section and apply them to the specified locations, performing the merges with other updates as necessary.

Proposed rewording:

Suggested change
October 2025 (as proposed for the NU6.1 upgrade). Another revision
may be needed to merge with other changes in a future v6 transaction
format (memo bundles [^zip-0231] and
October 2025 (as proposed for the NU6.1 upgrade). It will need to be merged
with any other changes to the note plaintext format in whichever NU deploys the
v6 transaction format (for example, memo bundles [^zip-0231] and/or

Comment thread zips/zip-2005.md
It is described in sections [Usage with FROST] and [Usage with Hardware Wallets].

A new note plaintext version is specified, beginning with a
$\{ \mathtt{0x03} \}$ byte. Wallets are intended to upgrade to
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.

None of the changes in this PR are in the Specification section, which is a sign that this PR is not actually making any normative changes to the ZIP. Changes to Motivation and Deployment are not normative.

At a minimum there needs to be a change to the acceptable versions function, to handle the fact that pre-NU wallets would need to start accepting 0x03 note plaintexts independently of a tx version update (instead of what this ZIP previously was specifying, which was having 0x03 be solely associated with v6 txs).

Comment thread zips/zip-2005.md
external notes.
* There is a risk that if the recipient wallet is not yet phase 1,
they will not receive the payment until they upgrade their wallet
version, and it re-syncs.
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.

This needs to be expressed as a change to the protocol spec's conformance requirements on wallets, and probably also a change to ZIP 315.

Additionally, even Phase 1 would need some defined activation height, even if it is a purely trivial one (e.g. the block height at which this ZIP transitions from Draft to Proposed). Phase 1 doesn't need to worry about this being in the past, because wallets are only sending notes to themselves (so the effective activation height is "whenever the wallet implementor implements Phase 1 and makes an app update"); having a defined activation height just ensures that on recovery, wallets don't try and look for 0x03 earlier than they could have existed.

Comment thread zips/zip-2005.md
Comment on lines +1397 to +1403
We view the risks laid out above worth taking, for the benefit of
getting users quantum recoverable sooner. There were difficulties in
the deployment of [ZIP 212](https://zips.z.cash/zip-0212), which
centered around upgraded wallets not being able to receive funds from
a wallet who did not upgrade during the allotted grace period. This
is fixed here, because within the v5 transaction format, non quantum
recoverable notes will always be accepted by all wallets.
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.

This should be Rationale for the changes to the acceptable versions function, not Deployment.

Comment thread zips/zip-2005.md
Comment on lines +1410 to +1411
features. That note plaintext version would be with $\{\mathsf{0x04}\}$ or
greater.
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.

This is the first time 0x04 is mentioned. It needs to be specified in the Specification section.

Also (from @daira) they are "note plaintext lead bytes", not "note plaintext versions".

Comment thread zips/zip-2005.md
Comment on lines +117 to +136
format change, and no changes to today's Orchard circuit. We roll out
the note plaintext change in two phases, with planned further
restrictions in the eventual v6 transaction format. In Phase 1, every
wallet independently updates to support receiving the new quantum
recoverable note format, and begins using it for internal change
notes. Each wallet is intended to warn the user, that they may see
lower balances if they use the same seed phrase on distinct, old
wallet software. In Phase 2, a coordinated upgrade height is decided
upon, for wallets to begin sending quantum recoverable notes in the
v5 transaction format. In Phase 2, wallets all still accept non
quantum recoverable notes. This deployment is structured such that users can
get quantum recoverability guarantees very quickly, with the only risks to
user funds are:

* During phase 1 and phase 2, if you use the same seed on another older
wallet version, you will see an inaccurate balance on the older
wallet.
* After the phase 2 coordinated upgrade height, if you use an older
wallet that did not upgrade for phase 1, you will not see incoming
payments from phase 2 wallets until you upgrade.
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.

This feels more like Rationale for the spec (which could be done inline as "Rationale for Foo" subsections), mixed with Deployment content (vs the changes to Deployment which as noted are really Specification).

Comment thread zips/zip-2005.md
Comment on lines +58 to +59
future versions of Zcash designed to be so. We call this property
quantum recoverability.
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.

"this property" is ambiguous referent.

@str4d
Copy link
Copy Markdown
Collaborator

str4d commented Mar 10, 2026

An alternative design would be to adapt QR to not need a note commitment change, e.g. via editing the binding signature which is purely wallet only

I see several problems with this:

  • There is only one Orchard binding signature per transaction, but multiple output notes (in particular, zcash_client_backend will shard change into multiple notes for note management purposes). So any process for binding note data into it would need to have visibility into all output notes.
  • We cannot fix the above by relying on the transaction creator to be both the sender and recipient (and knowing all the private details), because in the proposed Phase 2, the external recipient won't know the change note details, and thus can't account for them when checking the note binding.
  • Binding signatures are not included in CompactBlocks, so light client recipients can't check the binding properties of their notes.

It is necessary that recipients can check their notes are correctly bound, and reject 0x03 note plaintexts if not, as otherwise the sender is not correctly ensuring the semantics of that note plaintext format, and may not be getting the QR properties they are assuming (since those QR properties are entirely controlled by the sender).

@ValarDragon
Copy link
Copy Markdown
Collaborator Author

Thank you for all the comments! I'll make changes accordingly.

There is only one Orchard binding signature per transaction, but multiple output notes (in particular, zcash_client_backend will shard change into multiple notes for note management purposes). So any process for binding note data into it would need to have visibility into all output notes.

Your right! We could use the randomness for the signature from esk, which would be action-specific.

The same compact block problem would apply, but the trade-off is somewhat:

  • Make note lead plaintext byte change, and require a keystone update
  • Don't do a lead plaintext byte change, and pack somewhere else
    • Memo
    • randomness of the signature from esk

The only way I can see for how to safely pack data into a compact block without a lead plaintext byte change would be the memo. A candidate strategy would be on receipt of a tx, the wallet downloads the full tx or QR data to determine if its a QR note.

Perhaps the trade-off looks like:

  • Require keystone firmware update for users + have KS wallets avoid QR until they update.
  • Optimistically make wallets do QR via another field
    • At first wallet software may not be able to detect QR from external notes easily
    • Adapt wallet sync to download more data, similar to what is already done with full memo download. (Separate to this, but we already have demo's for using PIR to hide leakage of full memo downloads to a single server)

@str4d
Copy link
Copy Markdown
Collaborator

str4d commented Mar 11, 2026

The only way I can see for how to safely pack data into a compact block without a lead plaintext byte change would be the memo.

CompactBlocks don't contain memos. They are explicitly truncated off to save bandwidth. Besides the fact that changing the truncated length would be a very invasive change within the stack, without an associated tx format change we won't know which ones have the extra data so we'd need to include partially-truncated memos for every participant, creating a type safety nightmare.

@ValarDragon
Copy link
Copy Markdown
Collaborator Author

Ah your right, more accurate would be "only way to detect QR that I can see, in the existing light client protocol, and no note plaintext lead byte change". (Since the full memo is downloaded in the current light client protocol, after trial decrypt)

@daira
Copy link
Copy Markdown
Collaborator

daira commented Mar 14, 2026

An alternative design would be to adapt QR to not need a note commitment change, e.g. via editing the binding signature which is purely wallet only

This can't work. The current note commitment scheme is not post-quantum binding and that's a major part of the problem to be solved, so I think this comment indicates a misunderstanding of what that problem is.

We will not change the semantics of the note plaintext without changing the lead byte. The lead byte is how the creator of the note communicates to the recipient what the semantics are. Also nothing is to be gained by not changing the lead byte, because the recipient would in that case compute the wrong commitment, so it would ignore the note. It does not matter for compatibility whether it ignores the note because of computing the wrong commitment, or it ignores it because of an unrecognized lead byte — but the former is less explicit and less easily debuggable, which is why we will not do it that way.

Comment thread zips/zip-2005.md
Owners: Daira-Emma Hopwood <daira@jacaranda.org>
Jack Grigg <thestr4d@gmail.com>
Credits: Sean Bowe
Credits: Sean Bowe, Dev Ojha
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.

Suggested change
Credits: Sean Bowe, Dev Ojha
Credits: Sean Bowe
Dev Ojha

@nuttycom nuttycom added NU7 proposal F-transaction-v6 Feature: v6 transactions labels Mar 17, 2026
@str4d str4d dismissed their stale review March 31, 2026 21:52

I'm unable to continue reviewing this, so dismissing my review to ensure it doesn't block merging. Someone else will need to review to confirm that the ZIP Editor's comments are addressed, once the relevant changes are made.

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

Labels

F-transaction-v6 Feature: v6 transactions NU7 proposal

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants