chore: improve naming and comments (#780)

Author: themighty1

crates/common/src/encoding.rs

@@ -19,6 +19,8 @@ struct Encodings {
 }
 
 /// Transfers the encodings using the provided seed and keys.
+///
+/// The keys must be consistent with the global delta used in the encodings.
 pub async fn transfer(
     ctx: &mut Context,
     secret: &EncoderSecret,
@@ -70,6 +72,8 @@ pub async fn transfer(
 }
 
 /// Receives the encodings using the provided MACs.
+///
+/// The MACs must be consistent with the global delta used in the encodings.
 pub async fn receive(
     ctx: &mut Context,
     sent_macs: impl IntoIterator<Item = &'_ Block>,
@@ -132,7 +136,7 @@ impl EncodingProvider for Provider {
             Direction::Received => &self.recv,
         };
 
-        let mut encoding = Vec::with_capacity(idx.len());
+        let mut encoding = Vec::with_capacity(idx.len() * ENCODING_SIZE);
         for range in idx.iter_ranges() {
             let start = range.start * ENCODING_SIZE;
             let end = range.end * ENCODING_SIZE;

crates/core/src/transcript.rs

@@ -52,7 +52,8 @@ pub use proof::{
     TranscriptProof, TranscriptProofBuilder, TranscriptProofBuilderError, TranscriptProofError,
 };
 
-/// A transcript contains all the data communicated over a TLS connection.
+/// A transcript contains the plaintext of all application data communicated
+/// between the Prover and the Server.
 #[derive(Clone, Serialize, Deserialize)]
 pub struct Transcript {
     /// Data sent from the Prover to the Server.

crates/core/src/transcript/encoding/encoder.rs

@@ -84,7 +84,7 @@ pub trait Encoder {
 
 impl Encoder for ChaChaEncoder {
     fn encode_idx(&self, direction: Direction, idx: &Idx) -> Vec<u8> {
-        // ChaCha20 encoder works with 32-bit words. Each encoded bit is 128 bits long.
+        // ChaCha encoder works with 32-bit words. Each encoded bit is 128 bits long.
         const WORDS_PER_BYTE: u128 = 8 * 128 / 32;
 
         let stream_id: u64 = match direction {

crates/notary/server/src/server.rs

@@ -211,6 +211,7 @@ pub async fn run_server(config: &NotaryServerProperties) -> Result<(), NotarySer
                             .with_upgrades()
                             .await;
                     }
+
                     Err(err) => {
                         error!("{}", NotaryServerError::Connection(err.to_string()));
                     }

crates/prover/src/lib.rs

@@ -275,7 +275,7 @@ impl Prover<state::Setup> {
                         }),
                     };
 
-                // Pull out ZK VM
+                // Pull out ZK VM.
                 let (_, vm) = Arc::into_inner(vm)
                     .expect("vm should have only 1 reference")
                     .into_inner()

crates/prover/src/notarize.rs

@@ -91,7 +91,7 @@ impl Prover<Notarize> {
 
         let attestation = mux_fut
             .poll_with(async {
-                debug!("starting finalization");
+                debug!("sending attestation request");
 
                 ctx.io_mut().send(request.clone()).await?;
 

crates/verifier/src/lib.rs

@@ -223,8 +223,7 @@ impl Verifier<state::Setup> {
         {
             let mut vm = vm.try_lock().expect("VM should not be locked");
 
-            // Prove received plaintext. Prover drops the proof output, as they trust
-            // themselves.
+            // Prepare for the prover to prove received plaintext.
             let proof = commit_records(
                 &mut (*vm.zk()),
                 &mut zk_aes,
@@ -272,7 +271,7 @@ impl Verifier<state::Setup> {
             transcript_length: TranscriptLength { sent, received },
         };
 
-        // Pull out ZK VM
+        // Pull out ZK VM.
         let (_, vm) = Arc::into_inner(vm)
             .expect("vm should have only 1 reference")
             .into_inner()

crates/verifier/src/notarize.rs

@@ -43,13 +43,14 @@ impl Verifier<Notarize> {
                     .sent()
                     .iter()
                     .flat_map(|plaintext| vm.get_keys(*plaintext).expect("reference is valid"))
-                    .map(|mac| mac.as_block());
+                    .map(|key| key.as_block());
                 let recv_keys = transcript_refs
                     .recv()
                     .iter()
                     .flat_map(|plaintext| vm.get_keys(*plaintext).expect("reference is valid"))
-                    .map(|mac| mac.as_block());
+                    .map(|key| key.as_block());
 
+                // Convert encodings into a structured format.
                 encoding::transfer(&mut ctx, &encoder_secret, sent_keys, recv_keys).await?;
 
                 // Receive attestation request, which also contains commitments required before

crates/verifier/src/verify.rs

@@ -62,17 +62,18 @@ impl Verifier<VerifyState> {
 
                 self.state.vm.flush(&mut self.state.ctx).await.unwrap();
 
-                let mut purported_data = Vec::new();
+                let mut authenticated_data = Vec::new();
                 for mut fut in plaintext_futs {
                     let plaintext = fut
                         .try_recv()
                         .map_err(VerifierError::zk)?
                         .expect("plaintext should be decoded");
-                    purported_data.extend_from_slice(&plaintext);
+                    authenticated_data.extend_from_slice(&plaintext);
                 }
 
-                // Check that purported values are correct.
-                if purported_data
+                // Check that the purported data in the partial transcript is
+                // correct.
+                if authenticated_data
                     .into_iter()
                     .zip(
                         partial_transcript