update READMEs

apps/README.md

@@ -1,6 +1,5 @@
 # Apps
 
-
 ## Publisher
 This template provides an application example, [publisher], that lets you send an off-chain proof request to the [Bonsai] proving service and publish the received proofs directly to your deployed app contract.
 
@@ -26,5 +25,14 @@ Options:
           Print version
 ```
 
-[publisher]: (./src/bin/publisher.rs)
-[Bonsai]: https://dev.bonsai.xyz/
+
+## Library
+We provide a small rust [library] containing utility functions to help with sending off-chain proof requests to the Bonsai proving service and publish the received proofs directly to a deployed app contract on Ethereum.
+
+Please note that both [risc0_zkvm] and [bonsai_sdk] crates are still under active development. As such, this library might change to adapt to the upstream changes.
+
+[publisher]: ./src/bin/publisher.rs
+[Bonsai]: https://dev.bonsai.xyz/
+[library]: ./src/lib.rs
+[risc0_zkvm]: https://docs.rs/risc0-zkvm/latest/risc0_zkvm/
+[bonsai_sdk]: https://docs.rs/bonsai-sdk/latest/bonsai_sdk/

apps/src/bin/publisher.rs

@@ -12,6 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// This application demonstrates how to send an off-chain proof request
+// to the Bonsai proving service and publish the received proofs directly
+// to your deployed app contract.
+
 use alloy_primitives::U256;
 use alloy_sol_types::{sol, SolInterface, SolValue};
 use anyhow::{Context, Result};
@@ -20,8 +24,6 @@ use clap::Parser;
 use methods::IS_EVEN_ELF;
 
 // `IEvenNumber`` interface automatically generated via the alloy `sol!` macro.
