From 87fb34fd34eee9fdd02fc03385c125a03fc6b9c7 Mon Sep 17 00:00:00 2001
From: agureev <artguril@proton.me>
Date: Tue, 11 Aug 2026 17:45:11 +0400
Subject: [PATCH] chore: docs

---
 lee/state_machine/core/src/program/mod.rs                     | 4 ++++
 lee/state_machine/src/state/tests/mod.rs                      | 2 --
 lee/state_machine/src/validated_state_diff/mod.rs             | 2 ++
 lee/state_machine/test_methods/guest/src/bin/event_emitter.rs | 2 ++
 4 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/lee/state_machine/core/src/program/mod.rs b/lee/state_machine/core/src/program/mod.rs
index 1189e87eb..f0bb5b82a 100644
--- a/lee/state_machine/core/src/program/mod.rs
+++ b/lee/state_machine/core/src/program/mod.rs
@@ -489,6 +489,7 @@ pub struct ProgramOutput {
     pub block_validity_window: BlockValidityWindow,
     /// The timestamp window where the program output is valid.
     pub timestamp_validity_window: TimestampValidityWindow,
+    /// A vector of event data.
     pub events: Vec<Vec<u8>>,
 }
 
@@ -577,10 +578,13 @@ impl ProgramOutput {
     }
 }
 
+/// A struct holding an event-output of a program.
 #[cfg(feature = "host")]
 #[derive(Debug, Clone, PartialEq, Eq, BorshSerialize, BorshDeserialize)]
 pub struct Event {
+    // Which program emitted the event.
     pub program_id: ProgramId,
+    // The arbitrary event-data emitted in the program output.
     pub data: Vec<u8>,
 }
 
diff --git a/lee/state_machine/src/state/tests/mod.rs b/lee/state_machine/src/state/tests/mod.rs
index 49e238489..63f3f4f45 100644
--- a/lee/state_machine/src/state/tests/mod.rs
+++ b/lee/state_machine/src/state/tests/mod.rs
@@ -181,8 +181,6 @@ enum FlashSwapInstruction {
     },
 }
 
-// ── Event emitter type (mirror of the guest type for host-side serialisation) ──
-
 #[derive(serde::Serialize, serde::Deserialize)]
 struct EmitterInstruction {
     events: Vec<Vec<u8>>,
diff --git a/lee/state_machine/src/validated_state_diff/mod.rs b/lee/state_machine/src/validated_state_diff/mod.rs
index 9712bc56c..aaafa6622 100644
--- a/lee/state_machine/src/validated_state_diff/mod.rs
+++ b/lee/state_machine/src/validated_state_diff/mod.rs
@@ -262,6 +262,8 @@ impl ValidatedStateDiff {
                 state_diff.insert(pre.account_id, post.account().clone());
             }
 
+            // Write all the output event data into a proper event struct,
+            // marking its emitter program.
             events.extend(program_output.events.into_iter().map(|data| Event {
                 program_id: chained_call.program_id,
                 data,
diff --git a/lee/state_machine/test_methods/guest/src/bin/event_emitter.rs b/lee/state_machine/test_methods/guest/src/bin/event_emitter.rs
index e6d71502f..41b9813a6 100644
--- a/lee/state_machine/test_methods/guest/src/bin/event_emitter.rs
+++ b/lee/state_machine/test_methods/guest/src/bin/event_emitter.rs
@@ -35,6 +35,8 @@ fn main() {
         })
         .collect();
 
+    // Emit both the chained calls and a list of events.
+    // This is used to test the end-positioning of events in a transaction.
     ProgramOutput::new(
         self_program_id,
         caller_program_id,