diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 300a7ba..cf55d9a 100644 --- a/.github/workflows/rust.yml +++ b/.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 diff --git a/bellman/Cargo.toml b/bellman/Cargo.toml index fe2a55a..3b2a46f 100644 --- a/bellman/Cargo.toml +++ b/bellman/Cargo.toml @@ -1,6 +1,7 @@ [package] authors = ["Sean Bowe "] description = "zk-SNARK library" +readme = "README.md" documentation = "https://github.com/ebfull/bellman" homepage = "https://github.com/ebfull/bellman" license = "MIT/Apache-2.0" diff --git a/bellman/README.md b/bellman/README.md index 659a81c..d64dd9c 100644 --- a/bellman/README.md +++ b/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. diff --git a/bellman/src/domain.rs b/bellman/src/domain.rs index c636855..ddba4f4 100644 --- a/bellman/src/domain.rs +++ b/bellman/src/domain.rs @@ -1,14 +1,15 @@ -//! This module contains an `EvaluationDomain` abstraction for -//! performing various kinds of polynomial arithmetic on top of -//! the scalar field. +//! This module contains an [`EvaluationDomain`] abstraction for performing +//! various kinds of polynomial arithmetic on top of the scalar field. //! -//! In pairing-based SNARKs like Groth16, we need to calculate -//! a quotient polynomial over a target polynomial with roots -//! at distinct points associated with each constraint of the -//! constraint system. In order to be efficient, we choose these -//! roots to be the powers of a 2^n root of unity in the field. -//! This allows us to perform polynomial operations in O(n) -//! by performing an O(n log n) FFT over such a domain. +//! In pairing-based SNARKs like [Groth16], we need to calculate a quotient +//! polynomial over a target polynomial with roots at distinct points associated +//! with each constraint of the constraint system. In order to be efficient, we +//! choose these roots to be the powers of a 2n root of unity in the +//! field. This allows us to perform polynomial operations in O(n) 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; diff --git a/bellman/src/gadgets.rs b/bellman/src/gadgets.rs index cf366df..b0ce734 100644 --- a/bellman/src/gadgets.rs +++ b/bellman/src/gadgets.rs @@ -1,3 +1,5 @@ +//! Self-contained sub-circuit implementations for various primitives. + pub mod test; pub mod blake2s; diff --git a/bellman/src/gadgets/blake2s.rs b/bellman/src/gadgets/blake2s.rs index 96e554b..e98fd55 100644 --- a/bellman/src/gadgets/blake2s.rs +++ b/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; diff --git a/bellman/src/gadgets/boolean.rs b/bellman/src/gadgets/boolean.rs index bbc0d30..e08974d 100644 --- a/bellman/src/gadgets/boolean.rs +++ b/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}; diff --git a/bellman/src/gadgets/lookup.rs b/bellman/src/gadgets/lookup.rs index 8124b22..b83844d 100644 --- a/bellman/src/gadgets/lookup.rs +++ b/bellman/src/gadgets/lookup.rs @@ -1,3 +1,5 @@ +//! Window table lookup gadgets. + use ff::{Field, ScalarEngine}; use super::boolean::Boolean; diff --git a/bellman/src/gadgets/multipack.rs b/bellman/src/gadgets/multipack.rs index 1fa1967..c0dc50e 100644 --- a/bellman/src/gadgets/multipack.rs +++ b/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; diff --git a/bellman/src/gadgets/num.rs b/bellman/src/gadgets/num.rs index b7caf6d..8be5448 100644 --- a/bellman/src/gadgets/num.rs +++ b/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}; diff --git a/bellman/src/gadgets/sha256.rs b/bellman/src/gadgets/sha256.rs index a875513..0c8efea 100644 --- a/bellman/src/gadgets/sha256.rs +++ b/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; diff --git a/bellman/src/gadgets/test/mod.rs b/bellman/src/gadgets/test/mod.rs index fedfe94..47392f1 100644 --- a/bellman/src/gadgets/test/mod.rs +++ b/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}; diff --git a/bellman/src/gadgets/uint32.rs b/bellman/src/gadgets/uint32.rs index cf8e390..a10be6c 100644 --- a/bellman/src/gadgets/uint32.rs +++ b/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}; diff --git a/bellman/src/groth16/mod.rs b/bellman/src/groth16/mod.rs index 44c6f22..1ff152d 100644 --- a/bellman/src/groth16/mod.rs +++ b/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}; diff --git a/bellman/src/lib.rs b/bellman/src/lib.rs index 1445107..a3b577b 100644 --- a/bellman/src/lib.rs +++ b/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>( +//! mut cs: CS, +//! data: &[Boolean], +//! ) -> Result, 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 Circuit for MyCircuit { +//! fn synthesize>(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::, _>>()?; +//! +//! // 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::(c, &mut OsRng).unwrap() +//! }; +//! +//! // Prepare the verification key (for proof verification). +//! let pvk = groth16::prepare_verifying_key(¶ms.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, ¶ms, &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::(&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; diff --git a/bellman/src/multicore.rs b/bellman/src/multicore.rs index ff97e06..ba69b5f 100644 --- a/bellman/src/multicore.rs +++ b/bellman/src/multicore.rs @@ -1,8 +1,9 @@ -//! This is an interface for dealing with the kinds of -//! parallel computations involved in bellman. It's -//! currently just a thin wrapper around CpuPool and -//! crossbeam but may be extended in the future to -//! allow for various parallelism strategies. +//! An interface for dealing with the kinds of parallel computations involved in +//! `bellman`. It's currently just a thin wrapper around [`CpuPool`] and +//! [`crossbeam`] but may be extended in the future to allow for various +//! parallelism strategies. +//! +//! [`CpuPool`]: futures_cpupool::CpuPool #[cfg(feature = "multicore")] mod implementation { diff --git a/ff/Cargo.toml b/ff/Cargo.toml index 93dfb9f..b832581 100644 --- a/ff/Cargo.toml +++ b/ff/Cargo.toml @@ -3,6 +3,7 @@ name = "ff" version = "0.4.0" authors = ["Sean Bowe "] 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" diff --git a/ff/README.md b/ff/README.md index 3efef94..c3127d8 100644 --- a/ff/README.md +++ b/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. diff --git a/ff/src/lib.rs b/ff/src/lib.rs index fb692c2..6be25da 100644 --- a/ff/src/lib.rs +++ b/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")] diff --git a/group/Cargo.toml b/group/Cargo.toml index 2b09f09..f27eb3f 100644 --- a/group/Cargo.toml +++ b/group/Cargo.toml @@ -5,6 +5,7 @@ authors = [ "Sean Bowe ", "Jack Grigg ", ] +readme = "README.md" license = "MIT/Apache-2.0" description = "Elliptic curve group traits and utilities" diff --git a/group/README.md b/group/README.md index 7fadc0b..5c2398b 100644 --- a/group/README.md +++ b/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. diff --git a/group/src/lib.rs b/group/src/lib.rs index 0d50f8a..be78b2a 100644 --- a/group/src/lib.rs +++ b/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; diff --git a/librustzcash/Cargo.toml b/librustzcash/Cargo.toml index 8290191..becdf2a 100644 --- a/librustzcash/Cargo.toml +++ b/librustzcash/Cargo.toml @@ -7,6 +7,7 @@ authors = [ "Jay Graber ", "Simon Liu " ] +readme = "README.md" edition = "2018" [lib] diff --git a/librustzcash/README.md b/librustzcash/README.md index c21ca8e..0d6eeae 100644 --- a/librustzcash/README.md +++ b/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. diff --git a/librustzcash/src/rustzcash.rs b/librustzcash/src/rustzcash.rs index e3a85e4..068b824 100644 --- a/librustzcash/src/rustzcash.rs +++ b/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}; diff --git a/pairing/Cargo.toml b/pairing/Cargo.toml index 8fadb32..1801ffd 100644 --- a/pairing/Cargo.toml +++ b/pairing/Cargo.toml @@ -7,6 +7,7 @@ authors = [ "Sean Bowe ", "Jack Grigg ", ] +readme = "README.md" license = "MIT/Apache-2.0" description = "Pairing-friendly elliptic curve library" diff --git a/pairing/README.md b/pairing/README.md index bf386de..47a25dc 100644 --- a/pairing/README.md +++ b/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. diff --git a/pairing/src/bls12_381/mod.rs b/pairing/src/bls12_381/mod.rs index 8fc6bbd..e6e88dd 100644 --- a/pairing/src/bls12_381/mod.rs +++ b/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; diff --git a/pairing/src/lib.rs b/pairing/src/lib.rs index b5b46e3..89e5873 100644 --- a/pairing/src/lib.rs +++ b/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)] diff --git a/zcash_client_backend/Cargo.toml b/zcash_client_backend/Cargo.toml index 9996a47..6199f2b 100644 --- a/zcash_client_backend/Cargo.toml +++ b/zcash_client_backend/Cargo.toml @@ -4,6 +4,7 @@ version = "0.0.0" authors = [ "Jack Grigg ", ] +readme = "README.md" edition = "2018" [dependencies] diff --git a/zcash_client_backend/README.md b/zcash_client_backend/README.md index da5c9e2..af9a7ff 100644 --- a/zcash_client_backend/README.md +++ b/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. diff --git a/zcash_client_backend/src/constants/mainnet.rs b/zcash_client_backend/src/constants/mainnet.rs index ed90697..f3f020d 100644 --- a/zcash_client_backend/src/constants/mainnet.rs +++ b/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"; diff --git a/zcash_client_backend/src/constants/testnet.rs b/zcash_client_backend/src/constants/testnet.rs index f151110..5379d5a 100644 --- a/zcash_client_backend/src/constants/testnet.rs +++ b/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"; diff --git a/zcash_client_backend/src/lib.rs b/zcash_client_backend/src/lib.rs index 02de4b4..6d1d993 100644 --- a/zcash_client_backend/src/lib.rs +++ b/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; diff --git a/zcash_primitives/Cargo.toml b/zcash_primitives/Cargo.toml index 22e4aca..a026618 100644 --- a/zcash_primitives/Cargo.toml +++ b/zcash_primitives/Cargo.toml @@ -4,6 +4,7 @@ version = "0.0.0" authors = [ "Jack Grigg ", ] +readme = "README.md" edition = "2018" [dependencies] diff --git a/zcash_primitives/README.md b/zcash_primitives/README.md index b284820..02a0c33 100644 --- a/zcash_primitives/README.md +++ b/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. diff --git a/zcash_primitives/src/block.rs b/zcash_primitives/src/block.rs index 28a7441..ecb0e5b 100644 --- a/zcash_primitives/src/block.rs +++ b/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; diff --git a/zcash_primitives/src/block/equihash.rs b/zcash_primitives/src/block/equihash.rs index 2a3bb66..5d40465 100644 --- a/zcash_primitives/src/block/equihash.rs +++ b/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; diff --git a/zcash_primitives/src/constants.rs b/zcash_primitives/src/constants.rs index 39d55f3..37d337d 100644 --- a/zcash_primitives/src/constants.rs +++ b/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. diff --git a/zcash_primitives/src/group_hash.rs b/zcash_primitives/src/group_hash.rs index 8549c5e..6aac847 100644 --- a/zcash_primitives/src/group_hash.rs +++ b/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; diff --git a/zcash_primitives/src/jubjub/mod.rs b/zcash_primitives/src/jubjub/mod.rs index 40938f3..4998a0b 100644 --- a/zcash_primitives/src/jubjub/mod.rs +++ b/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; diff --git a/zcash_primitives/src/keys.rs b/zcash_primitives/src/keys.rs index 8c8a4b1..76914ba 100644 --- a/zcash_primitives/src/keys.rs +++ b/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}, diff --git a/zcash_primitives/src/lib.rs b/zcash_primitives/src/lib.rs index 644d7fb..713ca2b 100644 --- a/zcash_primitives/src/lib.rs +++ b/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; diff --git a/zcash_primitives/src/pedersen_hash.rs b/zcash_primitives/src/pedersen_hash.rs index 835e9c7..690e977 100644 --- a/zcash_primitives/src/pedersen_hash.rs +++ b/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}; diff --git a/zcash_primitives/src/primitives.rs b/zcash_primitives/src/primitives.rs index a336673..af4fa3a 100644 --- a/zcash_primitives/src/primitives.rs +++ b/zcash_primitives/src/primitives.rs @@ -1,3 +1,5 @@ +//! Structs for core Zcash primitives. + use ff::{Field, PrimeField, PrimeFieldRepr}; use crate::constants; diff --git a/zcash_primitives/src/redjubjub.rs b/zcash_primitives/src/redjubjub.rs index 6721b5e..187ebd3 100644 --- a/zcash_primitives/src/redjubjub.rs +++ b/zcash_primitives/src/redjubjub.rs @@ -1,5 +1,7 @@ -//! Implementation of RedJubjub, a specialization of RedDSA to the Jubjub curve. -//! See section 5.4.6 of the Sapling protocol specification. +//! Implementation of [RedJubjub], a specialization of RedDSA to the Jubjub +//! curve. +//! +//! [RedJubjub]: https://zips.z.cash/protocol/protocol.pdf#concretereddsa use crate::jubjub::{edwards::Point, FixedGenerators, JubjubEngine, JubjubParams, Unknown}; use ff::{Field, PrimeField, PrimeFieldRepr}; diff --git a/zcash_primitives/src/transaction/components.rs b/zcash_primitives/src/transaction/components.rs index c0410c4..270bac5 100644 --- a/zcash_primitives/src/transaction/components.rs +++ b/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}; diff --git a/zcash_primitives/src/transaction/mod.rs b/zcash_primitives/src/transaction/mod.rs index 10e935b..4c203c5 100644 --- a/zcash_primitives/src/transaction/mod.rs +++ b/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}; diff --git a/zcash_primitives/src/zip32.rs b/zcash_primitives/src/zip32.rs index 6cbc462..f346625 100644 --- a/zcash_primitives/src/zip32.rs +++ b/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}; diff --git a/zcash_proofs/Cargo.toml b/zcash_proofs/Cargo.toml index 766db63..f47714d 100644 --- a/zcash_proofs/Cargo.toml +++ b/zcash_proofs/Cargo.toml @@ -4,6 +4,7 @@ version = "0.0.0" authors = [ "Jack Grigg ", ] +readme = "README.md" edition = "2018" [dependencies] diff --git a/zcash_proofs/README.md b/zcash_proofs/README.md index 92d9c77..f365c5a 100644 --- a/zcash_proofs/README.md +++ b/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. diff --git a/zcash_proofs/src/circuit.rs b/zcash_proofs/src/circuit.rs index ac7e74c..6d26fa4 100644 --- a/zcash_proofs/src/circuit.rs +++ b/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; diff --git a/zcash_proofs/src/circuit/ecc.rs b/zcash_proofs/src/circuit/ecc.rs index fa4913a..e65d0ed 100644 --- a/zcash_proofs/src/circuit/ecc.rs +++ b/zcash_proofs/src/circuit/ecc.rs @@ -1,3 +1,5 @@ +//! Gadgets implementing Jubjub elliptic curve operations. + use ff::Field; use pairing::Engine; diff --git a/zcash_proofs/src/circuit/pedersen_hash.rs b/zcash_proofs/src/circuit/pedersen_hash.rs index 409f30e..15cc0c9 100644 --- a/zcash_proofs/src/circuit/pedersen_hash.rs +++ b/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::*; diff --git a/zcash_proofs/src/circuit/sapling.rs b/zcash_proofs/src/circuit/sapling.rs index 08e55e6..aa4b7c8 100644 --- a/zcash_proofs/src/circuit/sapling.rs +++ b/zcash_proofs/src/circuit/sapling.rs @@ -1,3 +1,5 @@ +//! The Sapling circuits. + use ff::{Field, PrimeField, PrimeFieldRepr}; use bellman::{Circuit, ConstraintSystem, SynthesisError}; diff --git a/zcash_proofs/src/circuit/sprout/mod.rs b/zcash_proofs/src/circuit/sprout/mod.rs index 959ec78..1877047 100644 --- a/zcash_proofs/src/circuit/sprout/mod.rs +++ b/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}; diff --git a/zcash_proofs/src/lib.rs b/zcash_proofs/src/lib.rs index a83964a..0a1f9f2 100644 --- a/zcash_proofs/src/lib.rs +++ b/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; diff --git a/zcash_proofs/src/sapling/mod.rs b/zcash_proofs/src/sapling/mod.rs index 9aa62f1..60ffd9b 100644 --- a/zcash_proofs/src/sapling/mod.rs +++ b/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,