[ZIP 307] Update out-of-date light client protocol definition.#1202
Open
nuttycom wants to merge 13 commits into
Open
[ZIP 307] Update out-of-date light client protocol definition.#1202nuttycom wants to merge 13 commits into
nuttycom wants to merge 13 commits into
Conversation
…parent
Broaden from Sapling-only to cover Sapling, Orchard, and transparent balance
tracking. Remove forward-looking language ("this proposal") in favor of
describing the deployed system.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…tocol references Remove the inline CompactBlock protobuf definitions and CompactTxStreamer service definition. Replace with references to the Zcash Light Client Protocol repository as the normative source. Add a brief summary of the major protocol versions (v0.3.x Orchard, v0.4.x transparent). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Generalize the output and spend compression sections to cover both Sapling and Orchard. Add byte counts for Orchard CompactOrchardAction (148 bytes vs 820 full). Note that Orchard Actions combine spend and output into a single description. Replace Sapling-only language throughout. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace the prescriptive incremental witness algorithm with a general description of the witness maintenance requirement. Note the availability of GetSubtreeRoots for constructing witnesses without scanning the entire chain. Update spend detection to reference both CompactSaplingSpend and CompactOrchardAction nullifiers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace the prescriptive four-phase interaction model with a general description of the operations a light client must perform: trial decryption, nullifier matching, and note commitment tree maintenance. Add a section on full transaction retrieval with privacy recommendations (Tor, Nym). Update pre-existing key import to cover seeds, FVKs, and IVKs with wallet birthday height. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add the Orchard compact trial decryption procedure alongside the existing Sapling procedure. The Orchard procedure uses Pallas-based key agreement and derives rho from the nullifier in the same CompactOrchardAction. Restructure the scanning section with separate subsections for each protocol. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Simplify the bucketing section to remove references to the old phase model. Expand transaction privacy to cover the full API surface: tx submission, transparent address queries, and mempool access. Recommend Tor/Nym for privacy-sensitive operations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove unused incremental-witness reference. Add ZIP 212 citation in the Sapling decryption procedure. Update Reference Implementation with current repos. Fix remaining Sapling-only references in High-Level Design, block header validation, and potential extensions sections. Generalize "zcashd" to "Zcash node". Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add "SHOULD NOT" to BCP 14 key words list (used in document but not previously listed). - Fix "the the" double-word typo in Security Model. - Replace stale ``CompactOutputs`` type reference with "compact outputs" in block header validation section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The protocol-saplingdecryptivk and protocol-decryptivk references both pointed to the same protocol spec section. Consolidate to a single reference to eliminate the rst2html5 "Duplicate explicit target name" warning. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
pacu
reviewed
Mar 26, 2026
| been used. If the birthday height is unknown and cannot be estimated by the | ||
| user, the light client SHOULD scan from the activation height of the earliest | ||
| shielded protocol supported by the key (Sapling activation at block 419200 on | ||
| mainnet, or Orchard activation at block 1687104 on mainnet). |
Collaborator
There was a problem hiding this comment.
Shall this include a paragraph about determining wallet birthday for clients initialized with pre-existing keys with no known birthday height?
Example, the light client is initialized with some key and sapling activation but full-sync process determines that the first transaction relevant to this key is block height 875_000, so the wallet birthday of this key is 874_999 (a block prior to the first known transaction block height)
daira
reviewed
Mar 27, 2026
daira
reviewed
Mar 27, 2026
daira
reviewed
Mar 27, 2026
| For each ``CompactSaplingOutput`` $(\mathtt{cmu}, \mathtt{ephemeralKey}, \mathsf{ciphertext})$, | ||
| the light client trial-decrypts with each Sapling incoming viewing key $\mathsf{ivk}$. The | ||
| procedure is a slight deviation from the standard decryption process | ||
| [#protocol-decryptivk]_ (all constants and algorithms are as defined there): |
Collaborator
There was a problem hiding this comment.
The decryption procedure in the protocol spec was refactored (in #962, specifically b9a1c96), in preparation for ZIP 2005. The change was to use an allowedLeadBytes function, rather than duplicating the specification of which lead bytes are allowed at which block height, protocol, and tx version in several places. That change should be reflected here.
Collaborator
There was a problem hiding this comment.
I will also add the required Quantum Recoverability updates for this ZIP to ZIP 2005. Filed as #1242.
Collaborator
There was a problem hiding this comment.
Fixed. This ZIP now only defines the diff from 4.20.2 in the protocol specification, which means that ZIP 2005 does not need to update it (memo bundles or the AssetBase addition would need to update it for the compact output ciphertext length).
daira
reviewed
Mar 27, 2026
daira
reviewed
Mar 27, 2026
daira
reviewed
Mar 27, 2026
daira
reviewed
Mar 27, 2026
Collaborator
zancas
reviewed
Mar 28, 2026
zancas
reviewed
Mar 28, 2026
zancas
reviewed
Mar 28, 2026
zancas
reviewed
Mar 28, 2026
zancas
reviewed
Mar 28, 2026
|
|
||
| - **Proxy server** that extracts block chain data from zcashd to store and serve it in a | ||
| lower-bandwidth format. | ||
| - **Proxy server** that extracts block chain data from a Zcash node to store and serve it |
Contributor
There was a problem hiding this comment.
We use "Indexer" widely:
Proposals:
"Indexing Proxy"
OR
"Indexer"
I prefer more explicit.
This was referenced Mar 31, 2026
daira
reviewed
Apr 2, 2026
daira
reviewed
Apr 2, 2026
daira
reviewed
Apr 2, 2026
daira
reviewed
Apr 2, 2026
daira
reviewed
Apr 2, 2026
daira
reviewed
Apr 2, 2026
… suggestions) Co-authored-by: Daira-Emma Hopwood <daira@jacaranda.org>
daira
reviewed
Apr 3, 2026
daira
reviewed
Apr 3, 2026
daira
force-pushed
the
zip-307-update
branch
2 times, most recently
from
6f98ef1 to
69e06bd
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
procedure rather than specifying the differences from § 4.20.3.
This led to the following unintended differences:
- The procedure described in this ZIP did not support pre-ZIP-212 Sapling
outputs.
- The swapping of domain separators $[4]$ and $[5]$ in the
$\mathsf{PRF^{expand}}$ inputs used to derive $\mathsf{rcm}$ and
$\mathsf{esk}$ for Sapling that was fixed in
[version 2023.4.0 of the protocol specification](https://zips.z.cash/protocol/protocol.pdf#2023.4.0),
had not been fixed in this ZIP.
- The type error that was fixed in
[version 2025.6.2 of the protocol specification](https://zips.z.cash/protocol/protocol.pdf#2025.6.2),
had not been fixed in this ZIP.
- The refactoring to use $\mathsf{allowedLeadBytes}$ also made in version
2025.6.2 had not been applied.
- The last step incorrectly returned $\mathsf{np}$ rather than the note.
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
in a `CompactSaplingOutput` or `CompactOrchardAction`. Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
daira
approved these changes
Apr 3, 2026
daira
left a comment
daira
left a comment
Collaborator
There was a problem hiding this comment.
ACK, except for the last three commits that I wrote.
pacu
approved these changes
Apr 7, 2026
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
4 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.
Once this cleanup is complete, we should migrate ZIP 307 to Active status, as it has been deployed for quite some time.