chore: docs

lee/privacy_preserving_circuit/src/execution_state.rs

@@ -170,15 +170,11 @@ impl ExecutionState {
             );
 
             // Check that `program_output` is consistent with the execution of the corresponding
-            // program and that the program is well behaved. The System Program has no guest ELF,
-            // so its clear skips both recursive-proof verification and `validate_execution`: the
-            // clear intentionally violates `validate_execution` (owner → the declared new owner,
-            // data zeroed, default-owner-with-data: rules 4, 6, 7) and is instead structurally
-            // validated here against the accounts the caller declared, which fully pins the
-            // prover-supplied post states. Every other program is verified
-            // against its proof and then checked by `validate_execution`.
+            // program and that the program is well behaved.
             // See the # Programs section for the definition of the `validate_execution` method.
+
             if chained_call.program_id == DEFAULT_PROGRAM_ID {
+                // For the default system-program, do logic by hand.
                 assert_eq!(
                     chained_call.pre_states, program_output.pre_states,
                     "System Program clear must apply to the accounts the caller declared"
@@ -191,6 +187,7 @@ impl ExecutionState {
                     borsh::from_slice(&program_output.instruction_data)
                         .expect("System Program instruction must deserialize");
                 match instruction {
+                    // A protocol-wide `Clear` instruction wipes data and reassigns owner.
                     SystemInstruction::Clear { new_owner } => {
                         assert_eq!(
                             program_output.pre_states.len(),

lee/state_machine/core/src/program/mod.rs

@@ -313,8 +313,10 @@ pub enum Claim {
     Pda(PdaSeed),
 }
 
+/// An enum encoding the system-wide instruction to be passed to the verifier.
 #[derive(BorshSerialize, BorshDeserialize)]
 pub enum SystemInstruction {
+    /// Clears account data assigning new owner.
     Clear { new_owner: Option<AccountId> },
 }
 
@@ -841,6 +843,9 @@ pub fn validate_execution(
     Ok(())
 }
 
+/// Logic of system-wide `Clear` instriction.
+///
+/// Checks authorization, clearing data and assigning a new owner.
 pub fn validate_clear(
     pre: &AccountWithMetadata,
     new_owner: Option<AccountId>,