add docs on exported types (#221)

eip7594/src/lib.rs

@@ -8,25 +8,65 @@ mod verifier;
 // Exported types
 //
 pub use errors::Error;
+/// TrustedSetup contains the Structured Reference String(SRS)
+/// needed to make and verify proofs.
 pub use trusted_setup::TrustedSetup;
+/// BlobRef denotes a references to an opaque Blob.
+///
+/// Note: This library never returns a Blob, which is why we
+/// do not have a Blob type.
 pub type BlobRef<'a> = &'a [u8; BYTES_PER_BLOB];
+
+/// Bytes48Ref denotes a reference to an untrusted cryptographic type
+/// that can be represented in 48 bytes. This will be either a
+/// purported KZGProof or a purported KZGCommitment.
 pub type Bytes48Ref<'a> = &'a [u8; 48];
 
+/// Cell contains a group of evaluations on a coset that one would like to
+/// make and verify opening proofs about.
+///
+/// Note: These are heap allocated.
 pub type Cell = Box<[u8; BYTES_PER_CELL]>;
+
+/// CellRef contains a reference to a Cell.
+///
+/// Note: Similar to Blob, the library takes in references
+/// to Cell and returns heap allocated instances as return types.
 pub type CellRef<'a> = &'a [u8; BYTES_PER_CELL];
 
+/// KZGProof denotes a 48 byte commitment to a polynomial
+/// that one can use to prove that a polynomial f(x) was
+/// correctly evaluated on a coset `H` and returned a set of points.
 pub type KZGProof = [u8; BYTES_PER_COMMITMENT];
+
+/// KZGCommitment denotes a 48 byte commitment to a polynomial f(x)
+/// that we would like to make and verify opening proofs about.
 pub type KZGCommitment = [u8; BYTES_PER_COMMITMENT];
+
+/// CellIndex is reference to a Coset.
+///
+/// We are able to use CellIndex instead of the coset because
+/// the prover and verifier both know what the cosets are that
+/// we will be making and verifying opening proofs for.
 pub type CellIndex = u64;
-pub type RowIndex = u64;
+
+/// CommitmentIndex is a reference to a commitment.
+///
+/// In order to make verification cheaper, the verifier will
+/// deduplicate the list of commitments that they need to verify opening proofs for.
+/// They will then refer to a commitment via its position in an array of deduplicated commitments
+/// with the CommitmentIndex.
+///
+/// Note: This is not exposed in the public API.
+pub(crate) type CommitmentIndex = u64;
 
 use constants::{BYTES_PER_BLOB, BYTES_PER_CELL, BYTES_PER_COMMITMENT};
 use prover::ProverContext;
 use rayon::ThreadPool;
 use std::sync::Arc;
 use verifier::VerifierContext;
 
-/// The context that will be used to create and verify proofs.
+/// The context that will be used to create and verify opening proofs.
 #[derive(Debug)]
 pub struct DASContext {
     thread_pool: Arc<ThreadPool>,

eip7594/src/verifier.rs

@@ -203,13 +203,13 @@ mod validation {
     use crate::{
         constants::{BYTES_PER_CELL, CELLS_PER_EXT_BLOB, EXTENSION_FACTOR},
         verifier::VerifierError,
-        Bytes48Ref, CellIndex, CellRef, RowIndex,
+        Bytes48Ref, CellIndex, CellRef, CommitmentIndex,
     };
 
     /// Validation logic for `verify_cell_kzg_proof_batch`
     pub fn verify_cell_kzg_proof_batch(
         deduplicated_commitments_bytes: &[Bytes48Ref],
-        commitment_indices: &[RowIndex],
+        commitment_indices: &[CommitmentIndex],
         cell_indices: &[CellIndex],
         cells: &[CellRef],
         proofs_bytes: &[Bytes48Ref],