Orchard Onboarding Course

This site is a graduate-level, contribution-oriented reading course on the zcash/orchard crate. Each chapter pairs the math behind a piece of the Orchard shielded protocol with the matching Rust code, the relevant specification, and exercises that force the reader to touch the source. The intended outcome is concrete: read the course, then open a real PR against the crate.

Automatically Generated Content

This site is automatically generated using Claude Code. Errors may have been introduced. This site is not authoritative documentation or explanation of the Orchard shielded protocol. The only authoritative material is what is published by the Zcash-related organisations that maintain the protocol and its reference implementations, in particular the ZIPs and the Zcash Protocol Specification. Anything on this site that disagrees with those sources is wrong on this site, not in them.

Concretely, the authoritative references for everything that follows are:

1. The source files in zcash/orchard, pinned to tag 0.13.1.
2. The Zcash Protocol Specification (Section 4 covers shielded payment components and Section 5.4 covers Orchard).
3. The relevant ZIPs, in particular ZIP 32, ZIP 212, ZIP 224, ZIP 244, and ZIP 316.

To file a correction, open an issue or a pull request on the onboarding branch of the fork: dannywillems/orchard onboarding.

Relationship to the Zcash Protocol Specification

The Zcash Protocol Specification is the canonical, normative reference for everything on this site. It is maintained by the protocol team, updated continuously as ZIPs are accepted, and re-released as a new PDF revision on every substantive change. It already contains every definition, constant, parameter, and pseudocode block that the chapters here rely on, in far more detail and with the formality required for consensus.

Most of the prose on this site is, by design, a paraphrase of the specification. The reason for having a second presentation at all is operational, not editorial:

• HTML, not PDF. Cross-references, full-text search, and responsive layout make the material easier to navigate on a laptop while reading code.
• Links to the source. Every definition that has a Rust counterpart links to the file, line, and pinned commit in zcash/orchard (and to librustzcash, zebrad, or zcashd where relevant). The PDF cannot do this without losing its pin-stability.
• Lives next to the code. This site is generated from Markdown checked in to the onboarding branch of the fork, so a change in the crate can be reflected in the same PR as a change in the prose.

If a statement on this site conflicts with the PDF, the PDF wins. When in doubt, search the PDF first; this site is the contributor-oriented index into it, not a replacement.

How to Read This Course

Chapters are numbered NN-slug.md so the sidebar matches the reading order. Every chapter follows the same seven-section skeleton:

1. Why This Chapter Exists: the question the chapter answers and the file or function the reader will touch by the end.
2. Definitions: formal definitions (KaTeX for math, grammars or state machines otherwise). Downstream chapters cite these by name.
3. The Code: a walkthrough of the implementation with line-anchored live source embeds, annotated with the invariant each block enforces.
4. Failure Modes: what goes wrong if a contributor changes the code without understanding the chapter. Audit findings, CVEs, or historical bugs are cited when available.
5. Spec Pointers: the relevant ZIPs, sections of the Zcash Protocol Specification, and papers, each with the reason it is cited.
6. Exercises: at least three, of which at least one requires the reader to modify code or add a test.
7. Further Reading: optional pointers for going deeper.

The supporting pages at the bottom of the sidebar (Cheat Sheet, PR Checklist, Glossary, Discovery Notes) are not chapters; they are reference material returned to during work.

Prerequisites

The reader is assumed to be comfortable with:

• Finite field arithmetic over $\mathbb{F}_p$ and the basics of elliptic curves over prime fields.
• Discrete-log based cryptography: Pedersen commitments, Schnorr-style signatures, key exchange.
• Cryptographic hash functions and the random oracle model.
• The Rust language at the level of reading a non-trivial crate with #![no_std].

Familiarity with PLONK or Halo 2 is helpful but not required; Chapter 4 (Halo 2 Primer) introduces the parts of PLONKish arithmetisation needed to read src/circuit.rs.

Notation

Used throughout, following the Zcash Protocol Specification.

Symbol	Meaning
$\mathbb{F}_p$	The prime field with $p$ elements
$\mathbb{G}$, $E_p$	A cyclic group; the curve over $\mathbb{F}_p$
$[k] P$	Scalar multiplication of $P$ by $k$
$\mathsf{Com}(m; r)$	Commitment to $m$ with randomness $r$
$x \xleftarrow{R} S$	Sample $x$ uniformly from $S$
$a \mathbin{\Vert} b$	Byte-string concatenation
$\mathsf{Sinsemilla}_D(m)$	Sinsemilla hash of $m$ in domain $D$
$\mathsf{Poseidon}(x_1, \dots, x_n)$	Poseidon permutation output
$q$, $r$	Base / scalar field orders
$\mathsf{Extract}_{\mathbb{P}}(P)$	$x$-coordinate extraction

Pin

All GitHub source links are pinned to upstream tag 0.13.1, commit f8915bc5c8d1c9fa3124ad28bcf73ce232ef3669. See Discovery Notes for the full rationale.

Chapter Index

The sidebar on the left lists every chapter in order. The intended reading path is linear: Chapter 1 maps the crate, Chapter 2 unlocks the contribution loop, and Chapters 3 to 19 each pick one subsystem and follow the seven-section skeleton. Chapter 20 is the six-week study plan that ties everything together.

Before reading chapter 1, two short front-pages set the context:

• Background: From Zerocoin to Orchard explains the lineage. Zcash implements Zerocash (2014), not Zerocoin (2013); Sprout, Sapling, and Orchard each refine the Zerocash note model and replace specific primitives. The page also defines the shielded-pool vocabulary (note, commitment, anchor, nullifier, action) that every later chapter uses without ceremony.
• Names, ZIPs, Issues, and PRs gives the botanical naming convention (Sprout / Sapling / Orchard, formerly Pollard) and a curated index of every external reference the chapters cite.