Improve README from code walkthorugh (#95)

* add initial draft

* add code walkthrough

* Apply suggestions from code review

Co-authored-by: Victor Graf <victor@risczero.com>

* address review comments

* simplify

---------

Co-authored-by: Victor Graf <victor@risczero.com>

README.md

@@ -100,11 +100,11 @@ Your new project consists of:
 
 ## Develop Your Application
 
-To build your application, you'll need to make changes in three folders:
+To build your application using the RISC Zero Foundry Template, you’ll need to make changes in three main areas:
 
-- write the code you want proven in the [methods/guest](./methods/guest/) folder.
-- write the on-chain part of your project in the [contracts](./contracts/) folder.
-- adjust the publisher example in the [apps](./apps/) folder.
+-	***Guest Code***: Write the code you want proven in the [methods/guest](./methods/guest/) folder. This code runs off-chain within the RISC Zero zkVM and performs the actual computations. For example, the provided template includes a computation to check if a given number is even and generate a proof of this computation.
+-	***Smart Contracts***: Write the on-chain part of your project in the [contracts](./contracts/) folder. The smart contract verifies zkVM proofs and updates the blockchain state based on the results of off-chain computations. For instance, in the [EvenNumber](./contracts/EvenNumber.sol) example, the smart contract verifies a proof that a number is even and stores that number on-chain if the proof is valid.
+-	***Publisher Application***: Adjust the publisher example in the [apps](./apps/) folder. The publisher application bridges off-chain computation with on-chain verification by submitting proof requests, receiving proofs, and publishing them to the smart contract on Ethereum.
 
 ### Configuring Bonsai
 

apps/src/bin/publisher.rs

@@ -57,37 +57,45 @@ struct Args {
 
 fn main() -> Result<()> {
     env_logger::init();
+    // Parse CLI Arguments: The application starts by parsing command-line arguments provided by the user.
     let args = Args::parse();
 
-    // Create a new `TxSender`.
+    // Create a new transaction sender using the parsed arguments.
     let tx_sender = TxSender::new(
         args.chain_id,
         &args.rpc_url,
         &args.eth_wallet_private_key,
         &args.contract,
     )?;
 
-    // ABI encode the input for the guest binary, to match what the `is_even` guest
-    // code expects.
+    // ABI encode input: Before sending the proof request to the Bonsai proving service,
+    // the input number is ABI-encoded to match the format expected by the guest code running in the zkVM.
     let input = args.input.abi_encode();
 
-    // Send an off-chain proof request to the Bonsai proving service.
+    // Request proof from the Bonsai proving service: The application sends the encoded input to the
+    // Bonsai proving service, requesting it to execute the is_even computation off-chain and generate the necessary proof.
     let (journal, post_state_digest, seal) = BonsaiProver::prove(IS_EVEN_ELF, &input)?;
 
-    // Decode the journal. Must match what was written in the guest with
-    // `env::commit_slice`.
+    // Decode Journal: Upon receiving the proof, the application decodes the journal to extract
+    // the verified number. This ensures that the number being submitted to the blockchain matches
+    // the number that was verified off-chain.
     let x = U256::abi_decode(&journal, true).context("decoding journal data")?;
 
-    // Encode the function call for `IEvenNumber.set(x)`.
+    // Construct function call: Using the IEvenNumber interface, the application constructs
+    // the ABI-encoded function call for the set function of the EvenNumber contract.
+    // This call includes the verified number, the post-state digest, and the seal (proof).
     let calldata = IEvenNumber::IEvenNumberCalls::set(IEvenNumber::setCall {
         x,
         post_state_digest,
         seal,
     })
     .abi_encode();
 
-    // Send the calldata to Ethereum.
+    // Initialize the async runtime environment to handle the transaction sending.
     let runtime = tokio::runtime::Runtime::new()?;
+
+    // Send transaction: Finally, the TxSender component sends the transaction to the Ethereum blockchain,
+    // effectively calling the set function of the EvenNumber contract with the verified number and proof.
     runtime.block_on(tx_sender.send(calldata))?;
 
     Ok(())

contracts/EvenNumber.sol

@@ -27,6 +27,10 @@ contract EvenNumber {
     /// @notice RISC Zero verifier contract address.
     IRiscZeroVerifier public immutable verifier;
     /// @notice Image ID of the only zkVM binary to accept verification from.
+    ///         The image ID is similar to the address of a smart contract.
+    ///         It uniquely represents the logic of that guest program,
+    ///         ensuring that only proofs generated from a pre-defined guest program
+    ///         (in this case, checking if a number is even) are considered valid.
     bytes32 public constant imageId = ImageID.IS_EVEN_ID;
 
     /// @notice A number that is guaranteed, by the RISC Zero zkVM, to be even.