-// The `set` function is then used as part of the `calldata` function of the
-// `EvenNumberInterface`.
 sol! {
     interface IEvenNumber {
         function set(uint256 x, bytes32 post_state_digest, bytes calldata seal);
@@ -57,30 +59,33 @@ fn main() -> Result<()> {
     env_logger::init();
     let args = Args::parse();
 
+    // Create a new `TxSender`.
     let tx_sender = TxSender::new(
         args.chain_id,
         &args.rpc_url,
         &args.eth_wallet_private_key,
         &args.contract,
     )?;
 
+    // Parse the hex encoded input for the guest binary.
     let input = hex::decode(args.input.strip_prefix("0x").unwrap_or(&args.input))?;
-    // TODO: explina that this is an helper function and a better integration is a
-    // TODO
+
+    // Send an off-chain proof request to the Bonsai proving service.
     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`
+    // `env::commit_slice`.
     let x = U256::abi_decode(&journal, true).context("decoding journal data")?;
 
-    // Encode the function call for `IEvenNumber.set(x)`
+    // Encode the function call for `IEvenNumber.set(x)`.
     let calldata = IEvenNumber::IEvenNumberCalls::set(IEvenNumber::setCall {
         x,
         post_state_digest,
         seal,
     })
     .abi_encode();
 
+    // Send the calldata to Ethereum.
     let runtime = tokio::runtime::Runtime::new()?;
     runtime.block_on(tx_sender.send(calldata))?;
 

apps/src/lib.rs

@@ -12,6 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// The following library provides utility functions to help with sending
+// off-chain proof requests to the Bonsai proving service and publish the
+// received proofs directly to a deployed app contract on Ethereum.
+//
+// Please note that both `risc0_zkvm` and `bonsai_sdk` crates are still
+// under active development. As such, this library might change to adapt to
+// the upstream changes.
+
 use std::time::Duration;
 
 use alloy_primitives::FixedBytes;
@@ -21,13 +29,16 @@ use ethers::prelude::*;
 use risc0_ethereum_contracts::groth16::Seal;
 use risc0_zkvm::{compute_image_id, Receipt};
 
+/// Wrapper of a `SignerMiddleware` client to send transactions to the given
+/// contract's `Address`.
 pub struct TxSender {
     chain_id: u64,
     client: SignerMiddleware<Provider<Http>, Wallet<k256::ecdsa::SigningKey>>,
     contract: Address,
 }
 
 impl TxSender {
+    /// Creates a new `TxSender`.
     pub fn new(chain_id: u64, rpc_url: &str, private_key: &str, contract: &str) -> Result<Self> {
         let provider = Provider::<Http>::try_from(rpc_url)?;
         let wallet: LocalWallet = private_key.parse::<LocalWallet>()?.with_chain_id(chain_id);
@@ -41,6 +52,7 @@ impl TxSender {
         })
     }
 
+    /// Send a transaction with the given calldata.
     pub async fn send(&self, calldata: Vec<u8>) -> Result<Option<TransactionReceipt>> {
         let tx = TransactionRequest::new()
             .chain_id(self.chain_id)
@@ -58,6 +70,7 @@ impl TxSender {
     }
 }
 
+/// An implementation of a Prover that runs on Bonsai.
 pub struct BonsaiProver {}
 impl BonsaiProver {
     /// Generates a snark proof as a triplet (`Vec<u8>`, `FixedBytes<32>`,

contracts/README.md

@@ -1,15 +1,40 @@
 # Solidity Contracts
 
 This directory contains the Solidity contract for deploying an application with [RISC Zero] on Ethereum.
-There are two primary starter template contracts included.
+The example contract included within the template is [EvenNumber.sol]. It holds a number, guaranteed to be even.
 
-<!-- TODO: Change this link once the new repo is live -->
+Additional contracts get auto-generated when building the project with cargo, by running:
 
-The Solidity libraries for Bonsai can be found at [github.com/risc0/risc0](https://github.com/risc0/risc0/tree/main/bonsai/ethereum).
+```bash
+cargo build
+```
+
+or to build guest code for the zkVM target `riscv32im-risc0-zkvm-elf` deterministically:
+
+```bash
+RISC0_USE_DOCKER=1 cargo build
+```
+
+By setting the env variable `RISC0_USE_DOCKER` a containerized build process via `Docker` will ensure that all builds of your guest code, regardless of the machine or local environment, will produce the same [ImageID]. The ImageID, and its importance to [security], is explained in more detail in our [developer FAQ].
+
+> **Note**: *to install `Docker`, see [Get Docker].*
+
+Specifically:
+- `ImageID.sol`: contains the ImageIDs for the guests implemented in the [methods] directory.
+- `elf.sol`: contains the path of the guest binaries implemented in the [methods] directory. This contract is saved in the `tests` directory in the root of this template.
+
+The Solidity libraries for Bonsai can be found at [github.com/risc0/risc0-ethereum].
 
 Contracts are built and tested with [forge], which is part of the [Foundry] toolkit.
 Tests are defined in the `tests` directory in the root of this template.
 
 [Foundry]: https://getfoundry.sh/
 [forge]: https://github.com/foundry-rs/foundry#forge
 [RISC Zero]: https://risczero.com
+[EvenNumber.sol]: ./EvenNumber.sol
+[github.com/risc0/risc0-ethereum]: https://github.com/risc0/risc0-ethereum/tree/main/contracts
+[methods]: ../methods/README.md
+[ImageID]: https://dev.risczero.com/terminology#image-id
+[Get Docker]: https://docs.docker.com/get-docker/
+[security]: https://dev.risczero.com/faq#security
+[developer FAQ]: https://dev.risczero.com/faq#zkvm-application-design

deployment-guide.md

@@ -31,7 +31,7 @@ You can deploy your contracts and run an end-to-end test or demo as follows:
     export ETH_WALLET_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
     export BONSAI_API_KEY="YOUR_API_KEY" # see form linked in the previous section
     export BONSAI_API_URL="BONSAI_API_URL" # provided with your api key
-    export RISC0_USE_DOCKER=1 # enable reproducible build via Docker
+    export RISC0_USE_DOCKER=1 # enable a deterministic environment via Docker
     ```
 
     By setting *RISC0_USE_DOCKER=1* the build process will build your guest binary within a deterministic environment, resulting in a reproducible build. This is helpful because it allows third-parties to independently build the guest binary and generate the same [image ID]. For more details, see [reproducible build].
@@ -108,7 +108,7 @@ You can deploy your contracts on a testnet such as `Sepolia` and run an end-to-e
     export BONSAI_API_URL="BONSAI_API_URL" # provided with your api key
     export ALCHEMY_API_KEY="YOUR_ALCHEMY_API_KEY" # the API_KEY provided with an alchemy account
     export ETH_WALLET_PRIVATE_KEY="YOUR_WALLET_PRIVATE_KEY" # the private key of your Ethereum testnet wallet e.g., Sepolia
-     export RISC0_USE_DOCKER=1 # enable reproducible build via Docker
+     export RISC0_USE_DOCKER=1 # enable a deterministic environment via Docker
     ```
 
     By setting *RISC0_USE_DOCKER=1* the build process will build your guest binary within a deterministic environment, resulting in a reproducible build. This is helpful because it allows third-parties to independently build the guest binary and generate the same [image ID]. For more details, see [reproducible build].

methods/README.md

@@ -3,22 +3,15 @@
 This directory contains the [zkVM] portion of your [RISC Zero] application.
 This is where you will define one or more [guest programs] to act as a coprocessor to your [on-chain logic].
 
-> In typical use cases, the only code in this directory that you will need to edit is inside [`guest/src/bin`].
+> In typical use cases, the only code in this directory that you will need to edit is inside [guest/src/bin].
 
-[zkVM]: https://dev.risczero.com/zkvm
-[RISC Zero]: https://www.risczero.com/
-[guest programs]: https://dev.risczero.com/terminology#guest-program
-[on-chain logic]: ../contracts/
-[`guest/src/bin`]: ./guest/src/bin/
 
 ### Writing Guest Code
 
 To learn to write code for the zkVM, we recommend [Guest Code 101].
 
 Examples of what you can do in the guest can be found in the [RISC Zero examples].
 
-[Guest Code 101]: https://dev.risczero.com/zkvm/developer-guide/guest-code-101
-[RISC Zero examples]: https://github.com/risc0/tree/v0.18.0/examples
 
 ### From Guest Code to Binary File
 
@@ -28,11 +21,11 @@ Build configuration for the methods is included in `methods/build.rs`.
 
 Each will have a corresponding image ID, which is a hash identifying the program.
 
-### Uploading Binary to Bonsai
-
-<!-- TODO: This should have practical instructions on how to actually upload to Bonsai -->
 
-When [deploying] your application, you will upload your binary to Bonsai where the guest will run when requested.
-The image ID will be included in the deployment of the smart contracts to reference your guest program living in Bonsai.
-
-[deploying]: ../deployment-guide
+[zkVM]: https://dev.risczero.com/zkvm
+[RISC Zero]: https://www.risczero.com/
+[guest programs]: https://dev.risczero.com/terminology#guest-program
+[on-chain logic]: ../contracts/
+[guest/src/bin]: ./guest/src/bin/
+[Guest Code 101]: https://dev.risczero.com/zkvm/developer-guide/guest-code-101
+[RISC Zero examples]: https://github.com/risc0/tree/v0.18.0/examples