From 1c87ce7fcaaf3806371b4428400a08e8cd67b7ba Mon Sep 17 00:00:00 2001
From: agureev <artguril@proton.me>
Date: Wed, 12 Aug 2026 15:17:03 +0400
Subject: [PATCH] doc: document changes

---
 lez/chain_state/src/apply.rs  | 10 ++++++++++
 lez/common/src/transaction.rs |  7 +++++++
 2 files changed, 17 insertions(+)

diff --git a/lez/chain_state/src/apply.rs b/lez/chain_state/src/apply.rs
index e33d27ba6..7451aec42 100644
--- a/lez/chain_state/src/apply.rs
+++ b/lez/chain_state/src/apply.rs
@@ -123,6 +123,8 @@ pub fn validate_against_tip(tip: Option<&Tip>, block: &Block) -> Result<(), Bloc
 /// Applies a block's transactions to `state`, mapping every failure to a
 /// [`BlockIngestError`] so the caller can park rather than crash. Operates in
 /// place; the caller commits only on `Ok`.
+///
+/// On `Ok` also returns the vector of indexed transaction events in the emitted order.
 pub fn apply_block_to_state(
     block: &Block,
     state: &mut V03State,
@@ -147,6 +149,8 @@ pub fn apply_block_to_state(
             tx_index: tx_index.try_into().expect("tx index fits in u64"),
             reason: format!("{err:#}"),
         };
+
+        // Collect all events based on user-submitted transactions.
         let events = if is_genesis {
             let LeeTransaction::Public(public_tx) = transaction else {
                 return Err(BlockIngestError::NonPublicGenesisTransaction);
@@ -168,6 +172,10 @@ pub fn apply_block_to_state(
         collect_tx_events(&mut block_events, tx_index, transaction, events);
     }
 
+    // Collect all events connected to the clock program separately.
+    // NOTE: Currently clock program does not have any events.
+    // This future-proofs the design in case they are introduced and has no bearing
+    // on current semantics.
     let clock_events = state
         .transition_from_public_transaction(clock_tx, block.header.block_id, block.header.timestamp)
         .map_err(|err| BlockIngestError::StateTransition {
@@ -179,6 +187,8 @@ pub fn apply_block_to_state(
     Ok(block_events)
 }
 
+/// Function collecting all block events into a vector of transaction events
+/// with a stamp indicating which transaction emitted it.
 fn collect_tx_events(
     block_events: &mut Vec<TxEvents>,
     tx_index: usize,
diff --git a/lez/common/src/transaction.rs b/lez/common/src/transaction.rs
index 383afb42a..c644c73e3 100644
--- a/lez/common/src/transaction.rs
+++ b/lez/common/src/transaction.rs
@@ -142,6 +142,8 @@ impl LeeTransaction {
     ///
     /// The indexer replays blocks the sequencer already validated and inscribed on Bedrock,
     /// so it trusts those inscriptions and re-derives state without re-validating them.
+    ///
+    /// Alongside the state, returns a vector of events the transaction emitted.
     pub fn execute_on_state(
         self,
         state: &mut V03State,
@@ -227,10 +229,15 @@ pub enum TransactionMalformationError {
     TransactionTooLarge { size: usize, max: usize },
 }
 
+/// A struct encoding a vector of transaction events alongside a fingerprint of a
+/// transaction which emitted it relative to the block it was in.
 #[derive(Debug, Clone, PartialEq, Eq, BorshSerialize, BorshDeserialize)]
 pub struct TxEvents {
+    // Index of an emitting transaction in a block.
     pub tx_index: u32,
+    // Hash of the emitting transaction.
     pub tx_hash: HashType,
+    // Vector of events in the order of emission.
     pub events: Vec<TransactionEvent>,
 }