From b44c84a4dbd38f9669e69045724284f959bc1195 Mon Sep 17 00:00:00 2001 From: capossele Date: Thu, 15 Feb 2024 12:53:20 +0000 Subject: [PATCH] update READMEs --- apps/README.md | 14 +++++++++++--- apps/src/bin/publisher.rs | 17 +++++++++++------ apps/src/lib.rs | 13 +++++++++++++ contracts/README.md | 31 ++++++++++++++++++++++++++++--- deployment-guide.md | 4 ++-- methods/README.md | 23 ++++++++--------------- 6 files changed, 73 insertions(+), 29 deletions(-) diff --git a/apps/README.md b/apps/README.md index 4eff2d5a..5f7513ec 100644 --- a/apps/README.md +++ b/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/ \ No newline at end of file + +## 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/ \ No newline at end of file diff --git a/apps/src/bin/publisher.rs b/apps/src/bin/publisher.rs index 132ae379..c7ba68b5 100644 --- a/apps/src/bin/publisher.rs +++ b/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,6 +59,7 @@ 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, @@ -64,16 +67,17 @@ fn main() -> Result<()> { &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, @@ -81,6 +85,7 @@ fn main() -> Result<()> { }) .abi_encode(); + // Send the calldata to Ethereum. let runtime = tokio::runtime::Runtime::new()?; runtime.block_on(tx_sender.send(calldata))?; diff --git a/apps/src/lib.rs b/apps/src/lib.rs index c953014d..befb73b4 100644 --- a/apps/src/lib.rs +++ b/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,6 +29,8 @@ 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, Wallet>, @@ -28,6 +38,7 @@ pub struct TxSender { } impl TxSender { + /// Creates a new `TxSender`. pub fn new(chain_id: u64, rpc_url: &str, private_key: &str, contract: &str) -> Result { let provider = Provider::::try_from(rpc_url)?; let wallet: LocalWallet = private_key.parse::()?.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) -> Result> { 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`, `FixedBytes<32>`, diff --git a/contracts/README.md b/contracts/README.md index 7ed739bc..709c1cdb 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,11 +1,29 @@ # 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. - +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. @@ -13,3 +31,10 @@ 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 \ No newline at end of file diff --git a/deployment-guide.md b/deployment-guide.md index a0cf9d98..19abd887 100644 --- a/deployment-guide.md +++ b/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]. diff --git a/methods/README.md b/methods/README.md index cc2b8c27..98e32535 100644 --- a/methods/README.md +++ b/methods/README.md @@ -3,13 +3,8 @@ 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 @@ -17,8 +12,6 @@ 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 - - -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 \ No newline at end of file