risc0/risc0-ethereum

Integration of the RISC Zero verifiable compute platform with Ethereum and EVM chains.

Important

main is the development branch. Application developers should use the latest release instead.

RISC Zero Ethereum

RISC Zero is a zero-knowledge verifiable general computing platform, with Ethereum integration. This repository contains Solidity verifier contracts, Relay, Steel EVM view call library, and supporting code.

If you are looking to get started using RISC Zero in the application on Ethereum, the best place to look is the Foundry template.

You can also find the documentation for RISC Zero, including guides for writing zkVM programs, using the Bonsai prover, and more at dev.risczero.com.

Contracts

RISC Zero's Ethereum contracts, including the on-chain verifier for all RISC Zero Groth16 proofs, can be found in the contracts directory.

Steel

A powerful library for querying and generating verifiable proofs over Ethereum or other EVM-based blockchain state. It leverages alloy, giving developers a familiar and high quality interface for querying Ethereum via view calls. Steel makes it easy to securely move execution off chain saving gas and unlocking new use cases on Ethereum.

You can install Steel with cargo add risc0-steel, check out the examples in the examples directory.

Relay

The Relay is a service that can be run to accept proving requests from on-chain events or via REST Request, and post receipts to the developer's application contract as a callback. It represents one way of accepting requests, and posting proofs to Ethereum. It is also possible to write your application without using the Relay.

You can find and overview of how the Relay works, in our documentation. Source code for the Relay is in the relay directory.

risc0-ethereum's Issues

`forge install risc0/risc0-ethereum` results in a failed build

It appears that there may be a similar issue with forge init -t rics0/bonsai-foundry-template

`sccache` not being properly invalidated on changes to `.sol` files

Changes to .sol files are not properly invalidating the sccache. This is likely fixed by adding a println! to build.rs to ensure that we rebuild if any of the .sol files that are used change.

Example of a failing run:
https://github.com/risc0/risc0-ethereum/actions/runs/9037664809/job/24837174330

Link reproducible builds into the Foundry template

This could be documentation or code/script to make it easier to figure out the imageid and plug it into a solidity contract.

Consider lowering the minimum required Solidity version in our risc0-ethereum contracts.

Support compositions in the forge ffi prove function

Forge FFI is used in the tests to call out to external programs, and in our testing code is used to generate receipts that can then be used to test receipt-authorized logic. This functionality is also referred to as cheat codes. The prove cheat code used in tests supports only a subset of the prover API, and one particularly useful feature that we would like to support is providing assumption receipts for composition.

Solidity compilation can sometimes fail with error about `isDevMode()`

Document feature flags for view call proof lib on docs.rs

Check that the control ID root is up to date as part of CI

Drop postStateDigest from IRiscZeroVerifier.verify

Following risc0/risc0#1690, the postStateDigest is now zeroed when exiting with Halt. As a result, we should drop it from the IRiscZeroVerifier.verify function signature.

Move the governance example from risc0

With risc0/risc0#1525 we want to drop all ethereum related crates from risc0. We should move the current version of the governance or un updated one on this repo, and adjust the links on the risc0 website to point on this repo

Update alloy and revm dependencies

I ran into an issue when trying to release 0.10 due to inconsistent versions of alloy and revm. It does not appear when the Cargo.lock file is in use, but will effect downstream users. I mitigated the issue on the release-0.10 branch in #85. Fixing it on main should be done by updating the dependencies.

Refactor Governance example to use the new foundry template

• Should move the Governance example from risc0/ repo to risc0/ethereum
• Should close #7 alongside this one.
• Update doc links to the new repository risc0-ethereum

[docs] correct enumeration of "key contracts"

the enumeration of key contracts in the contracts readme is self-contradictory -- it says "the 2 key contracts you'll need [as a user]..." and then goes on to enumerate 4 contracts (only some of which you need to think about as a user)

Use Anvil for view call library examples

Foundry team fixed the bugs in Anvil that were previously preventing usage of Anvil for local development with the view call library. We can now use it, and should update instructions and scripts.

Fix CI integration with RISC Zero monorepo

Three issues currently exist:

• Git submodule checkout is failing: https://github.com/risc0/risc0/actions/runs/8514140789/job/23319263768
• We need an updated local patching for risc0-ethereum-view-call
• Warning due to conflicting name: methods

Fix documentation on the `CONTROL_ID` constants in the `RiscZeroGroth16Verifier.sol`

Comment highlighted below is inaccurate:

risc0-ethereum/contracts/src/groth16/RiscZeroGroth16Verifier.sol

