Merge pull request #130 from str4d/crate-docs

Crate documentation updates

.github/workflows/rust.yml

@@ -39,3 +39,18 @@ jobs:
       run: $HOME/.cargo/bin/cargo test --verbose --release --all
     - name: Run slow tests
       run: $HOME/.cargo/bin/cargo test --verbose --release --all -- --ignored
+
+  doc-links:
+    name: Check intra-doc links
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: nightly
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --document-private-items

bellman/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 authors = ["Sean Bowe <ewillbefull@gmail.com>"]
 description = "zk-SNARK library"
+readme = "README.md"
 documentation = "https://github.com/ebfull/bellman"
 homepage = "https://github.com/ebfull/bellman"
 license = "MIT/Apache-2.0"

bellman/README.md

@@ -1,12 +1,23 @@
 # bellman [![Crates.io](https://img.shields.io/crates/v/bellman.svg)](https://crates.io/crates/bellman) #
 
-This is a research project being built for [Zcash](https://z.cash/).
+`bellman` is a crate for building zk-SNARK circuits. It provides circuit traits
+and primitive structures, as well as basic gadget implementations such as
+booleans and number abstractions.
+
+## Roadmap
+
+`bellman` is being refactored into a generic proving library. Currently it is
+pairing-specific, and different types of proving systems need to be implemented
+as sub-modules. After the refactor, `bellman` will be generic using the `ff` and
+`group` crates, while specific proving systems will be separate crates that pull
+in the dependencies they require.
 
 ## License
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

bellman/src/domain.rs

@@ -1,14 +1,15 @@
-//! This module contains an `EvaluationDomain` abstraction for
+//! This module contains an [`EvaluationDomain`] abstraction for performing
-//! performing various kinds of polynomial arithmetic on top of
+//! various kinds of polynomial arithmetic on top of the scalar field.
-//! the scalar field.
 //!
-//! In pairing-based SNARKs like Groth16, we need to calculate
+//! In pairing-based SNARKs like [Groth16], we need to calculate a quotient
-//! a quotient polynomial over a target polynomial with roots
+//! polynomial over a target polynomial with roots at distinct points associated
-//! at distinct points associated with each constraint of the
+//! with each constraint of the constraint system. In order to be efficient, we
-//! constraint system. In order to be efficient, we choose these
+//! choose these roots to be the powers of a 2<sup>n</sup> root of unity in the
-//! roots to be the powers of a 2^n root of unity in the field.
+//! field. This allows us to perform polynomial operations in O(n) by performing
-//! This allows us to perform polynomial operations in O(n)
+//! an O(n log n) FFT over such a domain.
-//! by performing an O(n log n) FFT over such a domain.
+//!
+//! [`EvaluationDomain`]: crate::domain::EvaluationDomain
+//! [Groth16]: https://eprint.iacr.org/2016/260
 
 use ff::{Field, PrimeField, ScalarEngine};
 use group::CurveProjective;

bellman/src/gadgets.rs

@@ -1,3 +1,5 @@
+//! Self-contained sub-circuit implementations for various primitives.
+
 pub mod test;
 
 pub mod blake2s;

bellman/src/gadgets/blake2s.rs

@@ -1,3 +1,7 @@
+//! The [BLAKE2s] hash function with personalization support.
+//!
+//! [BLAKE2s]: https://tools.ietf.org/html/rfc7693
+
 use super::{boolean::Boolean, multieq::MultiEq, uint32::UInt32};
 use crate::{ConstraintSystem, SynthesisError};
 use ff::ScalarEngine;

bellman/src/gadgets/boolean.rs

@@ -1,3 +1,5 @@
+//! Gadgets for allocating bits in the circuit and performing boolean logic.
+
 use ff::{BitIterator, Field, PrimeField, ScalarEngine};
 
 use crate::{ConstraintSystem, LinearCombination, SynthesisError, Variable};

bellman/src/gadgets/lookup.rs

@@ -1,3 +1,5 @@
+//! Window table lookup gadgets.
+
 use ff::{Field, ScalarEngine};
 
 use super::boolean::Boolean;

bellman/src/gadgets/multipack.rs

@@ -1,3 +1,5 @@
+//! Helpers for packing vectors of bits into scalar field elements.
+
 use super::boolean::Boolean;
 use super::num::Num;
 use super::Assignment;

bellman/src/gadgets/num.rs

@@ -1,3 +1,5 @@
+//! Gadgets representing numbers in the scalar field of the underlying curve.
+
 use ff::{BitIterator, Field, PrimeField, PrimeFieldRepr, ScalarEngine};
 
 use crate::{ConstraintSystem, LinearCombination, SynthesisError, Variable};

bellman/src/gadgets/sha256.rs

@@ -1,3 +1,8 @@
+//! Circuits for the [SHA-256] hash function and its internal compression
+//! function.
+//!
+//! [SHA-256]: https://tools.ietf.org/html/rfc6234
+
 use super::boolean::Boolean;
 use super::multieq::MultiEq;
 use super::uint32::UInt32;

bellman/src/gadgets/test/mod.rs

@@ -1,3 +1,5 @@
+//! Helpers for testing circuit implementations.
+
 use ff::{Field, PrimeField, PrimeFieldRepr, ScalarEngine};
 
 use crate::{ConstraintSystem, Index, LinearCombination, SynthesisError, Variable};

bellman/src/gadgets/uint32.rs

@@ -1,3 +1,6 @@
+//! Circuit representation of a [`u32`], with helpers for the [`sha256`]
+//! gadgets.
+
 use ff::{Field, PrimeField, ScalarEngine};
 
 use crate::{ConstraintSystem, LinearCombination, SynthesisError};

bellman/src/groth16/mod.rs

@@ -1,3 +1,7 @@
+//! The [Groth16] proving system.
+//!
+//! [Groth16]: https://eprint.iacr.org/2016/260
+
 use group::{CurveAffine, EncodedPoint};
 use pairing::{Engine, PairingCurveAffine};
 

bellman/src/lib.rs

@@ -1,3 +1,140 @@
+//! `bellman` is a crate for building zk-SNARK circuits. It provides circuit
+//! traits and and primitive structures, as well as basic gadget implementations
+//! such as booleans and number abstractions.
+//!
+//! # Example circuit
+//!
+//! Say we want to write a circuit that proves we know the preimage to some hash
+//! computed using SHA-256d (calling SHA-256 twice). The preimage must have a
+//! fixed length known in advance (because the circuit parameters will depend on
+//! it), but can otherwise have any value. We take the following strategy:
+//!
+//! - Witness each bit of the preimage.
+//! - Compute `hash = SHA-256d(preimage)` inside the circuit.
+//! - Expose `hash` as a public input using multiscalar packing.
+//!
+//! ```
+//! use bellman::{
+//!     gadgets::{
+//!         boolean::{AllocatedBit, Boolean},
+//!         multipack,
+//!         sha256::sha256,
+//!     },
+//!     groth16, Circuit, ConstraintSystem, SynthesisError,
+//! };
+//! use pairing::{bls12_381::Bls12, Engine};
+//! use rand::rngs::OsRng;
+//! use sha2::{Digest, Sha256};
+//!
+//! /// Our own SHA-256d gadget. Input and output are in little-endian bit order.
+//! fn sha256d<E: Engine, CS: ConstraintSystem<E>>(
+//!     mut cs: CS,
+//!     data: &[Boolean],
+//! ) -> Result<Vec<Boolean>, SynthesisError> {
+//!     // Flip endianness of each input byte
+//!     let input: Vec<_> = data
+//!         .chunks(8)
+//!         .map(|c| c.iter().rev())
+//!         .flatten()
+//!         .cloned()
+//!         .collect();
+//!
+//!     let mid = sha256(cs.namespace(|| "SHA-256(input)"), &input)?;
+//!     let res = sha256(cs.namespace(|| "SHA-256(mid)"), &mid)?;
+//!
+//!     // Flip endianness of each output byte
+//!     Ok(res
+//!         .chunks(8)
+//!         .map(|c| c.iter().rev())
+//!         .flatten()
+//!         .cloned()
+//!         .collect())
+//! }
+//!
+//! struct MyCircuit {
+//!     /// The input to SHA-256d we are proving that we know. Set to `None` when we
+//!     /// are verifying a proof (and do not have the witness data).
+//!     preimage: Option<[u8; 80]>,
+//! }
+//!
+//! impl<E: Engine> Circuit<E> for MyCircuit {
+//!     fn synthesize<CS: ConstraintSystem<E>>(self, cs: &mut CS) -> Result<(), SynthesisError> {
+//!         // Compute the values for the bits of the preimage. If we are verifying a proof,
+//!         // we still need to create the same constraints, so we return an equivalent-size
+//!         // Vec of None (indicating that the value of each bit is unknown).
+//!         let bit_values = if let Some(preimage) = self.preimage {
+//!             preimage
+//!                 .into_iter()
+//!                 .map(|byte| (0..8).map(move |i| (byte >> i) & 1u8 == 1u8))
+//!                 .flatten()
+//!                 .map(|b| Some(b))
+//!                 .collect()
+//!         } else {
+//!             vec![None; 80 * 8]
+//!         };
+//!         assert_eq!(bit_values.len(), 80 * 8);
+//!
+//!         // Witness the bits of the preimage.
+//!         let preimage_bits = bit_values
+//!             .into_iter()
+//!             .enumerate()
+//!             // Allocate each bit.
+//!             .map(|(i, b)| {
+//!                 AllocatedBit::alloc(cs.namespace(|| format!("preimage bit {}", i)), b)
+//!             })
+//!             // Convert the AllocatedBits into Booleans (required for the sha256 gadget).
+//!             .map(|b| b.map(Boolean::from))
+//!             .collect::<Result<Vec<_>, _>>()?;
+//!
+//!         // Compute hash = SHA-256d(preimage).
+//!         let hash = sha256d(cs.namespace(|| "SHA-256d(preimage)"), &preimage_bits)?;
+//!
+//!         // Expose the vector of 32 boolean variables as compact public inputs.
+//!         multipack::pack_into_inputs(cs.namespace(|| "pack hash"), &hash)
+//!     }
+//! }
+//!
+//! // Create parameters for our circuit. In a production deployment these would
+//! // be generated securely using a multiparty computation.
+//! let params = {
+//!     let c = MyCircuit { preimage: None };
+//!     groth16::generate_random_parameters::<Bls12, _, _>(c, &mut OsRng).unwrap()
+//! };
+//!
+//! // Prepare the verification key (for proof verification).
+//! let pvk = groth16::prepare_verifying_key(&params.vk);
+//!
+//! // Pick a preimage and compute its hash.
+//! let preimage = [42; 80];
+//! let hash = Sha256::digest(&Sha256::digest(&preimage));
+//!
+//! // Create an instance of our circuit (with the preimage as a witness).
+//! let c = MyCircuit {
+//!     preimage: Some(preimage),
+//! };
+//!
+//! // Create a Groth16 proof with our parameters.
+//! let proof = groth16::create_random_proof(c, &params, &mut OsRng).unwrap();
+//!
+//! // Pack the hash as inputs for proof verification.
+//! let hash_bits = multipack::bytes_to_bits_le(&hash);
+//! let inputs = multipack::compute_multipacking::<Bls12>(&hash_bits);
+//!
+//! // Check the proof!
+//! assert!(groth16::verify_proof(&pvk, &proof, &inputs).unwrap());
+//! ```
+//!
+//! # Roadmap
+//!
+//! `bellman` is being refactored into a generic proving library. Currently it
+//! is pairing-specific, and different types of proving systems need to be
+//! implemented as sub-modules. After the refactor, `bellman` will be generic
+//! using the [`ff`] and [`group`] crates, while specific proving systems will
+//! be separate crates that pull in the dependencies they require.
+
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
+
 #[cfg(feature = "multicore")]
 extern crate crossbeam;
 

bellman/src/multicore.rs

@@ -1,8 +1,9 @@
-//! This is an interface for dealing with the kinds of
+//! An interface for dealing with the kinds of parallel computations involved in
-//! parallel computations involved in bellman. It's
+//! `bellman`. It's currently just a thin wrapper around [`CpuPool`] and
-//! currently just a thin wrapper around CpuPool and
+//! [`crossbeam`] but may be extended in the future to allow for various
-//! crossbeam but may be extended in the future to
+//! parallelism strategies.
-//! allow for various parallelism strategies.
+//!
+//! [`CpuPool`]: futures_cpupool::CpuPool
 
 #[cfg(feature = "multicore")]
 mod implementation {

ff/Cargo.toml

@@ -3,6 +3,7 @@ name = "ff"
 version = "0.4.0"
 authors = ["Sean Bowe <ewillbefull@gmail.com>"]
 description = "Library for building and interfacing with finite fields"
+readme = "README.md"
 documentation = "https://docs.rs/ff/"
 homepage = "https://github.com/ebfull/ff"
 license = "MIT/Apache-2.0"

ff/README.md

@@ -15,11 +15,15 @@ Add the `ff` crate to your `Cargo.toml`:
 ff = "0.4"
 ```
 
-The `ff` crate contains `Field`, `PrimeField`, `PrimeFieldRepr` and `SqrtField` traits. See the **[documentation](https://docs.rs/ff/0.4.0/ff/)** for more.
+The `ff` crate contains `Field`, `PrimeField`, `PrimeFieldRepr` and `SqrtField` traits.
+See the **[documentation](https://docs.rs/ff/)** for more.
 
 ### #![derive(PrimeField)]
 
-If you need an implementation of a prime field, this library also provides a procedural macro that will expand into an efficient implementation of a prime field when supplied with the modulus. `PrimeFieldGenerator` must be an element of Fp of p-1 order, that is also quadratic nonresidue.
+If you need an implementation of a prime field, this library also provides a procedural
+macro that will expand into an efficient implementation of a prime field when supplied
+with the modulus. `PrimeFieldGenerator` must be an element of Fp of p-1 order, that is
+also quadratic nonresidue.
 
 First, enable the `derive` crate feature:
 
@@ -41,13 +45,16 @@ extern crate ff;
 struct Fp(FpRepr);
 ```
 
-And that's it! `Fp` now implements `Field` and `PrimeField`. `Fp` will also implement `SqrtField` if supported. The library implements `FpRepr` itself and derives `PrimeFieldRepr` for it.
+And that's it! `Fp` now implements `Field` and `PrimeField`. `Fp` will also implement
+`SqrtField` if supported. The library implements `FpRepr` itself and derives
+`PrimeFieldRepr` for it.
 
 ## License
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

ff/src/lib.rs

@@ -1,3 +1,7 @@
+//! This crate provides traits for working with finite fields.
+
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
 #![allow(unused_imports)]
 
 #[cfg(feature = "derive")]

group/Cargo.toml

@@ -5,6 +5,7 @@ authors = [
     "Sean Bowe <ewillbefull@gmail.com>",
     "Jack Grigg <jack@z.cash>",
 ]
+readme = "README.md"
 license = "MIT/Apache-2.0"
 
 description = "Elliptic curve group traits and utilities"

group/README.md

@@ -1,10 +1,13 @@
 # group [![Crates.io](https://img.shields.io/crates/v/group.svg)](https://crates.io/crates/group) #
 
+`group` is a crate for working with groups over elliptic curves.
+
 ## License
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

group/src/lib.rs

@@ -1,3 +1,6 @@
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
+
 use ff::{PrimeField, PrimeFieldDecodingError, ScalarEngine, SqrtField};
 use rand::RngCore;
 use std::error::Error;

librustzcash/Cargo.toml

@@ -7,6 +7,7 @@ authors = [
     "Jay Graber <jay@z.cash>",
     "Simon Liu <simon@z.cash>"
 ]
+readme = "README.md"
 edition = "2018"
 
 [lib]

librustzcash/README.md

@@ -1,12 +1,17 @@
 # librustzcash
 
-This repository contains librustzcash, a static library for Zcash code assets written in Rust.
+`librustzcash` is an FFI library crate that exposes the Zcash Rust components to
+the `zcashd` full node.
+
+The FFI API does not have any stability guarantees, and will change as required
+by `zcashd`.
 
 ## License
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

librustzcash/src/rustzcash.rs

@@ -1,3 +1,6 @@
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
+
 use lazy_static;
 
 use ff::{PrimeField, PrimeFieldRepr};

pairing/Cargo.toml

@@ -7,6 +7,7 @@ authors = [
     "Sean Bowe <ewillbefull@gmail.com>",
     "Jack Grigg <jack@z.cash>",
 ]
+readme = "README.md"
 license = "MIT/Apache-2.0"
 
 description = "Pairing-friendly elliptic curve library"

pairing/README.md

@@ -1,6 +1,16 @@
 # pairing [![Crates.io](https://img.shields.io/crates/v/pairing.svg)](https://crates.io/crates/pairing) #
 
-This is a Rust crate for using pairing-friendly elliptic curves. Currently, only the [BLS12-381](https://z.cash/blog/new-snark-curve.html) construction is implemented.
+`pairing` is a crate for using pairing-friendly elliptic curves.
+
+Currently, only the [BLS12-381](https://z.cash/blog/new-snark-curve.html)
+construction is implemented.
+
+## Roadmap
+
+`pairing` is being refactored into a generic library for working with
+pairing-friendly curves. After the refactor, `pairing` will provide basic traits
+for pairing-friendly elliptic curve constructions, while specific curves will be
+in separate crates.
 
 ## [Documentation](https://docs.rs/pairing/)
 
@@ -8,13 +18,15 @@ Bring the `pairing` crate into your project just as you normally would.
 
 ## Security Warnings
 
-This library does not make any guarantees about constant-time operations, memory access patterns, or resistance to side-channel attacks.
+This library does not make any guarantees about constant-time operations, memory
+access patterns, or resistance to side-channel attacks.
 
 ## License
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

pairing/src/bls12_381/mod.rs

@@ -1,3 +1,6 @@
+//! An implementation of the BLS12-381 pairing-friendly elliptic curve
+//! construction.
+
 mod ec;
 mod fq;
 mod fq12;

pairing/src/lib.rs

@@ -1,3 +1,5 @@
+//! A library for working with pairing-friendly curves.
+
 // `clippy` is a code linting tool for improving code quality by catching
 // common mistakes or strange code patterns. If the `cargo-clippy` feature
 // is provided, all compiler warnings are prohibited.
@@ -8,6 +10,8 @@
 #![cfg_attr(feature = "cargo-clippy", allow(clippy::many_single_char_names))]
 #![cfg_attr(feature = "cargo-clippy", allow(clippy::new_without_default))]
 #![cfg_attr(feature = "cargo-clippy", allow(clippy::write_literal))]
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
 // Force public structures to implement Debug
 #![deny(missing_debug_implementations)]
 

zcash_client_backend/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.0"
 authors = [
     "Jack Grigg <jack@z.cash>",
 ]
+readme = "README.md"
 edition = "2018"
 
 [dependencies]

zcash_client_backend/README.md

@@ -1,12 +1,14 @@
 # zcash_client_backend
 
-This library contains Rust structs and traits for creating shielded Zcash light clients.
+This library contains Rust structs and traits for creating shielded Zcash light
+clients.
 
 ## License
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

zcash_client_backend/src/constants/mainnet.rs

@@ -1,3 +1,5 @@
+//! Constants for the Zcash main network.
+
 /// The mainnet coin type for ZEC, as defined by [SLIP 44].
 ///
 /// [SLIP 44]: https://github.com/satoshilabs/slips/blob/master/slip-0044.md
@@ -23,6 +25,6 @@ pub const HRP_SAPLING_EXTENDED_FULL_VIEWING_KEY: &str = "zxviews";
 ///
 /// Defined in section 5.6.4 of the [Zcash Protocol Specification].
 ///
-/// [`PaymentAddress`]: sapling_crypto::primitives::PaymentAddress
+/// [`PaymentAddress`]: zcash_primitives::primitives::PaymentAddress
 /// [Zcash Protocol Specification]: https://github.com/zcash/zips/blob/master/protocol/protocol.pdf
 pub const HRP_SAPLING_PAYMENT_ADDRESS: &str = "zs";

zcash_client_backend/src/constants/testnet.rs

@@ -1,3 +1,5 @@
+//! Constants for the Zcash test network.
+
 /// The testnet coin type for ZEC, as defined by [SLIP 44].
 ///
 /// [SLIP 44]: https://github.com/satoshilabs/slips/blob/master/slip-0044.md
@@ -23,6 +25,6 @@ pub const HRP_SAPLING_EXTENDED_FULL_VIEWING_KEY: &str = "zxviewtestsapling";
 ///
 /// Defined in section 5.6.4 of the [Zcash Protocol Specification].
 ///
-/// [`PaymentAddress`]: sapling_crypto::primitives::PaymentAddress
+/// [`PaymentAddress`]: zcash_primitives::primitives::PaymentAddress
 /// [Zcash Protocol Specification]: https://github.com/zcash/zips/blob/master/protocol/protocol.pdf
 pub const HRP_SAPLING_PAYMENT_ADDRESS: &str = "ztestsapling";

zcash_client_backend/src/lib.rs

@@ -3,6 +3,9 @@
 //! `zcash_client_backend` contains Rust structs and traits for creating shielded Zcash
 //! light clients.
 
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
+
 pub mod constants;
 pub mod encoding;
 pub mod keys;

zcash_primitives/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.0"
 authors = [
     "Jack Grigg <jack@z.cash>",
 ]
+readme = "README.md"
 edition = "2018"
 
 [dependencies]

zcash_primitives/README.md

@@ -6,7 +6,8 @@ This library contains Rust implementations of the Zcash primitives.
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

zcash_primitives/src/block.rs

@@ -1,3 +1,5 @@
+//! Structs and methods for handling Zcash block headers.
+
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use hex;
 use std::fmt;

zcash_primitives/src/block/equihash.rs

@@ -1,3 +1,7 @@
+//! Verification functions for the [Equihash] proof-of-work algorithm.
+//!
+//! [Equihash]: https://zips.z.cash/protocol/protocol.pdf#equihash
+
 use blake2b_simd::{Hash as Blake2bHash, Params as Blake2bParams, State as Blake2bState};
 use byteorder::{BigEndian, LittleEndian, ReadBytesExt, WriteBytesExt};
 use log::error;

zcash_primitives/src/constants.rs

@@ -1,3 +1,5 @@
+//! Various constants used by the Zcash primitives.
+
 /// First 64 bytes of the BLAKE2s input during group hash.
 /// This is chosen to be some random string that we couldn't have anticipated when we designed
 /// the algorithm, for rigidity purposes.

zcash_primitives/src/group_hash.rs

@@ -1,3 +1,7 @@
+//! Implementation of [group hashing into Jubjub][grouphash].
+//!
+//! [grouphash]: https://zips.z.cash/protocol/protocol.pdf#concretegrouphashjubjub
+
 use crate::jubjub::{edwards, JubjubEngine, PrimeOrder};
 
 use ff::PrimeField;

zcash_primitives/src/jubjub/mod.rs

@@ -1,3 +1,6 @@
+//! The [Jubjub] curve for efficient elliptic curve operations in circuits built
+//! over [BLS12-381].
+//!
 //! Jubjub is a twisted Edwards curve defined over the BLS12-381 scalar
 //! field, Fr. It takes the form `-x^2 + y^2 = 1 + dx^2y^2` with
 //! `d = -(10240/10241)`. It is birationally equivalent to a Montgomery
@@ -16,6 +19,9 @@
 //! It is a complete twisted Edwards curve, so the equivalence with
 //! the Montgomery curve forms a group isomorphism, allowing points
 //! to be freely converted between the two forms.
+//!
+//! [Jubjub]: https://zips.z.cash/protocol/protocol.pdf#jubjub
+//! [BLS12-381]: pairing::bls12_381
 
 use ff::{Field, PrimeField, SqrtField};
 use pairing::Engine;

zcash_primitives/src/keys.rs

@@ -1,6 +1,8 @@
 //! Sapling key components.
 //!
-//! Implements section 4.2.2 of the Zcash Protocol Specification.
+//! Implements [section 4.2.2] of the Zcash Protocol Specification.
+//!
+//! [section 4.2.2]: https://zips.z.cash/protocol/protocol.pdf#saplingkeycomponents
 
 use crate::{
     jubjub::{edwards, FixedGenerators, JubjubEngine, JubjubParams, ToUniform, Unknown},

zcash_primitives/src/lib.rs

@@ -1,3 +1,11 @@
+//! *General Zcash primitives.*
+//!
+//! `zcash_primitives` is a library that provides the core structs and functions necessary
+//! for working with Zcash.
+
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
+
 #[macro_use]
 extern crate lazy_static;
 

zcash_primitives/src/pedersen_hash.rs

@@ -1,3 +1,5 @@
+//! Implementation of the Pedersen hash function used in Sapling.
+
 use crate::jubjub::*;
 use ff::{Field, PrimeField, PrimeFieldRepr};
 

zcash_primitives/src/primitives.rs

@@ -1,3 +1,5 @@
+//! Structs for core Zcash primitives.
+
 use ff::{Field, PrimeField, PrimeFieldRepr};
 
 use crate::constants;

zcash_primitives/src/redjubjub.rs

@@ -1,5 +1,7 @@
-//! Implementation of RedJubjub, a specialization of RedDSA to the Jubjub curve.
+//! Implementation of [RedJubjub], a specialization of RedDSA to the Jubjub
-//! See section 5.4.6 of the Sapling protocol specification.
+//! curve.
+//!
+//! [RedJubjub]: https://zips.z.cash/protocol/protocol.pdf#concretereddsa
 
 use crate::jubjub::{edwards::Point, FixedGenerators, JubjubEngine, JubjubParams, Unknown};
 use ff::{Field, PrimeField, PrimeFieldRepr};

zcash_primitives/src/transaction/components.rs

@@ -1,3 +1,5 @@
+//! Structs representing the components within Zcash transactions.
+
 use crate::jubjub::{edwards, Unknown};
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use ff::{PrimeField, PrimeFieldRepr};

zcash_primitives/src/transaction/mod.rs

@@ -1,3 +1,5 @@
+//! Structs and methods for handling Zcash transactions.
+
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use hex;
 use sha2::{Digest, Sha256};

zcash_primitives/src/zip32.rs

@@ -1,3 +1,7 @@
+//! Implementation of [ZIP 32] for hierarchical deterministic key management.
+//!
+//! [ZIP 32]: https://zips.z.cash/zip-0032
+
 use aes::Aes256;
 use blake2b_simd::Params as Blake2bParams;
 use byteorder::{ByteOrder, LittleEndian, ReadBytesExt, WriteBytesExt};

zcash_proofs/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.0"
 authors = [
     "Jack Grigg <jack@z.cash>",
 ]
+readme = "README.md"
 edition = "2018"
 
 [dependencies]

zcash_proofs/README.md

@@ -7,7 +7,8 @@ and verifying proofs.
 
 Licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

zcash_proofs/src/circuit.rs

@@ -1,3 +1,5 @@
+//! Implementations of the Zcash circuits and Zcash-specific gadgets.
+
 pub mod ecc;
 pub mod pedersen_hash;
 

zcash_proofs/src/circuit/ecc.rs

@@ -1,3 +1,5 @@
+//! Gadgets implementing Jubjub elliptic curve operations.
+
 use ff::Field;
 use pairing::Engine;
 

zcash_proofs/src/circuit/pedersen_hash.rs

@@ -1,3 +1,5 @@
+//! Gadget for Zcash's Pedersen hash.
+
 use super::ecc::{EdwardsPoint, MontgomeryPoint};
 use bellman::gadgets::boolean::Boolean;
 use bellman::gadgets::lookup::*;

zcash_proofs/src/circuit/sapling.rs

@@ -1,3 +1,5 @@
+//! The Sapling circuits.
+
 use ff::{Field, PrimeField, PrimeFieldRepr};
 
 use bellman::{Circuit, ConstraintSystem, SynthesisError};

zcash_proofs/src/circuit/sprout/mod.rs

@@ -1,3 +1,15 @@
+//! The "hybrid Sprout" circuit.
+//!
+//! "Hybrid Sprout" refers to the implementation of the [Sprout statement] in
+//! `bellman` for [`groth16`], instead of the [original implementation][oldimpl]
+//! using [`libsnark`] for [BCTV14].
+//!
+//! [Sprout statement]: https://zips.z.cash/protocol/protocol.pdf#joinsplitstatement
+//! [`groth16`]: bellman::groth16
+//! [oldimpl]: https://github.com/zcash/zcash/tree/v2.0.7/src/zcash/circuit
+//! [`libsnark`]: https://github.com/scipr-lab/libsnark
+//! [BCTV14]: https://eprint.iacr.org/2013/879
+
 use bellman::gadgets::boolean::{AllocatedBit, Boolean};
 use bellman::gadgets::multipack::pack_into_inputs;
 use bellman::{Circuit, ConstraintSystem, LinearCombination, SynthesisError};

zcash_proofs/src/lib.rs

@@ -1,3 +1,11 @@
+//! *Zcash circuits and proofs.*
+//!
+//! `zcash_proofs` contains the zk-SNARK circuits used by Zcash, and the APIs for creating
+//! and verifying proofs.
+
+// Catch documentation errors caused by code changes.
+#![deny(intra_doc_link_resolution_failure)]
+
 use bellman::groth16::{prepare_verifying_key, Parameters, PreparedVerifyingKey, VerifyingKey};
 use pairing::bls12_381::Bls12;
 use std::fs::File;

zcash_proofs/src/sapling/mod.rs

@@ -1,3 +1,5 @@
+//! Helpers for creating Sapling proofs.
+
 use pairing::bls12_381::Bls12;
 use zcash_primitives::jubjub::{
     edwards, fs::FsRepr, FixedGenerators, JubjubBls12, JubjubParams, Unknown,