Draft: Doc joss

src/semi_avid.rs

@@ -208,16 +208,46 @@ impl<F: PrimeField, G: CurveGroup<ScalarField = F>> std::fmt::Display for Block<
     }
 }
 
-/// compute a recoded block from an arbitrary set of blocks
+/// Compute a recoded block from an arbitrary set of blocks.
 ///
-/// coefficients will be drawn at random, one for each block.
+/// Coefficients will be drawn at random, one for each block. Blocks
+/// must come from the same data.
 ///
-/// if the blocks appear to come from different data, e.g. if the commits are
-/// different, an error will be returned.
+/// > **Note**: this is a wrapper around [`fec::recode_random`]
 ///
-/// > **Note**
-/// >
-/// > this is a wrapper around [`fec::recode_random`].
+/// # Example
+///
+/// ```rust
+/// # use ark_bls12_381::{Fr as F, G1Projective as G};
+/// # use ark_poly::univariate::DensePolynomial as DP;
+/// # use komodo::algebra::linalg::Matrix;
+/// # use komodo::fec::encode;
+/// use komodo::semi_avid::{prove, build, recode, verify};
+/// # use komodo::zk::setup;
+/// #
+/// # let mut rng = ark_std::test_rng();
+/// # let powers = setup::<F, G>(100, &mut rng).unwrap();
+/// #
+/// # let (k, n) = (3, 6_usize);
+/// # let data = b"hello world";
+/// # let encoding_mat: Matrix<F> = Matrix::random(k, n, &mut rng);
+/// # let shards = encode(data, &encoding_mat).unwrap();
+/// # let proof = prove::<F, G, DP<F>>(data, &powers, encoding_mat.height).unwrap();
+///
+/// // get blocks (see the semi_avid::build example for details)
+/// let blocks = build::<F, G, DP<F>>(&shards, &proof);
+///
+/// // recode a block using a subset of the blocks (blocks #0 and #2)
+/// let subset = [blocks[0].clone(), blocks[2].clone()];
+/// let recoded = recode(&subset, &mut rng).unwrap().unwrap();
+/// 
+/// // verify the recoded block
+/// assert!(verify::<F, G, DP<F>>(&recoded, &powers).unwrap());
+/// assert_eq!(recoded.shard.hash, blocks[0].shard.hash);
+/// ```
+///
+/// # Errors
+/// - TODO: document errors
 pub fn recode<F: PrimeField, G: CurveGroup<ScalarField = F>>(
     blocks: &[Block<F, G>],
     rng: &mut impl RngCore,
@@ -244,7 +274,34 @@ pub fn recode<F: PrimeField, G: CurveGroup<ScalarField = F>>(
     }))
 }
 
-/// compute the Semi-AVID proof for some data
+/// Compute the Semi-AVID proof for some data.
+///
+/// # Example
+///
+/// ```rust
+/// use ark_bls12_381::{Fr as F, G1Projective as G};
+/// use ark_poly::univariate::DensePolynomial as DP;
+/// use komodo::algebra::linalg::Matrix;
+/// use komodo::fec::encode;
+/// use komodo::semi_avid::prove;
+/// use komodo::zk::setup;
+///
+/// // get a trusted setup
+/// let mut rng = ark_std::test_rng();
+/// let powers = setup::<F, G>(100, &mut rng).unwrap();
+///
+/// // encode some data
+/// let (k, n) = (3, 6_usize);
+/// let data = b"hello world";
+/// let encoding_mat: Matrix<F> = Matrix::random(k, n, &mut rng);
+/// let shards = encode(data, &encoding_mat).unwrap();
+///
+/// // prove the data
+/// let proof = prove::<F, G, DP<F>>(data, &powers, encoding_mat.height).unwrap();
+/// ```
+///
+/// # Errors
+/// - TODO: document errors
 pub fn prove<F, G, P>(
     bytes: &[u8],
     powers: &Powers<F, G>,
@@ -281,7 +338,41 @@ where
     Ok(commits)
 }
 
-/// attach a Semi-AVID proof to a collection of encoded shards
+/// Attach a Semi-AVID proof to a collection of encoded shards.
+///
+/// # Example
+///
+/// ```rust
+/// # use ark_bls12_381::{Fr as F, G1Projective as G};
+/// # use ark_poly::univariate::DensePolynomial as DP;
+/// # use komodo::algebra::linalg::Matrix;
+/// # use komodo::fec::encode;
+/// use komodo::semi_avid::{prove, build};
+/// # use komodo::zk::setup;
+/// #
+/// # let mut rng = ark_std::test_rng();
+/// # let powers = setup::<F, G>(100, &mut rng).unwrap();
+/// #
+/// # let (k, n) = (3, 6_usize);
+/// # let data = b"hello world";
+/// # let encoding_mat: Matrix<F> = Matrix::random(k, n, &mut rng);
+///
+/// // get shards and proofs (see the `semi_avid::prove` example for details)
+/// let shards = encode(data, &encoding_mat).unwrap();
+/// let proof = prove::<F, G, DP<F>>(data, &powers, encoding_mat.height).unwrap();
+///
+/// // build blocks made of shards and proof
+/// let blocks = build::<F, G, DP<F>>(&shards, &proof);
+///
+/// assert_eq!(blocks.len(), shards.len());
+/// for (i, block) in blocks.iter().enumerate() {
+///     assert_eq!(block.shard, shards[i]);
+///     // assert_eq!(block.proof, proof); // private unaccessible field
+/// }
+/// ```
+///
+/// # Errors
+/// - TODO: document errors
 #[inline(always)]
 pub fn build<F, G, P>(shards: &[Shard<F>], proof: &[Commitment<F, G>]) -> Vec<Block<F, G>>
 where
@@ -299,7 +390,38 @@ where
         .collect::<Vec<_>>()
 }
 
-/// verify that a single block of encoded and proven data is valid
+/// Verify that a single block of encoded and proven data is valid.
+///
+/// # Example
+///
+/// ```rust
+/// # use ark_bls12_381::{Fr as F, G1Projective as G};
+/// # use ark_poly::univariate::DensePolynomial as DP;
+/// # use komodo::algebra::linalg::Matrix;
+/// # use komodo::fec::encode;
+/// use komodo::semi_avid::{prove, build, verify};
+/// # use komodo::zk::setup;
+/// #
+/// # let mut rng = ark_std::test_rng();
+/// # let powers = setup::<F, G>(100, &mut rng).unwrap();
+/// #
+/// # let (k, n) = (3, 6_usize);
+/// # let data = b"hello world";
+/// # let encoding_mat: Matrix<F> = Matrix::random(k, n, &mut rng);
+/// # let shards = encode(data, &encoding_mat).unwrap();
+/// # let proof = prove::<F, G, DP<F>>(data, &powers, encoding_mat.height).unwrap();
+///
+/// // get blocks (see the `semi_avid::build` example for details)
+/// let blocks = build::<F, G, DP<F>>(&shards, &proof);
+///
+/// // verify each block (you need the powers from the setup)
+/// for block in &blocks {
+///    assert!(verify::<F, G, DP<F>>(block, &powers).unwrap());
+/// }
+/// ```
+///
+/// # Errors
+/// - TODO: document errors
 pub fn verify<F, G, P>(
     block: &Block<F, G>,
     verifier_key: &Powers<F, G>,