{"id":19641637,"url":"https://github.com/risc0/risc0-foundry-template","last_synced_at":"2025-12-30T00:04:13.893Z","repository":{"id":176355535,"uuid":"643991144","full_name":"risc0/risc0-foundry-template","owner":"risc0","description":"Template for integrating RISC Zero and Ethereum using Foundry and Bonsai","archived":false,"fork":false,"pushed_at":"2024-05-17T11:37:28.000Z","size":1013,"stargazers_count":78,"open_issues_count":10,"forks_count":42,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-05-17T12:46:28.512Z","etag":null,"topics":["ethereum","foundry","rust","solidity","web3","zero-knowledge","zk-coprocessor"],"latest_commit_sha":null,"homepage":"https://risczero.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/risc0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-22T15:18:26.000Z","updated_at":"2024-05-29T22:20:58.281Z","dependencies_parsed_at":"2024-01-09T15:42:25.671Z","dependency_job_id":"64976a47-7d93-4584-86cd-51ea3678d168","html_url":"https://github.com/risc0/risc0-foundry-template","commit_stats":null,"previous_names":["risc0/bonsai-foundry-template","risc0/risc0-foundry-template"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risc0%2Frisc0-foundry-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risc0%2Frisc0-foundry-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risc0%2Frisc0-foundry-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risc0%2Frisc0-foundry-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/risc0","download_url":"https://codeload.github.com/risc0/risc0-foundry-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224115723,"owners_count":17258238,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ethereum","foundry","rust","solidity","web3","zero-knowledge","zk-coprocessor"],"created_at":"2024-11-11T14:09:58.982Z","updated_at":"2025-12-30T00:04:13.886Z","avatar_url":"https://github.com/risc0.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RISC Zero Foundry Template\n\n\u003e [!WARNING]\n\u003e **This repository has been deprecated.** After serving the community well, this template is now superseded by the [Boundless Foundry Template](https://github.com/boundless-xyz/boundless-foundry-template). All new projects should use the Boundless Foundry Template for the latest features and ongoing support. Thank you for your understanding. 🙏\n\n\u003e Prove computation with the [RISC Zero zkVM][docs-zkvm] and verify the results in your Ethereum contract.\n\nThis repository implements an example application on Ethereum utilizing RISC Zero as a [coprocessor][blog-coprocessor] to the smart contract application.\nIt provides a starting point for building powerful new applications on Ethereum that offload work that is computationally intensive (i.e. gas expensive), or difficult to implement in Solidity (e.g. ed25519 signature verification, or HTML parsing).\n\nIntegrate with [Steel][steel-repo] to execute view calls and simulate transactions on Ethereum. Check out the [ERC-20 counter][erc20-counter] demo to see an example.\n\n## Overview\n\nHere is a simplified overview of how devs can integrate RISC Zero, including with [Bonsai][docs-bonsai] proving, into their Ethereum smart contracts:\n\n![RISC Zero Foundry Template Diagram](images/risc0-foundry-template.png)\n\n1. Run your application logic in the [RISC Zero zkVM][docs-zkvm]. The provided [publisher](./apps) app sends an off-chain proof request to the [Bonsai] proving service.\n2. [Bonsai][docs-bonsai] generates the program result, written to the [journal][term-journal], and a SNARK proof of its correctness.\n3. The [publisher](./apps) app submits this proof and journal on-chain to your app contract for validation.\n4. Your app contract calls the [RISC Zero Verifier][docs-verifier] to validate the proof. If the verification is successful, the journal is deemed trustworthy and can be safely used.\n\n## Dependencies\n\nFirst, [install Rust][install-rust] and [Foundry][install-foundry], and then restart your terminal.\n\n```sh\n# Install Rust\ncurl https://sh.rustup.rs -sSf | sh\n# Install Foundry\ncurl -L https://foundry.paradigm.xyz | bash\n```\n\nNext, you will use `rzup` to install `cargo-risczero`.\n\nTo install `rzup`, run the following command and follow the instructions:\n\n```sh\ncurl -L https://risczero.com/install | bash\n```\n\nNext we can install the RISC Zero toolchain by running `rzup`:\n\n```sh\nrzup install\n```\n\nYou can verify the installation was successful by running:\n\n```sh\ncargo risczero --version\n```\n\nNow you have all the tools you need to develop and deploy an application with [RISC Zero][homepage-risczero].\n\n## Quick Start\n\nFirst, install the RISC Zero toolchain using the [instructions above](#dependencies).\n\nNow, you can initialize a new RISC Zero project at a location of your choosing:\n\n```sh\nforge init -t risc0/risc0-foundry-template ./my-project\n```\n\nCongratulations! You've just started your first RISC Zero project.\n\nYour new project consists of:\n\n- a [zkVM program](./methods) (written in Rust), which specifies a computation that will be proven;\n- a [app contract](./contracts) (written in Solidity), which uses the proven results;\n- a [publisher](./apps) which makes proving requests to [Bonsai][docs-bonsai] and posts the proof to Ethereum.\n  We provide an example implementation, but your dApp interface or application servers could act as the publisher.\n\n### Build the Code\n\n- Update git submodules.\n\n  ```sh\n  git submodule update --init\n  ```\n\n- Builds for zkVM program, the publisher app, and any other Rust code.\n\n  ```sh\n  cargo build\n  ```\n\n- Build your Solidity smart contracts.\n\n  \u003e NOTE: `cargo build` needs to run first to generate the `ImageID.sol` contract.\n\n  ```sh\n  forge build\n  ```\n\n### Run the Tests\n\n- Tests your zkVM program.\n\n  ```sh\n  cargo test\n  ```\n\n- Test your Solidity contracts, integrated with your zkVM program.\n\n  ```sh\n  RISC0_DEV_MODE=true forge test -vvv \n  ```\n\n- Run the same tests, with the full zkVM prover rather than dev-mode, by setting `RISC0_DEV_MODE=false`.\n\n  ```sh\n  RISC0_DEV_MODE=false forge test -vvv\n  ```\n\n  Producing the [Groth16 SNARK proofs][groth16] for this test requires running on an x86 machine with [Docker][install-docker] installed, or using [Bonsai](#configuring-bonsai).\n  Apple silicon is currently unsupported for local proving, you can find out more info in the relevant issues [here](https://github.com/risc0/risc0/issues/1520) and [here](https://github.com/risc0/risc0/issues/1749).\n\n## Develop Your Application\n\nTo build your application using the RISC Zero Foundry Template, you’ll need to make changes in three main areas:\n\n- ***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.\n- ***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.\n- ***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.\n\n### Configuring Bonsai\n\n***Note:*** *To request an API key [complete the form here](https://bonsai.xyz/apply).*\n\nWith the Bonsai proving service, you can produce a [Groth16 SNARK proof][Groth16] that is verifiable on-chain.\nYou can get started by setting the following environment variables with your API key and associated URL.\n\n```bash\nexport BONSAI_API_KEY=\"YOUR_API_KEY\" # see form linked above\nexport BONSAI_API_URL=\"BONSAI_URL\" # provided with your api key\n```\n\nNow if you run `forge test` with `RISC0_DEV_MODE=false`, the test will run as before, but will additionally use the fully verifying `RiscZeroGroth16Verifier` contract instead of `MockRiscZeroVerifier` and will request a SNARK receipt from Bonsai.\n\n```bash\nRISC0_DEV_MODE=false forge test -vvv\n```\n\n### Deterministic Builds\n\nBy setting the environment 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 [image ID][image-id].\nThe [image ID][image-id], and its importance to security, is explained in more detail in our [developer FAQ][faq].\n\n```bash\nRISC0_USE_DOCKER=1 cargo build\n```\n\n\u003e ***Note:*** *This requires having Docker installed and in your PATH. To install Docker see [Get Docker][install-docker].*\n\n## Deploy Your Application\n\nWhen you're ready, follow the [deployment guide](./deployment-guide.md) to get your application running on [Sepolia][sepolia] or Ethereum Mainnet.\n\n## Project Structure\n\nBelow are the primary files in the project directory\n\n```text\n.\n├── Cargo.toml                      // Configuration for Cargo and Rust\n├── foundry.toml                    // Configuration for Foundry\n├── apps\n│   ├── Cargo.toml\n│   └── src\n│       └── lib.rs                  // Utility functions\n│       └── bin                     \n│           └── publisher.rs        // Example app to publish program results into your app contract \n├── contracts\n│   ├── EvenNumber.sol              // Basic example contract for you to modify\n│   └── ImageID.sol                 // Generated contract with the image ID for your zkVM program\n├── methods\n│   ├── Cargo.toml\n│   ├── guest\n│   │   ├── Cargo.toml\n│   │   └── src\n│   │       └── bin                 // You can add additional guest programs to this folder\n│   │           └── is_even.rs      // Example guest program for checking if a number is even\n│   └── src\n│       └── lib.rs                  // Compiled image IDs and tests for your guest programs\n└── tests\n    ├── EvenNumber.t.sol            // Tests for the basic example contract\n    └── Elf.sol                     // Generated contract with paths the guest program ELF files.\n```\n\n[docs-bonsai]: https://dev.risczero.com/api/generating-proofs/remote-proving\n[install-foundry]: https://getfoundry.sh/\n[install-docker]: https://docs.docker.com/get-docker/\n[groth16]: https://www.risczero.com/news/on-chain-verification\n[docs-verifier]: https://dev.risczero.com/api/blockchain-integration/contracts/verifier\n[docs-zkvm]: https://dev.risczero.com/zkvm\n[homepage-risczero]: https://www.risczero.com/\n[Sepolia]: https://www.alchemy.com/overviews/sepolia-testnet\n[blog-coprocessor]: https://www.risczero.com/news/a-guide-to-zk-coprocessors-for-scalability\n[faq]: https://dev.risczero.com/faq#zkvm-application-design\n[image-id]: https://dev.risczero.com/terminology#image-id\n[install-rust]: https://doc.rust-lang.org/cargo/getting-started/installation.html\n[term-journal]: https://dev.risczero.com/terminology#journal\n[steel-repo]: https://github.com/risc0/risc0-ethereum/tree/main/crates/steel\n[erc20-counter]: https://github.com/risc0/risc0-ethereum/tree/main/examples/erc20-counter\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisc0%2Frisc0-foundry-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frisc0%2Frisc0-foundry-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisc0%2Frisc0-foundry-template/lists"}