librustzcash Onboarding

Automatically generated content

This documentation is automatically generated using Claude Code. Errors, omissions, and inaccuracies may have been introduced during generation. Treat every claim as a starting point for your own reading of the source, not as authoritative.

The code is the law, always. When in doubt, refer to:

• the source files in the librustzcash workspace,
• the Zcash Protocol Specification,
• the relevant ZIPs.

If you spot an error, please open an issue or a pull request on the onboarding branch.

A graduate-level reading course on librustzcash, with strong focus on the cryptography. Each chapter combines protocol theory (with LaTeX math), pointers into the actual Rust code in the workspace, and references to the canonical specifications (ZIPs, the Zcash Protocol Specification, original papers).

The chapters are ordered as a study plan: you can read them in sequence, but each is also written to be useful on its own as a reference once you know your way around.

How to read this course

LaTeX is rendered via KaTeX (configured in this site). The math is the substance of the chapters, not decoration.

Every chapter has the same skeleton:

1. Motivation in 3-5 sentences.
2. The math: definitions, equations, security games.
3. The implementation: which crates, which modules, which functions.
4. Pointers to the spec (ZIPs, protocol PDF) and seminal papers.
5. Exercises with answers in the code.

Chapters

The course splits into three parts. Part I is the reading course (narrative). Part II goes deeper into bugs, side channels, audits, and operational rigour. Part III is authoritative reference material (key catalog, circuit walk-through).

Part I - Reading course

#	Title	Focus
01	Overview and roadmap	Crate graph, layering, how the pieces fit
02	Zcash protocol foundations	Consensus, value pools, network upgrades, transaction shape
03	Cryptography primer	Groups, pairings, Pedersen, BLAKE2, RedDSA, ZK primer
04	Sprout and Sapling	JoinSplit math, Sapling Spend/Output, Jubjub, BLS12-381, Groth16
05	Orchard and Halo 2	Pointer chapter. The technical material lives in the dedicated orchard and halo2 courses.
06	Keys, addresses, ZIP 32, unified addresses	HD derivation, viewing keys, F4Jumble
07	Transactions, sighash, builder, PCZT	v4/v5/v6 layout, sighash trees, PCZT roles
08	Note encryption	In-band secret distribution, OutCiphertext, KDF
09	Equihash and consensus rules	Generalised birthday, history tree, PoW math
10	Wallet stack	client_backend, scanning, fees, SQLite storage
11	Study plan and exercises	Week-by-week schedule with self-tests

Part II - Deep dives and operational rigour

#	Title	Focus
12	Historical bugs and security incidents	2018 counterfeit bug, ZIP 212, audit findings catalog
13	Cofactors, subgroups, canonical encodings	Jubjub cofactor 8, ZIP 216, subgroup checks
14	Side channels and constant-time	subtle, zeroize, vartime APIs to avoid
15	Trusted setup ceremonies	Powers of Tau, Sapling MPC, toxic waste, Halo 2 alternative
16	Pedersen hash deep dive	Windowed encoding, generators, constraint counts
17	Halo 2 deep dive	Pointer chapter. The technical material lives in the dedicated halo2 course.
18	Anonymity set and metadata	Privacy beyond cryptography: behaviour, network, dummies
19	ZIP catalog and reading order	Curated index of the ZIPs you must know
20	Audits and cross-implementation testing	Public audit reports, test vectors, Zebra / zcashd parity
21	Active research and the road to NU7	v6 tx, ZSAs, ZIP 233 burn, recursion, PQ
22	Cryptographer's code review checklist	The operational checklist for every crypto PR

Part III - Authoritative references

#	Title	Focus
23	The complete key catalog	Every key symbol defined, derived, typed, and located in code
24	Circuits, constraint by constraint	Sapling Spend, Sapling Output, Orchard Action: every clause with its constraint count and the attack each clause prevents

Notation used throughout

• $\mathbb{F}_p$: a prime field of order $p$.
• $\mathbb{G}$: a cyclic group of prime order $q$ written additively.
• $[k]P$: scalar multiplication of point $P$ by scalar $k$.
• $H_\ell(\cdot)$: a hash function with output length $\ell$ bits.
• $\langle \cdot, \cdot \rangle$: a pairing $e : \mathbb{G}_1 \times \mathbb{G}_2 \to \mathbb{G}_T$ when used in pairing contexts.
• $\mathsf{Com}(m; r)$: a commitment to message $m$ with randomness $r$.
• $\mathsf{Enc}_k, \mathsf{Dec}_k$: symmetric encryption/decryption with key $k$.
• \stackrel{\}{\leftarrow}$: uniform random sampling.
• $a \mathbin{\|} b$: byte-string concatenation.

Canonical references

• Zcash Protocol Specification (the "yellow paper"): https://zips.z.cash/protocol/protocol.pdf
• The ZIP index: https://zips.z.cash/
• zcashd consensus implementation (for cross-checking): https://github.com/zcash/zcash
• Zebra (Rust full node): https://github.com/ZcashFoundation/zebra
• sapling-crypto (external repo): https://github.com/zcash/sapling-crypto
• orchard (external repo): https://github.com/zcash/orchard
• halo2 (external repo): https://github.com/zcash/halo2
• The original Zerocash paper: Ben-Sasson et al., 2014.
• The Sapling design notes: https://github.com/zcash/zips/blob/main/protocol/sapling.pdf
• The Halo paper: Bowe, Grigg, Hopwood, 2019.