SP1 Helios

Overview

Implementation of an ZK Ethereum light client using the Altair sync committee with SP1 and Helios.

  • /program: The SP1 Helios program.
  • /primitives: Libraries for types and helper functions used in the program.
  • /script: Scripts for getting the contract's genesis parameters and deploying the operator to update the light client.

Deployment

Overview

SP1 Helios verifies the consensus of a source chain in the execution environment of a destination chain. For example, you can run an SP1 Helios light client on Polygon that verifies Ethereum Mainnet's consensus.

Prerequisites

Steps

1. Consensus RPC Setup

To run SP1 Helios, you need a Beacon Chain node for your source chain. For example, to run an Ethereum mainnet light client, you need an Ethereum mainnet beacon node.

The beacon chain node must support the RPC methods for the Altair light client protocol. As of 10/15/24, Nimbus is the only consensus client that supports these "light sync" endpoints by default.

There are a few options for setting up a consensus RPC with "light sync" endpoints:

  1. Get an RPC from a provider running Nimbus nodes. Chainstack is currently the only provider we're aware of that supports this. Set up a node on Chainstack and use the consensus client endpoint for an Ethereum mainnet node.
  2. Run a Nimbus eth2 beacon node. Instructions here.
  3. There is a community-maintained list of Ethereum Beacon Chain light sync endpoints here. These endpoints are not guaranteed to work, and are often unreliable.

The RPC you just set up will be used as the SOURCE_CONSENSUS_RPC_URL in the next step.

Provide a source execution RPC as --source-execution-rpc for genesis and operator commands. It must serve full block headers with eth_getBlockByHash and eth_getBlockByNumber. Storage requests also need eth_getProof for the selected source block. The source execution RPC must use the same chain as the consensus RPC. The destination RPC serves the chain where the SP1 Helios smart contract is deployed.

Gloas light-client headers commit an execution block hash. The operator supplies the full header for that hash, and the SP1 program checks its RLP hash before using execution fields. This hash identifies the parent execution block from the signed payload bid. Its execution block can lag the beacon slot when payloads are skipped.

2. Deploy Contract

Deploy the SP1 Helios contract, note, this requires Foundry, and a PLONK verifier gateway:

cargo run --bin genesis -- [--private-key] [--ledger] [--etherscan-api-key] <--sp1-verifier-address> <--guardian-address> <--source-consensus-rpc> <--source-execution-rpc> <--source-chain-id>

When the script completes, take note of the light client contract address printed to the terminal.

3. Run Light Client

To run the operator, which generates proofs and keeps the light client updated with chain state:

cargo run --release --bin operator -- <--rpc-url> <--contract-address> <--source-chain-id> <--source-consensus-rpc> <--source-execution-rpc> <--private-key>

The operator requests proofs through the Succinct Prover Network. Configure the requester key, fulfillment strategy, and proof mode in .env; see .env.example for the supported values.

Rebuild the program ELFs when changing the Helios dependency or SP1 program source. Run cargo run --bin vkey to derive the keys from the rebuilt programs. Coordinate the smart contract's program key changes with the operator's program update.

If successful, you should see logs indicating that the consensus state is being updated:

[2024-10-15T21:01:19Z INFO  operator] Starting SP1 Helios operator
[2024-10-15T21:01:20Z WARN  helios::consensus] checkpoint too old, consider using a more recent block
[2024-10-15T21:01:20Z INFO  operator] Contract is up to date. Nothing to update.
[2024-10-15T21:01:20Z INFO  operator] Sleeping for 5 minutes
...
[2024-10-15T21:06:35Z INFO  operator] New head: 6107648
[2024-10-15T21:06:50Z INFO  operator] Transaction hash: 0x4a0dfa2922704295ed59bf16840454858a4d17225cdf613387de7605b5a41520
[2024-10-15T21:06:50Z INFO  operator] Sleeping for 5 minutes

Components

An SP1 Helios implementation has a few key components:

  • An SP1Helios contract. Contains the logic for verifying SP1 Helios proofs, storing the latest data from the Ethereum beacon chain, including the headers, execution state roots and sync committees.
  • An SP1Verifier contract. Verifies arbitrary SP1 programs. Most chains will have canonical deployments upon SP1's mainnet launch. Until then, users can deploy their own SP1Verifier contracts to verify SP1 programs on their chain. The SP1 Helios implementation will use the SP1Verifier contract to verify the proofs of the SP1 Helios program.
  • The SP1 Helios program. An SP1 program that verifies the consensus of a source chain in the execution environment of a destination chain using the helios library.
  • The operator. A Rust script that fetches the latest data from a deployed SP1Helios contract and an Ethereum beacon chain, determines the block to request, requests for/generates a proof, and relays the proof to the SP1Helios contract.

Frequently Asked Questions

How do I prove data on Ethereum against an SP1 Helios light client?

The SP1 Helios light client validates the Ethereum beacon chain's headers are signed correctly by the Altair sync committee. The Helios library verifies that the execution payload in the beacon chain's header is correct here.

You can use storage proofs to Merkle prove data in the Merkle Patricia Trie against the execution state root.

Reproducible Builds

Overview

Verify the program ELFs before you use them to generate proofs. Run these commands from the repository root of the release you want to verify.

Prerequisites

Install the SP1 toolchain.

Use the SP1 version that built the checked-in ELFs:

sp1up --version 6.10.0

Check the installed version:

cargo prove --version

Rebuild the program ELFs

Check that Docker is running:

docker ps

Build all three programs with the pinned Docker image and lockfile:

cd program
cargo prove build --docker --tag v6.10.0 --locked --output-directory ../elf
cd ..
git diff --exit-code -- elf/

The diff check succeeds when the rebuilt ELFs match the checked-in files.

Verify the program keys

Derive the verification keys from the rebuilt ELFs:

SP1_SKIP_PROGRAM_BUILD=true cargo run --locked --release -p sp1-helios-script --bin vkey

Compare each key with the corresponding key configured in the SP1 Helios smart contract. See the deployment guide for program key updates.