Add documentation links

README.md

@@ -41,7 +41,7 @@ Note that nightly compilers after `nightly-2024-02-04` will [not work](https://g
 You can examine performance using the benchmarks: either `cargo bench` or `cargo +nightly-2024-02-04 bench`.
 
 Proofs support a custom serialization format designed to be efficient and canonical.
-This functionality has an associated fuzzer that can be run using a nightly compiler: `cargo +nightly-2024-02-04 fuzz run proofs`
+This functionality has an associated fuzzer that can be run using a nightly compiler: `cargo +nightly-2024-02-04 fuzz run proofs`.
 
 ## Warning
 

src/lib.rs

@@ -46,7 +46,7 @@
 //!
 //! Proofs support a custom serialization format designed to be efficient and canonical.
 //! This functionality has an associated fuzzer that can be run using a nightly compiler: `cargo +nightly-2024-02-04
-//! fuzz run proofs`
+//! fuzz run proofs`.
 //!
 //! # Warning
 //!

src/parameters.rs

@@ -16,8 +16,8 @@ use snafu::prelude::*;
 /// Public parameters used for generating and verifying Triptych proofs.
 ///
 /// Parameters require a base and exponent that define the size of verification key vectors, as well as group generators
-/// `G` and `U` required by the protocol. You can either use `new` to have these generators defined securely for you, or
-/// use `new_with_generators` if your use case requires specific values for these.
+/// `G` and `U` required by the protocol. You can either use [`Parameters::new`] to have these generators defined
+/// securely for you, or use [`Parameters::new_with_generators`] if your use case requires specific values for these.
 #[allow(non_snake_case)]
 #[derive(Clone, Eq, PartialEq)]
 pub struct Parameters {
@@ -30,7 +30,7 @@ pub struct Parameters {
  hash: Vec<u8>,
 }
 
-/// Errors that can arise relating to `Parameters`.
+/// Errors that can arise relating to [`Parameters`].
 #[derive(Debug, Snafu)]
 pub enum ParameterError {
  /// An invalid parameter was provided.
@@ -39,13 +39,13 @@ pub enum ParameterError {
 }
 
 impl Parameters {
- /// Generate new parameters for Triptych proofs.
+ /// Generate new [`Parameters`] for Triptych proofs.
  ///
  /// The base `n > 1` and exponent `m > 1` define the size of verification key vectors, so it must be the case that
- /// `n**m` does not overflow `u32`. If any of these conditions is not met, returns an error.
+ /// `n**m` does not overflow [`prim@u32`]. If any of these conditions is not met, returns a [`ParameterError`].
  ///
  /// This function produces group generators `G` and `U` for you.
- /// If your use case requires specific generators, use `new_with_generators` instead.
+ /// If your use case requires specific generators, use [`Parameters::new_with_generators`] instead.
  #[allow(non_snake_case)]
  pub fn new(n: u32, m: u32) -> Result<Self, ParameterError> {
  // Use the default base point for `G` (this is arbitrary)
@@ -61,17 +61,17 @@ impl Parameters {
  Self::new_with_generators(n, m, &G, &U)
  }
 
- /// Generate new parameters for Triptych proofs.
+ /// Generate new [`Parameters`] for Triptych proofs.
  ///
  /// The base `n > 1` and exponent `m > 1` define the size of verification key vectors, so it must be the case that
- /// `n**m` does not overflow `u32`. If any of these conditions is not met, returns an error.
+ /// `n**m` does not overflow [`prim@u32`]. If any of these conditions is not met, returns a [`ParameterError`].
  ///
  /// You must also provide independent group generators `G` and `U`:
  /// - The generator `G` is used to define verification keys.
  /// - The generator `U` is used to define linking tags.
  ///
  /// The security of these generators cannot be checked by this function.
- /// If you'd rather have the generators securely defined for you, use `new` instead.
+ /// If you'd rather have the generators securely defined for you, use [`Parameters::new`] instead.
  #[allow(non_snake_case)]
  pub fn new_with_generators(n: u32, m: u32, G: &RistrettoPoint, U: &RistrettoPoint) -> Result<Self, ParameterError> {
  // These bounds are required by the protocol
@@ -154,37 +154,37 @@ impl Parameters {
  }
  }
 
- /// Get the group generator `G` from these parameters.
+ /// Get the group generator `G` from these [`Parameters`].
  ///
  /// This is the generator used for defining verification keys.
  #[allow(non_snake_case)]
  pub fn get_G(&self) -> &RistrettoPoint {
  &self.G
  }
 
- /// Get the group generator `U` from these parameters.
+ /// Get the group generator `U` from these [`Parameters`].
  ///
  /// This is the generator used for defining linking tags.
  #[allow(non_snake_case)]
  pub fn get_U(&self) -> &RistrettoPoint {
  &self.U
  }
 
- /// Get the value `n` from these parameters.
+ /// Get the value `n` from these [`Parameters`].
  ///
  /// This is the base used for defining the verification key vector size.
  pub fn get_n(&self) -> u32 {
  self.n
  }
 
- /// Get the value `m` from these parameters.
+ /// Get the value `m` from these [`Parameters`].
  ///
  /// This is the exponent used for defining the verification key vector size.
  pub fn get_m(&self) -> u32 {
  self.m
  }
 
- /// Get the value `N == n**m` from these parameters.
+ /// Get the value `N == n**m` from these [`Parameters`].
  ///
  /// This is the verification key vector size.
  #[allow(non_snake_case)]
@@ -193,19 +193,19 @@ impl Parameters {
  self.n.pow(self.m)
  }
 
- /// Get the value `CommitmentG` from these parameters.
+ /// Get the value `CommitmentG` from these [`Parameters`].
  #[allow(non_snake_case)]
  pub(crate) fn get_CommitmentG(&self) -> &Vec<RistrettoPoint> {
  &self.CommitmentG
  }
 
- /// Get the value `CommitmentH` from these parameters.
+ /// Get the value `CommitmentH` from these [`Parameters`].
  #[allow(non_snake_case)]
  pub(crate) fn get_CommitmentH(&self) -> &RistrettoPoint {
  &self.CommitmentH
  }
 
- /// Get a cryptographic hash representation of these parameters, suitable for transcripting.
+ /// Get a cryptographic hash representation of these [`Parameters`], suitable for transcripting.
  pub(crate) fn get_hash(&self) -> &[u8] {
  &self.hash
  }

src/proof.rs

@@ -44,7 +44,7 @@ pub struct Proof {
  z: Scalar,
 }
 
-/// Errors that can arise relating to proofs.
+/// Errors that can arise relating to [`Proof`].
 #[derive(Debug, Snafu)]
 pub enum ProofError {
  /// An invalid parameter was provided.
@@ -91,13 +91,15 @@ fn xi_powers(transcript: &mut Transcript, m: u32) -> Result<Vec<Scalar>, ProofEr
 }
 
 impl Proof {
- /// Generate a Triptych proof, throwing constant-time operations out the window.
+ /// Generate a Triptych [`Proof`].
  ///
- /// The proof is generated by supplying a witness `witness` and corresponding statement `statement`.
+ /// The proof is generated by supplying a [`Witness`] `witness` and corresponding [`Statement`] `statement`.
  /// If the witness and statement do not share the same parameters, or if the statement is invalid for the witness,
- /// returns an error.
+ /// returns a [`ProofError`].
  ///
- /// You must also supply a Merlin `transcript`.
+ /// This function provides a cryptographically-secure random number generator for you.
+ ///
+ /// You must also supply a [`Transcript`] `transcript`.
  ///
  /// This function specifically avoids constant-time operations for efficiency.
  #[cfg(feature = "rand")]
@@ -111,13 +113,13 @@ impl Proof {
  Self::prove_internal(witness, statement, &mut OsRng, transcript, true)
  }
 
- /// Generate a Triptych proof, throwing constant-time operations out the window.
+ /// Generate a Triptych [`Proof`].
  ///
- /// The proof is generated by supplying a witness `witness` and corresponding statement `statement`.
+ /// The proof is generated by supplying a [`Witness`] `witness` and corresponding [`Statement`] `statement`.
  /// If the witness and statement do not share the same parameters, or if the statement is invalid for the witness,
- /// returns an error.
+ /// returns a [`ProofError`].
  ///
- /// You must also supply a cryptographically-secure random number generator `rng` and a Merlin `transcript`.
+ /// You must also supply a [`CryptoRngCore`] random number generator `rng` and a [`Transcript`] `transcript`.
  ///
  /// This function specifically avoids constant-time operations for efficiency.
  pub fn prove_with_rng_vartime<R: CryptoRngCore>(
@@ -129,34 +131,33 @@ impl Proof {
  Self::prove_internal(witness, statement, rng, transcript, true)
  }
 
- /// Generate a Triptych proof.
+ /// Generate a Triptych [`Proof`].
  ///
- /// The proof is generated by supplying a witness `witness` and corresponding statement `statement`.
+ /// The proof is generated by supplying a [`Witness`] `witness` and corresponding [`Statement`] `statement`.
  /// If the witness and statement do not share the same parameters, or if the statement is invalid for the witness,
- /// returns an error.
+ /// returns a [`ProofError`].
  ///
  /// This function provides a cryptographically-secure random number generator for you.
  ///
- /// You must also supply a Merlin `transcript`.
+ /// You must also supply a [`Transcript`] `transcript`.
  ///
- /// This function makes some attempt at avoiding timing side-channel attacks.
- /// operations.
+ /// This function makes some attempt at avoiding timing side-channel attacks using constant-time operations.
  #[cfg(feature = "rand")]
  pub fn prove(witness: &Witness, statement: &Statement, transcript: &mut Transcript) -> Result<Self, ProofError> {
  use rand_core::OsRng;
 
  Self::prove_internal(witness, statement, &mut OsRng, transcript, false)
  }
 
- /// Generate a Triptych proof.
+ /// Generate a Triptych [`Proof`].
  ///
- /// The proof is generated by supplying a witness `witness` and corresponding statement `statement`.
+ /// The proof is generated by supplying a [`Witness`] `witness` and corresponding [`Statement`] `statement`.
  /// If the witness and statement do not share the same parameters, or if the statement is invalid for the witness,
- /// returns an error.
+ /// returns a [`ProofError`].
  ///
- /// You must also supply a cryptographically-secure random number generator `rng` and a Merlin `transcript`.
+ /// You must also supply a [`CryptoRngCore`] random number generator `rng` and a [`Transcript`] `transcript`.
  ///
- /// This function makes some attempt at avoiding timing side-channel attacks.
+ /// This function makes some attempt at avoiding timing side-channel attacks using constant-time operations.
  pub fn prove_with_rng<R: CryptoRngCore>(
  witness: &Witness,
  statement: &Statement,
@@ -384,11 +385,12 @@ impl Proof {
  })
  }
 
- /// Verify a Triptych proof.
+ /// Verify a Triptych [`Proof`].
  ///
  /// Verification requires that the `statement` and `transcript` match those used when the proof was generated.
  ///
- /// Returns a boolean that is `true` if and only if the above requirement is met and the proof is valid.
+ /// Returns a [`prim@bool`] that is [`prim@true`] if and only if the above requirement is met and the proof is
+ /// valid.
  pub fn verify(&self, statement: &Statement, transcript: &mut Transcript) -> bool {
  // Verify as a trivial batch
  Self::verify_batch(
@@ -398,13 +400,14 @@ impl Proof {
  )
  }
 
- /// Verify a batch of Triptych proofs that share a common input set and parameters.
+ /// Verify a batch of Triptych [`Proofs`](`Proof`).
  ///
  /// Verification requires that the `statements` and `transcripts` match those used when the `proofs` were generated,
- /// and that they share a common input set and parameters.
+ /// and that they share a common [`InputSet`](`crate::statement::InputSet`) and
+ /// [`Parameters`](`crate::parameters::Parameters`).
  ///
- /// Returns a boolean that is `true` if and only if the above requirements are met and each proof is valid.
- /// If the batch is empty, returns `true`.
+ /// Returns a [`prim@bool`] that is [`prim@true`] if and only if the above requirements are met and each proof is
+ /// valid. If the batch is empty, returns [`prim@true`].
  #[allow(clippy::too_many_lines, non_snake_case)]
  pub fn verify_batch(statements: &[Statement], proofs: &[Proof], transcripts: &mut [Transcript]) -> bool {
  // Check that we have the same number of statements, proofs, and transcripts
@@ -676,7 +679,7 @@ impl Proof {
  RistrettoPoint::vartime_multiscalar_mul(scalars.iter(), points) == RistrettoPoint::identity()
  }
 
- /// Serialize a proof to a canonical byte array.
+ /// Serialize a [`Proof`] to a canonical byte vector.
  #[allow(non_snake_case)]
  pub fn to_bytes(&self) -> Vec<u8> {
  let mut result = Vec::with_capacity(
@@ -718,7 +721,9 @@ impl Proof {
  result
  }
 
- /// Deserialize a proof from a canonical byte slice.
+ /// Deserialize a [`Proof`] from a canonical byte slice.
+ ///
+ /// If `bytes` does not represent a canonical encoding, returns a [`ProofError`].
  #[allow(non_snake_case)]
  pub fn from_bytes(bytes: &[u8]) -> Result<Self, ProofError> {
  // Helper to parse a `u32` from a `u8` iterator

src/statement.rs

@@ -21,7 +21,7 @@ pub struct InputSet {
 }
 
 impl InputSet {
- /// Generate a new input set from a slice `M` of verification keys.
+ /// Generate a new [`InputSet`] from a slice `M` of verification keys.
  #[allow(non_snake_case)]
  pub fn new(M: &[RistrettoPoint]) -> Self {
  // Use `BLAKE3` for the transcript hash
@@ -37,21 +37,21 @@ impl InputSet {
  }
  }
 
- /// Get the verification keys for this input set.
+ /// Get the verification keys for this [`InputSet`].
  pub fn get_keys(&self) -> &[RistrettoPoint] {
  &self.M
  }
 
- /// Get a cryptographic hash representation of this input set, suitable for transcripting.
+ /// Get a cryptographic hash representation of this [`InputSet`], suitable for transcripting.
  pub(crate) fn get_hash(&self) -> &[u8] {
  &self.hash
  }
 }
 
 /// A Triptych proof statement.
 ///
-/// The statement consists of an input set of verification keys and a linking tag.
-/// It also contains parameters that, among other things, enforce the size of the input set.
+/// The statement consists of an [`InputSet`] of verification keys and a linking tag.
+/// It also contains [`Parameters`] that, among other things, enforce the size of the [`InputSet`].
 #[allow(non_snake_case)]
 #[derive(Clone, Eq, PartialEq)]
 pub struct Statement {
@@ -60,7 +60,7 @@ pub struct Statement {
  J: RistrettoPoint,
 }
 
-/// Errors that can arise relating to `Statement`.
+/// Errors that can arise relating to [`Statement`].
 #[derive(Debug, Snafu)]
 pub enum StatementError {
  /// An invalid parameter was provided.
@@ -69,13 +69,15 @@ pub enum StatementError {
 }
 
 impl Statement {
- /// Generate a new Triptych proof statement.
+ /// Generate a new [`Statement`].
  ///
- /// The input set `input_set` must have a verification key vector whose size matches that specified by the
- /// parameters `params`, and which does not contain the identity group element.
- /// If either of these conditions is not met, returns an error.
+ /// The [`InputSet`] `input_set` must have a verification key vector whose size matches that specified by the
+ /// [`Parameters`] `params`, and which does not contain the identity group element.
+ /// If either of these conditions is not met, returns a [`StatementError`].
  ///
- /// The linking tag `J` is assumed to have been computed from witness data or otherwise provided externally.
+ /// The linking tag `J` is assumed to have been computed from
+ /// [`Witness::compute_linking_tag`](`crate::witness::Witness::compute_linking_tag`) data or otherwise provided
+ /// externally.
  #[allow(non_snake_case)]
  pub fn new(
  params: &Arc<Parameters>,
@@ -97,17 +99,17 @@ impl Statement {
  })
  }
 
- /// Get the parameters for this statement.
+ /// Get the parameters for this [`Statement`].
  pub fn get_params(&self) -> &Arc<Parameters> {
  &self.params
  }
 
- /// Get the input set for this statement.
+ /// Get the input set for this [`Statement`].
  pub fn get_input_set(&self) -> &Arc<InputSet> {
  &self.input_set
  }
 
- /// Get the linking tag for this statement.
+ /// Get the linking tag for this [`Statement`].
  #[allow(non_snake_case)]
  pub fn get_J(&self) -> &RistrettoPoint {
  &self.J