Skip to main content

External references

1. Why this chapter exists​

The single most important fact about this codebase is that it does not contain the protocol. The protocol lives in the Zcash Protocol Specification and in the ZIPs. zcashd is one implementation. Always cross-check the code against the spec.

This chapter is the index of external authorities. It is intentionally flat: a reader does not study it linearly; the reader returns to it when chasing a citation.

2. Definitions​

Definition 12.1 (Protocol specification). The Zcash Protocol Specification PDF is the normative description of consensus. Section numbers are stable across revisions. Source LaTeX lives in github.com/zcash/zips/tree/main/protocol.

Definition 12.2 (ZIP). A Zcash Improvement Proposal. Indexed at zips.z.cash. Each is a numbered document describing one protocol-level decision.

3. The references​

The spec​

Every consensus rule in src/main.cpp corresponds to a paragraph in the spec.

ZIPs​

The ZIPs that have shaped zcashd, by area:

Consensus and transaction format​

Funding streams and economics​

  • ZIP-207: funding streams.
  • ZIP-208: Blossom block-target adjustment.
  • ZIP-214: post-Canopy funding-stream addresses.

Addresses and wallet​

Orchard, Halo 2, and post-NU5​

When code says // ZIP-N, open the ZIP. The ZIP says why the code does what it does.

Zcash Foundation​

Electric Coin Company / librustzcash ecosystem​

Mobile and light clients​

Block explorers and tooling​

  • ZcashBlockExplorer (various community forks).
  • zecpages, zecmate (community tooling).

Books and longer reads​

  • The Zerocash paper (Sasson et al., 2014): the original construction underlying Sprout.
  • "Sapling: A Privacy-Preserving Cryptocurrency for the Decentralized Web" (Bowe-Hopwood et al.). Background reading for Sapling.
  • "Halo: Recursive Proof Composition without a Trusted Setup" (Bowe, Grigg, Hopwood, 2019). The basis of Halo 2.
  • Halo 2 book.
  • Orchard book.
  • Zcash User Guide.
  • "Mastering Bitcoin" (Antonopoulos): the Bitcoin Core background zcashd inherits.

Papers worth knowing about​

  • Equihash: Biryukov, Khovratovich, "Equihash: Asymmetric Proof-of-Work Based on the Generalized Birthday Problem", NDSS 2016.
  • BLAKE2: Aumasson, Neves, Wilcox-O'Hearn, Winnerlein, 2013.
  • Pinocchio (PGHR13): the original quadratic-arithmetic-program SNARK used by Sprout.
  • Groth16: Jens Groth, "On the Size of Pairing-Based Non-interactive Arguments", EUROCRYPT 2016. Used by Sapling.
  • BLS12-381: the curve used by Sapling; see the spec and the "BLS12-381 for the rest of us" blog post.
  • Pasta curves: defined by Daira-Emma Hopwood; see the pasta_curves repo.
  • Sinsemilla: defined in the Orchard spec.

Communities and forums​

  • Zcash community forum.
  • Discord.
  • Zcash community calls (Arborist meetings, R&D calls): announced on the forum and on Twitter.
  • IETF / academic venues: papers from ECC researchers and Foundation researchers tend to appear at EUROCRYPT, CRYPTO, S&P, CCS, and on ePrint.

Issue trackers​

When triaging a bug report, check whether the underlying issue is in zcashd, librustzcash, or further upstream. Most cryptographic bugs are upstream.

Disclosure​

  • security@z.cash is the disclosure address.
  • The PGP key is in SECURITY.md.
  • Disclosure policy: RD-Crypto-Spec/Responsible-Disclosure with Zcash-specific deviations described in SECURITY.md (because of counterfeiting-bug subtleties).
  • Bilateral disclosure relationships exist with Zcash Foundation (zebra), Horizen, Komodo, Bitcoin ABC. ZODL will inherit these relationships.

Conventions for citing in commits and PRs​

Reference ZIPs by number (ZIP-244), spec sections by chapter (Spec section 6.3.2), and Bitcoin BIPs by number (BIP-32). Link to GitHub permalinks for code references; link to zips.z.cash/protocol/protocol.pdf for the spec.

For commit messages, follow the repository's existing style (see git log for examples; small subject line under 80 columns, body that explains why and links to the ZIP / issue / PR).

Quick lookup map​

QuestionFirst place to look
What is the activation height for X on mainnet?src/chainparams.cpp::CMainParams
What is the consensus rule for X?the spec, then src/main.cpp
What does this BLAKE2 personalisation mean?zcash_primitives::constants upstream, and the spec
Is this an RPC or a wallet RPC?grep for the command name in src/rpc/ and src/wallet/rpcwallet.cpp
What does this Rust function do on the C++ side?grep for librustzcash_<name> in src/ and check src/rust/include/rust/
Where does Sapling proof verification happen?src/rust/src/sapling.rs (batch) and zcash_proofs::sapling upstream
Why was this changed?git log -p <file> and any linked PR / issue
What is the on-disk format of...?the relevant serialize.h/Serialize overload, plus src/dbwrapper.{h,cpp} for LevelDB key shape

4. Failure modes​

  • Citing a ZIP without reading it. ZIPs are short; read the one being cited. Misciting a ZIP in a PR description sends reviewers in the wrong direction.
  • Citing the spec without giving a section number. "The spec says" is unfalsifiable; "Spec section 4.7.3" is checkable.
  • Linking to a moving branch (main). Use a tag (e.g. v5.5.0-rc1) or a commit SHA. This course pins to v5.5.0-rc1.

5. Spec pointers​

This chapter IS the spec-pointer reference. See section 3.

6. Exercises​

  1. Practice the citation pattern. Write a one-paragraph description of how branch IDs work, citing one ZIP and one code path. Compare to the discussion in Chapter 04.

  2. Find a stale link. Browse the upstream repos linked above and spot any that have moved or archived. Open a PR against this course.

  3. Locate a paper. Find the original BLS12-381 design document and explain why the curve was chosen for Sapling. Hint: the "BLS12-381 for the rest of us" blog post is the entry point.

7. Further reading​