chore: fix some variable names and comments (#578)

evm_arithmetization/src/fixed_recursive_verifier.rs

@@ -94,7 +94,7 @@ where
     pub segment_aggregation: SegmentAggregationCircuitData<F, C, D>,
     /// The transaction aggregation circuit, which verifies the aggregation of
     /// two proofs that can either be a segment aggregation representing a
-    /// transaction or an aggregation of transactions.
+    /// batch of transactions or an aggregation of those batches.
     pub txn_aggregation: TxnAggregationCircuitData<F, C, D>,
     /// The block circuit, which verifies a transaction aggregation proof and an
     /// optional previous block proof.

evm_arithmetization/src/generation/mod.rs

@@ -66,8 +66,8 @@ pub struct GenerationInputs {
     /// `gas_used_before`.
     pub gas_used_after: U256,
 
-    /// A None would yield an empty proof, otherwise this contains the encoding
-    /// of a transaction.
+    /// A batch of individually RLP-encoded transactions, which may be empty for
+    /// dummy payloads.
     pub signed_txns: Vec<Vec<u8>>,
     /// Target address for the base fee to be 'burnt', if there is one. If
     /// `None`, then the base fee is directly burnt.

trace_decoder/src/decoding.rs

@@ -24,7 +24,7 @@ use mpt_trie::{
 use crate::{
     hash,
     processed_block_trace::{
-        NodesUsedByTxn, ProcessedBlockTrace, ProcessedTxnInfo, StateWrite, TxnMetaState,
+        NodesUsedByTxnBatch, ProcessedBlockTrace, ProcessedTxnBatchInfo, StateWrite, TxnMetaState,
     },
     typed_mpt::{ReceiptTrie, StateTrie, StorageTrie, TransactionTrie, TrieKey},
     OtherBlockData, PartialTriePreImages, TryIntoExt as TryIntoBounds,
@@ -119,7 +119,7 @@ pub fn into_txn_proof_gen_ir(
 fn update_beacon_block_root_contract_storage(
     trie_state: &mut PartialTrieState<impl StateTrie>,
     delta_out: &mut TrieDeltaApplicationOutput,
-    nodes_used: &mut NodesUsedByTxn,
+    nodes_used: &mut NodesUsedByTxnBatch,
     block_data: &BlockMetadata,
 ) -> anyhow::Result<()> {
     const HISTORY_BUFFER_LENGTH_MOD: U256 = U256([HISTORY_BUFFER_LENGTH.1, 0, 0, 0]);
@@ -251,7 +251,7 @@ fn init_any_needed_empty_storage_tries<'a>(
 
 fn create_minimal_partial_tries_needed_by_txn(
     curr_block_tries: &PartialTrieState<impl StateTrie + Clone + TryIntoBounds<HashedPartialTrie>>,
-    nodes_used_by_txn: &NodesUsedByTxn,
+    nodes_used_by_txn: &NodesUsedByTxnBatch,
     txn_range: Range<usize>,
     delta_application_out: TrieDeltaApplicationOutput,
 ) -> anyhow::Result<TrieInputs> {
@@ -294,7 +294,7 @@ fn create_minimal_partial_tries_needed_by_txn(
 
 fn apply_deltas_to_trie_state(
     trie_state: &mut PartialTrieState<impl StateTrie>,
-    deltas: &NodesUsedByTxn,
+    deltas: &NodesUsedByTxnBatch,
     meta: &[TxnMetaState],
 ) -> anyhow::Result<TrieDeltaApplicationOutput> {
     let mut out = TrieDeltaApplicationOutput::default();
@@ -512,7 +512,7 @@ fn update_trie_state_from_withdrawals<'a>(
 fn process_txn_info(
     txn_range: Range<usize>,
     is_initial_payload: bool,
-    txn_info: ProcessedTxnInfo,
+    txn_info: ProcessedTxnBatchInfo,
     curr_block_tries: &mut PartialTrieState<
         impl StateTrie + Clone + TryIntoBounds<HashedPartialTrie>,
     >,

trace_decoder/src/lib.rs

@@ -104,7 +104,7 @@ use evm_arithmetization::GenerationInputs;
 use keccak_hash::keccak as hash;
 use keccak_hash::H256;
 use mpt_trie::partial_trie::{HashedPartialTrie, OnOrphanedHashNode};
-use processed_block_trace::ProcessedTxnInfo;
+use processed_block_trace::ProcessedTxnBatchInfo;
 use serde::{Deserialize, Serialize};
 use typed_mpt::{StateMpt, StateTrie as _, StorageTrie, TrieKey};
 
@@ -434,7 +434,7 @@ pub fn entrypoint(
         .collect::<Result<Vec<_>, _>>()?;
 
     while txn_info.len() < 2 {
-        txn_info.push(ProcessedTxnInfo::default());
+        txn_info.push(ProcessedTxnBatchInfo::default());
     }
 
     decoding::into_txn_proof_gen_ir(

trace_decoder/src/processed_block_trace.rs

@@ -14,10 +14,11 @@ use crate::{ContractCodeUsage, TxnInfo};
 const FIRST_PRECOMPILE_ADDRESS: U256 = U256([1, 0, 0, 0]);
 const LAST_PRECOMPILE_ADDRESS: U256 = U256([10, 0, 0, 0]);
 
+/// A processed block trace, ready to be used to generate prover input payloads.
 #[derive(Debug)]
 pub(crate) struct ProcessedBlockTrace {
     pub tries: PartialTriePreImages,
-    pub txn_info: Vec<ProcessedTxnInfo>,
+    pub txn_info: Vec<ProcessedTxnBatchInfo>,
     pub withdrawals: Vec<(Address, U256)>,
 }
 
@@ -27,9 +28,11 @@ pub(crate) struct ProcessedBlockTracePreImages {
     pub extra_code_hash_mappings: Option<HashMap<H256, Vec<u8>>>,
 }
 
+/// A processed transaction batch, containing all information necessary to
+/// reproduce the state transition incurred by its set of transactions.
 #[derive(Debug, Default)]
-pub(crate) struct ProcessedTxnInfo {
-    pub nodes_used_by_txn: NodesUsedByTxn,
+pub(crate) struct ProcessedTxnBatchInfo {
+    pub nodes_used_by_txn: NodesUsedByTxnBatch,
     pub contract_code_accessed: HashSet<Vec<u8>>,
     pub meta: Vec<TxnMetaState>,
 }
@@ -77,8 +80,8 @@ impl TxnInfo {
         all_accounts_in_pre_image: &[(H256, AccountRlp)],
         extra_state_accesses: &[Address],
         hash2code: &mut Hash2Code,
-    ) -> anyhow::Result<ProcessedTxnInfo> {
-        let mut nodes_used_by_txn = NodesUsedByTxn::default();
+    ) -> anyhow::Result<ProcessedTxnBatchInfo> {
+        let mut nodes_used_by_txn = NodesUsedByTxnBatch::default();
         let mut contract_code_accessed = HashSet::from([vec![]]); // we always "access" empty code
         let mut meta = Vec::with_capacity(tx_infos.len());
 
@@ -243,7 +246,7 @@ impl TxnInfo {
             });
         }
 
-        Ok(ProcessedTxnInfo {
+        Ok(ProcessedTxnBatchInfo {
             nodes_used_by_txn,
             contract_code_accessed,
             meta,
@@ -260,13 +263,15 @@ fn check_receipt_bytes(bytes: Vec<u8>) -> anyhow::Result<Vec<u8>> {
     }
 }
 
-/// Note that "*_accesses" includes writes.
+/// A collection of all the state and storage accesses performed by a batch of
+/// transaction.
+///
+/// Note that "*_accesses" fields include writes.
 #[derive(Debug, Default)]
-pub(crate) struct NodesUsedByTxn {
+pub(crate) struct NodesUsedByTxnBatch {
     pub state_accesses: HashSet<Address>,
     pub state_writes: HashMap<Address, StateWrite>,
 
-    // Note: All entries in `storage_writes` also appear in `storage_accesses`.
     pub storage_accesses: HashMap<H256, Vec<TrieKey>>,
     pub storage_writes: HashMap<H256, HashMap<TrieKey, Vec<u8>>>,