CI risc0

Zeam — Zig Beam Client

Zeam is a production-grade implementation (work-in-progress) of the Beam Chain — a ZK-based Ethereum Consensus Protocol unveiled at Devcon 7 Bangkok (November 2024). Beam Chain is designed to upgrade the current Beacon Chain by massively scaling and decentralizing Ethereum consensus through provable, ZK-VM-backed state transitions.

---

Table of Contents

• Overview
• Beam Chain
• Client Architecture
• Package Structure
• ZK Prover Support
• Libraries & Ecosystem
• Build Instructions
• Running a Local Devnet
• Testing
• Community & Contributions
• Reporting Issues

---

Overview

Beam Chain introduces several disruptive improvements to Ethereum consensus that are difficult to implement incrementally on the current Beacon Chain:

• ZK-provable state transitions — every state transition can be proven and verified by a ZK-VM
• Quantum-resistant cryptography — hash-based signatures (XMSS) replacing BLS
• Decentralized consensus — designed to scale and decentralize at the protocol level

Zeam translates these specs into a production-grade Zig client, actively contributing to the development of the Beam protocol alongside other client teams.

---

Beam Chain

• Beam Chain Developments & Resources
• Zeam & Beam Wiki
• Beam Chain Devcon 7 Announcement

---

Client Architecture

Zeam's architecture closely mirrors the Beacon Chain client structure, adapted for Beam's ZK-centric design. The client is built modularly, with each concern separated into its own package.

Development Status

The team is currently building and validating foundational POCs and libraries before composing them into a full client:

Refer to ZEAM POC for detailed documentation on the current POC scope and design.

---

Package Structure

The pkgs/ directory contains the modular components of the Zeam client:

---

ZK Prover Support

Zeam supports multiple ZK-VMs for state transition proving:

---

Libraries & Ecosystem

Zeam is developing and contributing to the Zig Ethereum ecosystem. These libraries are used in and alongside the client:

If you are developing a library in the Zig ecosystem that could benefit Zeam, please reach out via Telegram.

---

Build Instructions

Prerequisites

• Zig 0.16.0
• Rust 1.85+ (required for ZK-VM Rust bindings)
• risc0 toolchain (only if using risc0 prover): rzup install r0vm 3.0.3
  • Install guide: https://dev.risczero.com/api/zkvm/install
• OpenVM is self-contained — no additional toolchain required

Building

Build all transition functions and the full client:

zig build -Doptimize=ReleaseFast

To include the git version in the binary:

zig build -Doptimize=ReleaseFast -Dgit_version="$(git rev-parse --short HEAD)"

Running the Prover Demo

zig build -Doptimize=ReleaseFast install run -- prove

Docker

Docker images are built in CI using Dockerfile.prebuilt, which packages pre-built binaries. This avoids intermittent failures caused by a Zig HTTP connection pool bug when building inside Docker.

Build a Docker image locally:

# Build zeam natively first
zig build -Doptimize=ReleaseFast -Dgit_version="$(git rev-parse --short HEAD)"

# Then create Docker image with pre-built binary
docker build -f Dockerfile.prebuilt -t zeam:local .

Build with OCI labels for registry publishing:

docker build -f Dockerfile.prebuilt \
  --build-arg GIT_COMMIT=$(git rev-parse HEAD) \
  --build-arg GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD) \
  -t blockblaz/zeam:latest .

Troubleshooting

Build fails with EndOfStream error

If you encounter errors like:

error: invalid HTTP response: EndOfStream

This may be caused by proxy environment variables interfering with Zig's HTTP client (related to the Zig HTTP connection pool bug mentioned above).

Try building without proxy settings:

env -u https_proxy -u HTTPS_PROXY -u http_proxy -u HTTP_PROXY \
    -u all_proxy -u ALL_PROXY -u no_proxy -u NO_PROXY \
    zig build -Doptimize=ReleaseFast

---

Running a Local Devnet

To run a local devnet with multiple nodes for testing and development, see the Local Devnet Setup Guide, which covers a 2-node setup with finalization.

Alternatively, use the lean-quickstart submodule:

git submodule update --init lean-quickstart

This provides a handy CLI tool to spin up two nodes for local interop.

Checkpoint Sync

Zeam supports checkpoint sync for faster initial synchronization. Start a node from a trusted finalized checkpoint state using the --checkpoint-sync-url flag. See the Local Devnet Setup Guide for full documentation.

---

Testing

---

Community & Contributions

Join the conversation around Beam Protocol and Zeam client:

• Telegram community
• X / Twitter (@zeamETH)
• Zeam & Beam Wiki
• Community calls archive

Zeam welcomes open-source contributions that meaningfully advance the client. Watch for announcements in the community or reach out directly via Telegram.

---

Reporting Issues

Open a GitHub issue or reach out via the Telegram community group.