{"id":28083243,"url":"https://github.com/blockblaz/zeam","last_synced_at":"2026-05-25T04:04:32.552Z","repository":{"id":265948607,"uuid":"865514253","full_name":"blockblaz/zeam","owner":"blockblaz","description":"Ethereum Lean client in Zig (wip)","archived":false,"fork":false,"pushed_at":"2026-05-21T20:38:54.000Z","size":7308,"stargazers_count":93,"open_issues_count":105,"forks_count":39,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-21T20:43:50.917Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blockblaz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-09-30T16:52:00.000Z","updated_at":"2026-05-21T20:35:20.000Z","dependencies_parsed_at":"2025-01-10T17:25:08.950Z","dependency_job_id":"23774cee-acde-47b5-b3c0-936544eb4a93","html_url":"https://github.com/blockblaz/zeam","commit_stats":null,"previous_names":["blockblaz/zeam"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/blockblaz/zeam","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockblaz%2Fzeam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockblaz%2Fzeam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockblaz%2Fzeam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockblaz%2Fzeam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blockblaz","download_url":"https://codeload.github.com/blockblaz/zeam/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockblaz%2Fzeam/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33459711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T02:24:28.008Z","status":"ssl_error","status_checked_at":"2026-05-25T02:23:23.339Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-13T09:00:56.105Z","updated_at":"2026-05-25T04:04:32.547Z","avatar_url":"https://github.com/blockblaz.png","language":"Zig","funding_links":[],"categories":["Network \u0026 Web","3. Lean Consensus"],"sub_categories":["Web3 Framework","Implementations"],"readme":"\n\n[CI](https://github.com/blockblaz/zeam/actions/workflows/ci.yml)\n[risc0](https://github.com/blockblaz/zeam/actions/workflows/risc0.yml)\n\n# Zeam — Zig Beam Client\n\nZeam is a production-grade implementation (work-in-progress) of the [Beam Chain](https://www.youtube.com/watch?v=Gjuenkv1zrw) — 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.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Beam Chain](#beam-chain)\n- [Client Architecture](#client-architecture)\n- [Package Structure](#package-structure)\n- [ZK Prover Support](#zk-prover-support)\n- [Libraries \u0026 Ecosystem](#libraries--ecosystem)\n- [Build Instructions](#build-instructions)\n- [Running a Local Devnet](#running-a-local-devnet)\n- [Testing](#testing)\n- [Community \u0026 Contributions](#community--contributions)\n- [Reporting Issues](#reporting-issues)\n\n---\n\n## Overview\n\nBeam Chain introduces several disruptive improvements to Ethereum consensus that are difficult to implement incrementally on the current Beacon Chain:\n\n- **ZK-provable state transitions** — every state transition can be proven and verified by a ZK-VM\n- **Quantum-resistant cryptography** — hash-based signatures (XMSS) replacing BLS\n- **Decentralized consensus** — designed to scale and decentralize at the protocol level\n\nZeam translates these specs into a production-grade Zig client, actively contributing to the development of the Beam protocol alongside other client teams.\n\n---\n\n## Beam Chain\n\n- [Beam Chain Developments \u0026 Resources](./resources/beam.md)\n- [Zeam \u0026 Beam Wiki](https://github.com/blockblaz/zeam/wiki)\n- [Beam Chain Devcon 7 Announcement](https://www.youtube.com/watch?v=Gjuenkv1zrw)\n\n---\n\n## Client Architecture\n\nZeam'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.\n\n### Development Status\n\nThe team is currently building and validating foundational POCs and libraries before composing them into a full client:\n\n\n| Area                           | Status            |\n| ------------------------------ | ----------------- |\n| ZK-VM state transition proving | Active POC        |\n| libp2p networking (Zig ↔ Rust) | POC complete      |\n| SSZ serialization              | Library available |\n| Hash-based signatures (XMSS)   | In development    |\n| Snappy compression             | Library available |\n| Full client integration        | Upcoming          |\n\n\nRefer to [ZEAM POC](./resources/zeam.md) for detailed documentation on the current POC scope and design.\n\n---\n\n## Package Structure\n\nThe `pkgs/` directory contains the modular components of the Zeam client:\n\n\n| Package                         | Description                              |\n| ------------------------------- | ---------------------------------------- |\n| `pkgs/state-transition`         | Core state transition logic (Zig)        |\n| `pkgs/state-transition-runtime` | RISC-V binary executed inside ZK-VMs     |\n| `pkgs/state-proving-manager`    | Orchestrates ZK proving and verification |\n| `pkgs/node`                     | Main node lifecycle and coordination     |\n| `pkgs/network`                  | libp2p-based P2P networking              |\n| `pkgs/api`                      | HTTP API layer                           |\n| `pkgs/cli`                      | Command-line interface                   |\n| `pkgs/database`                 | Persistent storage (RocksDB)             |\n| `pkgs/types`                    | Shared Beam/Zeam data types              |\n| `pkgs/spectest`                 | Spec test framework                      |\n| `pkgs/metrics`                  | Prometheus-compatible metrics            |\n| `pkgs/xmss`                     | Hash-based signature scheme              |\n| `pkgs/key-manager`              | Key management utilities                 |\n| `pkgs/params`                   | Protocol parameters                      |\n| `pkgs/configs`                  | Node configuration                       |\n| `pkgs/utils`                    | Shared utilities                         |\n| `pkgs/tools`                    | Developer tooling                        |\n\n\n---\n\n## ZK Prover Support\n\nZeam supports multiple ZK-VMs for state transition proving:\n\n\n| Prover                                         | Status    | Notes                               |\n| ---------------------------------------------- | --------- | ----------------------------------- |\n| [risc0](https://github.com/risc0/risc0) v3.0.3 | Supported | Requires external toolchain         |\n| [OpenVM](https://github.com/openvm-org/openvm) | Supported | Self-contained, no toolchain needed |\n\n\n---\n\n## Libraries \u0026 Ecosystem\n\nZeam is developing and contributing to the Zig Ethereum ecosystem. These libraries are used in and alongside the client:\n\n\n| Library                                                                                                             | Description                                                |\n| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| [ssz.zig](https://github.com/blockblaz/ssz.zig)                                                                     | SSZ serialization with configurable hash function (SHA256) |\n| [zig-snappy](https://github.com/blockblaz/zig-snappy) / [snappyframesz](https://github.com/blockblaz/snappyframesz) | Snappy compression                                         |\n| [zig-libp2p-pocs](https://github.com/blockblaz/zig-libp2p-pocs)                                                     | Zig ↔ Rust libp2p interop                                  |\n| [hash-sigz](https://github.com/blockblaz/hash-sigz)                                                                 | Hash-based signature schemes                               |\n| [zeam-runtime](https://github.com/blockblaz/zeam-runtime)                                                           | ZK-VM runtime POC                                          |\n\n\nIf you are developing a library in the Zig ecosystem that could benefit Zeam, please reach out via [Telegram](https://t.me/zeamETH).\n\n---\n\n## Build Instructions\n\n### Prerequisites\n\n- **Zig** `0.16.0`\n- **Rust** `1.85+` (required for ZK-VM Rust bindings)\n- **risc0 toolchain** (only if using risc0 prover): `rzup install r0vm 3.0.3`\n  - Install guide: [https://dev.risczero.com/api/zkvm/install](https://dev.risczero.com/api/zkvm/install)\n- **OpenVM** is self-contained — no additional toolchain required\n\n### Building\n\nBuild all transition functions and the full client:\n\n```bash\nzig build -Doptimize=ReleaseFast\n```\n\nTo include the git version in the binary:\n\n```bash\nzig build -Doptimize=ReleaseFast -Dgit_version=\"$(git rev-parse --short HEAD)\"\n```\n\n### Running the Prover Demo\n\n```bash\nzig build -Doptimize=ReleaseFast install run -- prove\n```\n\n### Docker\n\nDocker 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](https://github.com/ziglang/zig/issues/21316) when building inside Docker.\n\n**Build a Docker image locally:**\n\n```bash\n# Build zeam natively first\nzig build -Doptimize=ReleaseFast -Dgit_version=\"$(git rev-parse --short HEAD)\"\n\n# Then create Docker image with pre-built binary\ndocker build -f Dockerfile.prebuilt -t zeam:local .\n```\n\n**Build with OCI labels for registry publishing:**\n\n```bash\ndocker build -f Dockerfile.prebuilt \\\n  --build-arg GIT_COMMIT=$(git rev-parse HEAD) \\\n  --build-arg GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD) \\\n  -t blockblaz/zeam:latest .\n```\n\n### Troubleshooting\n\n**Build fails with `EndOfStream` error**\n\nIf you encounter errors like:\n\n```\nerror: invalid HTTP response: EndOfStream\n```\n\nThis may be caused by proxy environment variables interfering with Zig's HTTP client (related to the [Zig HTTP connection pool bug](https://github.com/ziglang/zig/issues/21316) mentioned above).\n\nTry building without proxy settings:\n\n```bash\nenv -u https_proxy -u HTTPS_PROXY -u http_proxy -u HTTP_PROXY \\\n    -u all_proxy -u ALL_PROXY -u no_proxy -u NO_PROXY \\\n    zig build -Doptimize=ReleaseFast\n```\n\n---\n\n## Running a Local Devnet\n\nTo run a local devnet with multiple nodes for testing and development, see the [Local Devnet Setup Guide](./pkgs/cli/test/fixtures/README.md), which covers a 2-node setup with finalization.\n\nAlternatively, use the [lean-quickstart](https://github.com/blockblaz/lean-quickstart) submodule:\n\n```bash\ngit submodule update --init lean-quickstart\n```\n\nThis provides a handy CLI tool to spin up two nodes for local interop.\n\n### Checkpoint Sync\n\nZeam 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](./pkgs/cli/test/fixtures/README.md#checkpoint-sync) for full documentation.\n\n---\n\n## Testing\n\n\n| Scenario                          | Guide                                                        |\n| --------------------------------- | ------------------------------------------------------------ |\n| Test blocks by root (parent sync) | [parent-sync.md](./resources/parent-sync.md)                 |\n| Test checkpoint sync              | [checkpoint-sync.md](./resources/checkpoint-sync.md)         |\n| Spec test framework               | [spec-test-framework.md](./resources/spec-test-framework.md) |\n\n\n---\n\n## Community \u0026 Contributions\n\nJoin the conversation around Beam Protocol and Zeam client:\n\n- [Telegram community](https://t.me/zeamETH)\n- [X / Twitter (@zeamETH)](https://x.com/zeamETH)\n- [Zeam \u0026 Beam Wiki](https://github.com/blockblaz/zeam/wiki)\n- [Community calls archive](https://github.com/blockblaz/zeam-community/issues?q=is%3Aissue+state%3Aclosed)\n\nZeam welcomes open-source contributions that meaningfully advance the client. Watch for announcements in the community or reach out directly via [Telegram](https://t.me/zeamETH).\n\n---\n\n## Reporting Issues\n\nOpen a [GitHub issue](https://github.com/blockblaz/zeam/issues/new) or reach out via the [Telegram community group](https://t.me/zeamETH).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockblaz%2Fzeam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockblaz%2Fzeam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockblaz%2Fzeam/lists"}