Celestia zkEVM

Warning

This repository is a work in progress and under active development.

This repository showcases a bridged token transfer between Celestia and a ZK proveable EVM via Hyperlane. For more information refer to the architecture. Note that the design is subject to change.

Usage

Preamble

SP1 supports generating proofs in mock mode or network mode. By default, mock mode is used which is faster for testing and development purposes. Network mode is used for production purposes to generate real proofs. To use network mode, modify your .env file:

SP1_PROVER=network
NETWORK_PRIVATE_KEY="PRIVATE_KEY" to the SP1 prover network private key from Celestia 1Password

Prerequisites

1. Install Docker
2. Install Foundry
3. Install Rust
4. Install SP1

Running a local network with Docker

1. Clone this repository.

   git clone [email protected]:celestiaorg/celestia-zkevm-hl-testnet.git

2. Source the provided .env file in this repository.

   cp .env.example .env
   
   set -a
   source .env
   set +a

3. Start the docker compose services.

   # Run `make start` or `docker compose up` from the root of the repository
   make start 

4. Allow the hyperlane-init service to complete the provisioning of Hyperlane EVM contracts and cosmosnative components.

   # Stream the logs via Docker to observe the status.
   docker logs -f hyperlane-init

5. Run a Hyperlane warp transfer, bridging utia from celestia to the reth service.

   make transfer

6. Query the ERC20 balance of the recipient on the reth service.

   make query-balance

7. Transfer funds back from the ERC20 contract to celestia.

   make transfer-back

8. Stop and teardown docker compose services.

   make stop

Running the E2E test

1. Clone this repository.

   git clone [email protected]:celestiaorg/celestia-zkevm-hl-testnet.git

2. Source the provided .env file in this repository.

   cp .env.example .env
   
   set -a
   source .env
   set +a

3. Select a prover mode other than mock. Valid choices are network, cuda, cpu. in .env:

   SP1_PROVER=cpu #network, cuda

4. Use the prover service binary to generate config files locally.

   cargo run --bin ev-prover init
   

   Alternatively, install the client binary and run init:

   cargo install --path ./crates/ev-prover
   ev-prover init
   

5. Initialize the Docker network Start all services (ev-reth, ev sequencer, celestia)

   # Run `make start` or `docker compose up` from the root of the repository
   make start 

   Wait for all containers to finish their initialization sequence.

   Next, deploy and update the ZKISM:

   make deploy-ism

   make update-ism

6. Run the e2e

   RUST_LOG="e2e=info" make e2e

   Note that depending on your hardware it can take a while for the e2e to run, as it will prove a series of EVM blocks leading up to a target height, as well as state inclusion of a Hyperlane deposit message at the target height.

Start the Prover Service

You will find detailed documentation on how to run the joint hyperlane message and block prover service ev-prover here.

Architecture

See ARCHITECTURE.md for more information.

Benchmarking

See Benchmarks for more information.

Context

The objective of this project is to establish a ZK bridge from the Celestia base-layer to a Celestia rollup and back. The sequencer of each rollup submits tx blobs to the base-layer that are used to build the EVM blocks, which are then verified against a previous, trusted EVM block from that same rollup. In order to facilitate transfers from one Celestia rollup to another, a forwarding module will be introduced to the base-layer in the future.

This ZK bridge is internal to the Celestia ecosystem, meaning that generic EVM chains, like Ethereum, which exist outside Celestia, will require a connection to the base-layer. This connection will usually be a ZK light client, such as SP1-Helios, that submits proofs and header roots to the base-layer's ISM module.

Contributing

See CONTRIBUTING.md for more information.