Skip to content

Commit 9e5f80c

Browse files
committed
chore: add more doc comments
1 parent 1d457c4 commit 9e5f80c

File tree

3 files changed

+59
-5
lines changed

3 files changed

+59
-5
lines changed

eip7594/src/prover.rs

+45-5
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,15 @@ use crate::{
1717
BlobRef, Bytes48Ref, Cell, CellID, CellRef, KZGCommitment, KZGProof,
1818
};
1919

20+
/// Errors that can occur while calling a method in the Prover API
2021
#[derive(Debug)]
2122
pub enum ProverError {
2223
Serialization(SerializationError),
2324
RecoveryFailure(VerifierError),
2425
}
2526

27+
/// Context object that is used to call functions in the prover API.
28+
/// This includes, computing the commitments, proofs and cells.
2629
pub struct ProverContext {
2730
fk20: FK20,
2831
// TODO: We don't need the commit key, since we use FK20 to compute the proofs
@@ -45,8 +48,16 @@ pub struct ProverContext {
4548
impl ProverContext {
4649
pub fn new() -> Self {
4750
let (commit_key, _) = create_eth_commit_opening_keys();
51+
// The number of points that we will make an opening proof for,
52+
// ie a proof will attest to the value of the polynomial at these points.
4853
let point_set_size = FIELD_ELEMENTS_PER_CELL;
54+
55+
// The number of points that we will be making proofs for.
56+
//
57+
// Note: it is easy to calculate the number of proofs that we need to make
58+
// by doing number_of_points_to_open / point_set_size.
4959
let number_of_points_to_open = FIELD_ELEMENTS_PER_EXT_BLOB;
60+
5061
let fk20 = FK20::new(&commit_key, point_set_size, number_of_points_to_open);
5162

5263
let poly_domain = Domain::new(FIELD_ELEMENTS_PER_BLOB);
@@ -63,27 +74,43 @@ impl ProverContext {
6374
}
6475
}
6576

77+
/// Computes the KZG commitment to the polynomial represented by the blob.
6678
pub fn blob_to_kzg_commitment(&self, blob: BlobRef) -> Result<KZGCommitment, ProverError> {
79+
// Deserialize the blob into scalars. The blob is in lagrange form.
6780
let mut scalars =
6881
serialization::deserialize_blob_to_scalars(blob).map_err(ProverError::Serialization)?;
82+
83+
// Reverse the order of the scalars, so that they are in normal order.
84+
// ie not in bit-reversed order.
6985
reverse_bit_order(&mut scalars);
7086

87+
// Commit to the polynomial.
7188
let commitment: G1Point = self.commit_key_lagrange.commit_g1(&scalars).into();
89+
90+
// Serialize the commitment.
7291
Ok(serialize_g1_compressed(&commitment))
7392
}
7493

94+
/// Computes the cells and the KZG proofs for the given blob.
7595
pub fn compute_cells_and_kzg_proofs(
7696
&self,
7797
blob: BlobRef,
7898
) -> Result<([Cell; CELLS_PER_EXT_BLOB], [KZGProof; CELLS_PER_EXT_BLOB]), ProverError> {
79-
// Deserialize the blob into scalars (lagrange form)
99+
// Deserialize the blob into scalars. The blob is in lagrange form.
80100
let mut scalars =
81101
serialization::deserialize_blob_to_scalars(blob).map_err(ProverError::Serialization)?;
102+
103+
// Reverse the order of the scalars, so that they are in normal order.
104+
// ie not in bit-reversed order.
82105
reverse_bit_order(&mut scalars);
83106

107+
// Convert the polynomial from lagrange to monomial form.
84108
let poly_coeff = self.poly_domain.ifft_scalars(scalars);
109+
110+
// Compute the proofs and the evaluations of the polynomial.
85111
let (proofs, evaluations) = self.fk20.compute_multi_opening_proofs(poly_coeff);
86112

113+
// Serialize the evaluations into `Cell`s.
87114
let cells = evaluations
88115
.iter()
89116
.map(|eval| serialization::serialize_scalars_to_cell(eval))
@@ -92,6 +119,7 @@ impl ProverContext {
92119
.try_into()
93120
.expect(&format!("expected {} number of cells", CELLS_PER_EXT_BLOB));
94121

122+
// Serialize the proofs into `KZGProof`s.
95123
let proofs: Vec<_> = proofs.iter().map(serialize_g1_compressed).collect();
96124
let proofs: [KZGProof; CELLS_PER_EXT_BLOB] = proofs
97125
.try_into()
@@ -100,15 +128,23 @@ impl ProverContext {
100128
Ok((cells, proofs))
101129
}
102130

131+
#[deprecated(note = "This function is deprecated, use `compute_cells_and_kzg_proofs` instead")]
103132
pub fn compute_cells(&self, blob: BlobRef) -> Result<[Cell; CELLS_PER_EXT_BLOB], ProverError> {
104-
// Deserialize the blob into scalars (lagrange form)
133+
// Deserialize the blob into scalars. The blob is in lagrange form.
105134
let mut scalars =
106135
serialization::deserialize_blob_to_scalars(blob).map_err(ProverError::Serialization)?;
136+
137+
// Reverse the order of the scalars, so that they are in normal order.
138+
// ie not in bit-reversed order.
107139
reverse_bit_order(&mut scalars);
108140

141+
// Convert the polynomial from lagrange to monomial form.
109142
let poly_coeff = self.poly_domain.ifft_scalars(scalars);
143+
144+
// Compute the evaluations of the polynomial at the points that we need to make proofs for.
110145
let evaluations = self.fk20.compute_evaluation_sets(poly_coeff);
111146

147+
// Serialize the evaluations into cells.
112148
let cells = evaluations
113149
.iter()
114150
.map(|eval| serialization::serialize_scalars_to_cell(eval))
@@ -120,24 +156,28 @@ impl ProverContext {
120156
Ok(cells)
121157
}
122158

159+
/// Recovers the cells and computes the KZG proofs, given a subset of cells.
123160
pub fn recover_cells_and_proofs(
124161
&self,
125162
cell_ids: Vec<CellID>,
126163
cells: Vec<CellRef>,
127164
_proofs: Vec<Bytes48Ref>,
128165
) -> Result<([Cell; CELLS_PER_EXT_BLOB], [KZGProof; CELLS_PER_EXT_BLOB]), ProverError> {
166+
// Use erasure decoding to recover all of the cells.
167+
// These will be in serialized form
129168
let cells = self
130169
.verifier_context
131170
.recover_all_cells(cell_ids, cells)
132171
.map_err(|err| ProverError::RecoveryFailure(err))?;
133172

134-
// Concatenate the cells together
173+
// Concatenate the cells together and extract the blob.
135174
let extension_blob = cells.into_iter().flatten().collect::<Vec<_>>();
136175

137-
// We do not need the extension blob, only the blob
138-
// which is the first BYTES_PER_BLOB bytes.
176+
// To compute the proofs, we need the Blob.
177+
// The blob will be the first BYTES_PER_BLOB bytes from the extension blob.
139178
let blob = &extension_blob[..BYTES_PER_BLOB];
140179

180+
// Compute the cells and the proofs for the given blob.
141181
self.compute_cells_and_kzg_proofs(blob)
142182
}
143183
}

eip7594/src/serialization.rs

+1
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ fn deserialize_bytes_to_scalars(bytes: &[u8]) -> Result<Vec<Scalar>, Serializati
2929
}
3030
Ok(scalars)
3131
}
32+
3233
pub(crate) fn deserialize_blob_to_scalars(
3334
blob_bytes: &[u8],
3435
) -> Result<Vec<Scalar>, SerializationError> {

eip7594/src/verifier.rs

+13
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ use kzg_multi_open::{
1818
proof::verify_multi_opening_naive, reverse_bit_order,
1919
};
2020

21+
/// Errors that can occur while calling a method in the Verifier API
2122
#[derive(Debug)]
2223
pub enum VerifierError {
2324
Serialization(SerializationError),
@@ -56,6 +57,7 @@ pub enum VerifierError {
5657
},
5758
}
5859

60+
/// The context object that is used to call functions in the verifier API.
5961
pub struct VerifierContext {
6062
opening_key: OpeningKey,
6163
/// The cosets that we want to verify evaluations against.
@@ -84,6 +86,8 @@ impl VerifierContext {
8486
rs: ReedSolomon::new(FIELD_ELEMENTS_PER_BLOB, EXTENSION_FACTOR),
8587
}
8688
}
89+
90+
/// Verify that a cell is consistent with a commitment using a KZG proof.
8791
pub fn verify_cell_kzg_proof(
8892
&self,
8993
commitment_bytes: Bytes48Ref,
@@ -111,6 +115,11 @@ impl VerifierContext {
111115
}
112116
}
113117

118+
/// This is the batch version of `verify_cell_kzg_proof`.
119+
///
120+
/// Given a collection of commitments, cells and proofs, this functions verifies that
121+
/// the cells are consistent with the commitments using the KZG proofs.
122+
///
114123
// TODO: take a slice instead of vectors here or something opaque like impl Iterator<Item = &[u8]>
115124
pub fn verify_cell_kzg_proof_batch<T: AsRef<[u8]> + Clone>(
116125
&self,
@@ -178,6 +187,10 @@ impl VerifierContext {
178187
Ok(())
179188
}
180189

190+
/// Given a list of cell IDs and cells, this function recovers the missing cells.
191+
#[deprecated(
192+
note = "This method will be removed from the public API, ie made crate private. Use `recover_cells_and_proofs` instead."
193+
)]
181194
pub fn recover_all_cells(
182195
&self,
183196
cell_ids: Vec<CellID>,

0 commit comments

Comments
 (0)