From 29b56e3a32e1e0b6186562681c9b8bedca529468 Mon Sep 17 00:00:00 2001
From: Sergio Chouhy <sergio.chouhy@gmail.com>
Date: Sun, 20 Jul 2025 22:30:31 -0300
Subject: [PATCH] improve docstrings

---
 risc0-selective-privacy-poc/core/src/lib.rs    | 18 ++++++++++++++----
 .../sequencer/process_public_execution.rs      |  4 ++--
 .../program_methods/guest/src/bin/outer.rs     | 13 +++++--------
 3 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/risc0-selective-privacy-poc/core/src/lib.rs b/risc0-selective-privacy-poc/core/src/lib.rs
index 9342094..dbd4b5b 100644
--- a/risc0-selective-privacy-poc/core/src/lib.rs
+++ b/risc0-selective-privacy-poc/core/src/lib.rs
@@ -53,10 +53,19 @@ pub fn bytes_to_words(bytes: &[u8; 32]) -> [u32; 8] {
     words
 }
 
-/// Verifies that a program public execution didn't break the chain's rules.
-/// `input_accounts` are the accounts provided as inputs to the program.
-/// `output_accounts` are the accounts post states after execution of the program
-pub fn post_execution_consistency_checks(
+/// Ensures that account transitions follow the rules of a well-behaved program.
+///
+/// A well-behaved program is one that:
+/// - does not change account addresses
+/// - does not change account nonces
+/// - does not change the `program_owner` field
+/// - only reduces the balance of accounts it owns 
+/// - preserves the total token supply across all accounts
+///
+/// This function does **not** check that the output accounts are the result of correctly
+/// executing the program. That must be checked separately, either by re-executing
+/// the program with the inputs or by verifying a proof of correct execution.
+pub fn check_well_behaved_account_transition(
     input_accounts: &[Account],
     output_accounts: &[Account],
     program_id: ProgramId,
@@ -71,6 +80,7 @@ pub fn post_execution_consistency_checks(
         if account_pre.address != account_post.address {
             return false;
         }
+
         // Fail if the program modified the nonces of the input accounts
         if account_pre.nonce != account_post.nonce {
             return false;
diff --git a/risc0-selective-privacy-poc/examples/mocked_components/sequencer/process_public_execution.rs b/risc0-selective-privacy-poc/examples/mocked_components/sequencer/process_public_execution.rs
index b41b1b2..fcf7562 100644
--- a/risc0-selective-privacy-poc/examples/mocked_components/sequencer/process_public_execution.rs
+++ b/risc0-selective-privacy-poc/examples/mocked_components/sequencer/process_public_execution.rs
@@ -1,4 +1,4 @@
-use core::{account::Account, post_execution_consistency_checks, types::Address};
+use core::{account::Account, check_well_behaved_account_transition, types::Address};
 
 use crate::mocked_components::sequencer::error::Error;
 
@@ -22,7 +22,7 @@ impl MockedSequencer {
             nssa::execute_onchain::<P>(&input_accounts, instruction_data).map_err(|_| Error::BadInput)?;
 
         // Assert accounts pre- and post-states preserve chains invariants
-        if !post_execution_consistency_checks(&input_accounts, &program_output.accounts_post, P::PROGRAM_ID) {
+        if !check_well_behaved_account_transition(&input_accounts, &program_output.accounts_post, P::PROGRAM_ID) {
             return Err(Error::BadInput);
         }
 
diff --git a/risc0-selective-privacy-poc/program_methods/guest/src/bin/outer.rs b/risc0-selective-privacy-poc/program_methods/guest/src/bin/outer.rs
index c95726c..2f4fcd7 100644
--- a/risc0-selective-privacy-poc/program_methods/guest/src/bin/outer.rs
+++ b/risc0-selective-privacy-poc/program_methods/guest/src/bin/outer.rs
@@ -1,5 +1,5 @@
 use core::{
-    compute_nullifier, hash, is_in_tree, post_execution_consistency_checks,
+    check_well_behaved_account_transition, compute_nullifier, hash, is_in_tree,
     types::{Nonce, PrivacyExecutionOutput, ProgramId, ProgramOutput},
     visibility::AccountVisibility,
 };
@@ -7,18 +7,15 @@ use risc0_zkvm::{guest::env, serde::to_vec};
 
 /// Privacy execution logic.
 /// This is the circuit for proving correct off-chain executions of programs.
-/// It also verifies that the chain's invariants are not violated.
+/// It also verifies that the chain's invariants are not violated and the program is well-behaved.
 ///
 /// Inputs:
-/// - Vec<Account>: The output of the inner program. This is assumed to include the accounts pre and
+/// - ProgramOuptut: The output of the inner program. This is includes the accounts pre and
 ///     post-states of the execution of the inner program.
-///
 /// - Vec<AccountVisibility>: A vector indicating which accounts are private and which are public.
-///
 /// - Vec<Nonce>: The vector of nonces to be used for the output accounts. This is assumed to be
 ///     sampled at random by the host program.
-///
-/// - [u32; 8]: The root of the commitment tree. Commitments of used private accounts will be
+/// - [u32; 8]: The root of the commitment tree. Commitments of input private accounts will be
 ///     checked against this to prove that they belong to the tree.
 /// - ProgamId: The ID of the inner program.
 ///
@@ -52,7 +49,7 @@ fn main() {
     env::verify(program_id, &to_vec(&inner_program_output).unwrap()).unwrap();
 
     // Assert accounts pre- and post-states preserve chains invariants
-    assert!(post_execution_consistency_checks(
+    assert!(check_well_behaved_account_transition(
         &inner_program_output.accounts_pre,
         &inner_program_output.accounts_post,
         program_id