SP1 ICS07-Tendermint IBC Light Client

This is an ICS-07 IBC light client on Ethereum powered by SP1 and ibc-rs.

Table of Contents

• SP1 ICS07-Tendermint IBC Light Client
  • Table of Contents
  • Overview
    • Project Structure
    • Programs
  • Requirements
  • Build the programs
  • Run ICS-07 Tendermint Light Client End to End
  • EVM-Compatible Proof Generation & Verification
    • Solidity Proof Verification
  • End to End Testing

Overview

sp1-ics07-tendermint is a ZK IBC tendermint light client on Ethereum that can:

• Update the client with new consensus states
• Verify the membership of any key-value pair in the counterparty's state at a given height.
• Verify the non-membership of any key in the counterparty's state at a given height.
• Detect misbehaviour in the counterparty's consensus (e.g. double signing, non-monotonic heights).

Project Structure

This project is structured as a cargo workspace with the following directories:

• The contracts directory contains a Solidity contract that implements the ICS-07 Tendermint light client which can verify SP1 proofs. This is a foundry project, and not a part of the cargo workspace.
• The operator directory contains a Rust program that interacts with the Solidity contract. It fetches the latest header (although it could also fetch historical headers) and generates a proof of the update using ibc-rs, and then updates the contract with the proof. It also contains several scripts to generate fixtures and proofs for testing.
• The programs directory contains the SP1 programs that are compiled to RiscV and run on the SP1's zkVM.
• The packages directory contains a shared rust library that is used by the operator and programs directories.

Programs

This project contains the following SP1 programs:

Programs	Description	Status
update-client	Once the initial client state and consensus state are submitted, future consensus states can be added to the client by submitting IBC Headers. These headers contain all necessary information to run the Comet BFT Light Client protocol. Also supports partial misbehavior check.	✅
membership	As consensus states are added to the client, they can be used for proof verification by relayers wishing to prove packet flow messages against a particular height on the counterparty. This uses the verify_membership and verify_non_membership methods on the tendermint client.	✅
uc-and-membership	This is a program that combines update-client and membership to update the client, and prove membership of packet flow messages against the new consensus state.	✅
misbehaviour	In case, the malicious subset of the validators exceeds the trust level of the client; then the client can be deceived into accepting invalid blocks and the connection is no longer secure. The tendermint client has some mitigations in place to prevent this.	✅

Contracts

This project contains the following Solidity contracts and libraries (interfaces are not included):

Contract	Description
SP1ICS07Tendermint.sol	The light client contract, and the entry point for SP1 proofs.
UnionMembership.sol	A library wrapping Union's ICS23 implementation for verifying (non)membership purely in solidity (without SP1).

Requirements

• Rust
• SP1
• Foundry
• Bun
• Just

Foundry typically uses git submodules to manage contract dependencies, but this repository uses Node.js packages (via Bun) because submodules don't scale. You can install the contracts dependencies by running the following command:

bun install

Tip

Nix users can enter a development shell with all the necessary dependencies by running:

nix-shell shell.nix

Build the programs

You should build the programs for zkVM by running the following command:

just build-programs

The programs will be built in the elf/ directory which is ignored by .gitignore but are needed for the operator to build.

Run ICS-07 Tendermint Light Client End to End

1. Set the environment variables by filling in the .env file with the following:

   cp .env.example .env

   You need to fill in the PRIVATE_KEY, SP1_PROVER, TENDERMINT_RPC_URL, and RPC_URL. You also need the SP1_PRIVATE_KEY field if you are using the SP1 prover network.

2. Deploy the SP1ICS07Tendermint contract:

   just deploy-contracts

   This will generate the contracts/script/genesis.json file which contains the initialization parameters for the contract. And then deploy the contract using contracts/script/SP1ICS07Tendermint.s.sol. If you see the following error, add --legacy to the command in the justfile:

   Error: Failed to get EIP-1559 fees    
   

3. Your deployed contract address will be printed to the terminal.

   == Return ==
   0: address <CONTRACT_ADDRESS>
   

   This will be used when you run the operator in step 5. So add this to your .env file.

   CONTRACT_ADDRESS=<CONTRACT_ADDRESS>

4. Run the Tendermint operator.

   To run the operator, you need to select the prover type for SP1. This is set in the .env file with the SP1_PROVER value (network|local|mock). If you run the operator with the network prover, you need to provide your SP1 network private key with SP1_PRIVATE_KEY=0xyourprivatekey in .env.

   just operator

EVM-Compatible Proof Generation & Verification

Warning

You will need at least 128GB RAM to generate the PLONK proofs locally.

Here, I will show you how to generate a proof to be used in the fixtures for the foundry tests. You can do this locally or by using the SP1 prover network. To do this on your local machine, run the following command:

just fixtures local

To use the SP1 prover network, set SP1_PROVER=network and provide your SP1 network private key with SP1_PRIVATE_KEY="0xyourprivatekey in the .env file. After this, you can run the following command:

just fixtures network

Solidity Proof Verification

After generating the verify the proof with the SP1 EVM verifier.

just test-foundry

The recipe also accepts a testname argument that will only run the test with the given name. For example:

just test-foundry test_success_sendTransfer

End to End Testing

There are several end-to-end tests in the e2e/interchaintestv8 directory. These tests are written in Go and use the interchaintest library. It spins up a local Ethereum and a Tendermint network and runs the tests found in e2e/interchaintestv8/sp1_ics07_test.go. Some of the tests use the prover network to generate the proofs, so you need to provide your SP1 network private key to .env for these tests to pass.

Note

If you are running on a Mac with an M chip, you will need to do the following:

• Set up Rosetta

• Enable Rosetta for Docker (in Docker Desktop: Settings -> General -> enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon")

• Pull the foundry image with the following command:

  docker pull --platform=linux/amd64 ghcr.io/foundry-rs/foundry:latest

To run the tests, run the following command:

just test-e2e $TEST_NAME

Where $TEST_NAME is the name of the test you want to run, for example:

just test-e2e TestDeploy