Lines 89 to 95 in 37e4cb9

	/// @notice Control ID hash for the identity_p254 predicate decomposed by `splitDigest`.
	/// @dev This value controls what set of recursion programs, and therefore what version of the
	/// zkVM circuit, will be accepted by this contract. Each instance of this verifier contract
	/// will accept a single release of the RISC Zero circuits.
	///
	/// New releases of RISC Zero's zkVM require updating these values. These values can be
	/// obtained by running `cargo run --bin bonsai-ethereum-contracts -F control-id`

Document the risc0-ethereum release process

• Document that the development branch is main.
• Document the release/* branch strategy.
• Document the expectations of tags.
• Document cargo publish including which ones are published.
• Deploy a new verifier contract when changes to the contract are needed.
  • Document the address in the dev.risczero.com docs
  • Verify the source code on e.g. Etherescan
• Add verifier to RISC Zero managed mux

Move contracts and related code into this repo from risc0

Mark old crate names for renamed crates as deprecated

We have three crates that have been renamed, but their old names are still published on crates.io without any notes.

• bonsai-ethereum-relay
• bonsai-ethereum-contracts
• risc0-ethereum-view-call

We should mark these as deprecated in some way.

Update risc0-ethereum main branch to point to risc0 main branch

Improve handling of the view call env for multiple view calls

Feedback from @austinabell in his usage of the Steel view call library.

When making multiple view calls within a single guest execution with Steel, there is a problem that the ViewCallEnv cannot be cloned, but the execute method consumes the object.

Fix Soldiity compiler warnings due to payable fallback function

Warning (3628): This contract has a payable fallback function, but no receive ether function. Consider adding a receive ether function.
  --> lib/risc0-ethereum/contracts/src/relay/BonsaiRelayQueueWrapper.sol:26:1:
   |
26 | contract BonsaiRelayQueueWrapper is IBonsaiRelay, Proxy, Test {
   | ^ (Relevant source part starts here and spans across multiple lines).
Note: The payable fallback function is defined here.
  --> lib/openzeppelin-contracts/contracts/proxy/Proxy.sol:66:5:
   |
66 |     fallback() external payable virtual {
   |     ^ (Relevant source part starts here and spans across multiple lines).

Implement on-chain verifier version management

Write a tutorial walking through a basic project with Foundry

Fix `risc0-ethereum-relay` ignored e2e tests

In risc-ethereum-relay there are some e2e tests that are currently marked as ignored. Unfortunately, the tests are broken right now, and need some work to get running in CI again.

Update OpenZeppelin dependencies

Refactor Soldity types in view call library to be defined in `.sol` files instead of using the `sol!` macro

One rough edge in the view call library is that the BlockCommitment type is defined only in the Rust source code through a sol! macro. As a result, it is difficult to use in Solidity smart contracts to build upon it. Moving BlockCommitment and any other Solidity types into contracts that can be imported into smart contract projects would improve the developer experience.

Add Solidity linting and improve coverage for formatting in CI

• No linter is currently run on the Solidity code in CI.
• Cargo.toml files in examples are not currently covered by Cargo sort.
• Cargo.lock files are not ensured to not change.

Variable length ReceiptClaim encoding for use in Solidity

One of the friction points with the Eth Verifirer API is that the user has to drag around the post_state_digest. It is a field only needed to construct the receipt claim digest, and not a detail users need to concern themselves with, yet it pollutes the API.

By using a variable length encoding, it would be possible to have a ReceiptClaim type that optionally includes various components, including the post state digest. Action here is to implement this variable length encoding, and then use it to simplify the verifier API.

Move `bonsai-rest-api-mock` from risc0

The bonsai-rest-api-mock crate is only used by the relay. It should be tune down as an internal utility so that we can lower the burden on the risc0 release process

Drop the dockerfile from Foundry template

Run `forge doc` in CI

We want to run forge doc in CI to make sure docs are working, and ensure they are up to date when these docs are published. Unfortunately, there is an issue preventing forge doc from working.

$ forge doc --root contracts
Error:
prefix not found

Related: foundry-rs/foundry#4533

Rust analysers runs will override Elf.sol and ImageID.sol files

Part of the root cause is that we are we are abusing the build script by writing to a shared directory, instead of the build outputs.

Use independent CLI tool with Forge FFI for getting proofs in Solidity tests

Use POSIX I/O for view call proofs

Currently, the view call proof library uses stdin and env::read to get it's required inputs, namely the Merkle inclusion proofs for the storage slots accessed in view call execution. This introduces from devex complications in that the developer needs to redefine the inputs to include this data.

By using POSIX I/O, this communication can be done out of band to user execution, and the details can be made internal to the view call library itself.

Depends on risc0/risc0-foundry-template#91

[Feature] Load groth16 proofs from disk

From @mothran feedback: "I would also love an example of having a unit test with the proof is baked on disk + script to regenerate all the proof test data. Because generally I don't need to rerun the proof for each forge test through bonsai/locally, if we had a cheat code to get the data like seal + journal + post_state from a .json on disk that would be awesome"