Skip to main content
Version: 0.19

Bonsai on Ethereum

Warning: Bonsai is still in early development. Do not use in production.

Bonsai can produce SNARK proofs; allowing efficient verification of any computation, on Ethereum.

There are two main ways to integrate your RISC Zero application with Ethereum:

  • Using the Bonsai Relay to process proof requests and send verified results on-chain.
  • Using the Bonsai proving service and the verifier contract directly.

Bonsai Relay

The Bonsai Relay is a service makes it simpler to integrate RISC Zero into your applications, leveraging the zk coprocessor model.

At a high level, here's how it works:

Bonsai ETH Relay overview

  1. Your application sends a request to run your zkVM guest to the Bonsai Relay. You can either:
    • Send your request on-chain, by calling requestCallback on the BonsaiRelay contract.
    • Send your request off-chain, by sending a request to the Bonsai Relay REST API.
  2. The Bonsai Relay sends the proof request to the Bonsai proving service.
  3. Bonsai generates a Groth16 SNARK proof of the guest execution, and submits the receipt to the BonsaiRelay contract.
  4. The BonsaiRelay contract:
    1. Verifies the receipt by using an IRiscZeroVerifier contract
    2. Extracts the journal from the verified receipt.
    3. Sends the journal and image ID in a callback to your application contract.

Getting Started

The Bonsai Foundry Template provides a template and instructions for developing your application with the Bonsai Relay. More details are provided below on how to send requests to the Bonsai Relay.

Running the Bonsai Relay

With Bonsai in alpha, every application currently needs to run their own deployment of the Bonsai Relay. Instructions are included in the Bonsai Foundry Template. This involves running a service binary provided by RISC Zero, and deploying the BonsaiRelay contract

Off-chain Requests

The Bonsai Relay accepts requests off-chain using its REST API.

Using the off-chain API allows for including data not available to smart contracts in the EVM, and avoids needing to pay transaction fees on Ethereum to initiate a request. When inputs to your guest program and large (e.g. more than a few kilobytes) sending requests on-chain can be cost-prohibitive, while sending large inputs (e.g. up to tens of megabytes) via the REST API has no additional cost.

The Bonsai Relay SDK provides a Rust interface for interacting with the Bonsai Relay. An example for sending a callback request via the REST API can be found in the relay directory of the Bonsai Foundry Template.

On-chain Requests

The Bonsai Relay also accepts requests on-chain using the BonsaiRelay contract.

On-chain requests can be useful for reducing the amount of code you need to maintain. When submitting requests off-chain, some client or indexer needs to be written to assemble the inputs and make the request to the Bonsai Relay. With on-chain requests, the application smart contract can directly issue requests, and so no client or indexer needs to be written or maintained.

An example of sending a request on-chain can be found in the starter contract of the Bonsai Foundry Template.

Verifier Contract

RISC Zero supports an on-chain verifier for Groth16 SNARK proofs generated by the Bonsai proving service. You can use this contract in your applications.

As described above, the Bonsai Relay forwards requests to the Bonsai proving service, and sends proofs on-chain to be verified in the authentication for for the BonsaiRelay contract. An alternative to using the Bonsai Relay is to send requests to the Bonsai proving service directly, and to use the verifier contract in your own application contract.

The verifier contract has the IRiscZeroVerifier interface. This interface defines the relevant data structures for the receipt and provides a verify method.

The IRiscZeroVerifier interface is implemented by the RiscZeroGroth16Verifier contract. While Bonsai is in alpha, you will deploy this contract as part of your application.

The Bonsai SDK provides support for sending requests to the Bonsai proving service. You may also want to check out our Bonsai Quick Start page and/or the Bonsai Overview.