chore: docs

lee/privacy_preserving_circuit/src/execution_state.rs

@@ -172,14 +172,9 @@ impl ExecutionState {
                 "Program output caller_program_id does not match actual caller"
             );
 
-            // 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 → default, data zeroed,
-            // default-owner-with-data: rules 4, 6, 7) and is instead structurally validated here,
-            // which fully pins the prover-supplied post state. Every other program is verified
-            // against its proof and then checked by `validate_execution`.
-            // See the # Programs section for the definition of the `validate_execution` method.
+            // The System Program has no guest ELF and is instead structurally validated here,
+            // Every other program is verified  against its proof and then checked by
+            // `validate_execution`.
             if chained_call.program_id == DEFAULT_PROGRAM_ID {
                 let instruction: SystemInstruction = from_slice(&program_output.instruction_data)
                     .expect("System Program instruction must deserialize");
@@ -195,6 +190,7 @@ impl ExecutionState {
                             .iter()
                             .zip(program_output.post_states.iter())
                         {
+                            // Try to clear each account in pre-states.
                             let expected = match validate_clear(pre) {
                                 Ok(expected) => expected,
                                 Err(err) => panic!(
@@ -202,6 +198,8 @@ impl ExecutionState {
                                     chained_call.program_id
                                 ),
                             };
+
+                            // If the cleared account differs from expected, error.
                             assert_eq!(
                                 post.account(),
                                 &expected,
@@ -211,12 +209,15 @@ impl ExecutionState {
                     }
                 }
             } else {
+                // Check that `program_output` is consistent with the execution of the corresponding
+                // program.
                 let program_output_words =
                     &to_vec(&program_output).expect("program_output must be serializable");
                 env::verify(chained_call.program_id, program_output_words).unwrap_or_else(
                     |_: Infallible| unreachable!("Infallible error is never constructed"),
                 );
 
+                // Check that `program_output` is well behaved.
                 let validated_execution = validate_execution(
                     &program_output.pre_states,
                     &program_output.post_states,

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

@@ -775,6 +775,8 @@ pub fn validate_execution(
     Ok(())
 }
 
+/// Function for validation of account-clearing. If authorized, defaults the owner
+/// and data, keeping the balance.
 pub fn validate_clear(pre: &AccountWithMetadata) -> Result<Account, ClearValidationError> {
     if !pre.is_authorized {
         return Err(ClearValidationError::NotAuthorized {

lee/state_machine/src/validated_state_diff/mod.rs

@@ -122,12 +122,15 @@ impl ValidatedStateDiff {
             };
 
             if chained_call.program_id == DEFAULT_PROGRAM_ID {
+                // If the program is a default one, try to decode the protocol-wide instruction.
                 let instruction: SystemInstruction =
                     risc0_zkvm::serde::from_slice(&chained_call.instruction_data)
                         .map_err(|e| LeeError::InstructionSerializationError(e.to_string()))?;
 
                 match instruction {
                     SystemInstruction::Clear => {
+                        // On a `Clear`, if authorized, wipe a pre-state's owner
+                        // and data.
                         for pre_state in &chained_call.pre_states {
                             let account_id = pre_state.account_id;
                             let pre = AccountWithMetadata::new(

lez/wallet/src/cli/programs/system_program.rs

@@ -16,8 +16,7 @@ pub enum SystemSubcommand {
     ///
     /// The account authorizes its own reset. Only public accounts are supported.
     Reclaim {
-        /// Public account to reclaim. Either 32 byte base58 account id string with
-        /// privacy prefix or a label. You must own this account.
+        /// Account to reclaim. Must have authorization.
         #[arg(long)]
         account_id: CliAccountMention,
     },