{"id":31776952,"url":"https://github.com/qdrvm/qlean-mini","last_synced_at":"2026-07-06T00:32:05.728Z","repository":{"id":314215645,"uuid":"1045516522","full_name":"qdrvm/qlean-mini","owner":"qdrvm","description":"Lean Ethereum PQ devnet client implementation in C++","archived":false,"fork":false,"pushed_at":"2026-06-30T07:07:38.000Z","size":127799,"stargazers_count":3,"open_issues_count":6,"forks_count":4,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-30T09:09:50.668Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qdrvm.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":null,"dco":null,"cla":null}},"created_at":"2025-08-27T09:48:17.000Z","updated_at":"2026-05-25T08:37:50.000Z","dependencies_parsed_at":"2025-11-29T16:02:55.869Z","dependency_job_id":null,"html_url":"https://github.com/qdrvm/qlean-mini","commit_stats":null,"previous_names":["qdrvm/qlean-mini"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/qdrvm/qlean-mini","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fqlean-mini","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fqlean-mini/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fqlean-mini/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fqlean-mini/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qdrvm","download_url":"https://codeload.github.com/qdrvm/qlean-mini/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fqlean-mini/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35174071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-10-10T06:00:06.764Z","updated_at":"2026-07-06T00:32:05.713Z","avatar_url":"https://github.com/qdrvm.png","language":"C++","funding_links":[],"categories":["3. Lean Consensus"],"sub_categories":["Implementations"],"readme":"# qlean-mini\n\nLean Ethereum consensus client for devnets, implemented in modern C++.\n\nqlean-mini follows the Lean Ethereum devnet specification:\n- Spec: https://github.com/leanEthereum/leanSpec/\n\nThis repository builds a small, modular node binary called `qlean` and a set of loadable modules. It uses CMake, Ninja, and vcpkg (manifest mode) for dependency management.\n\n\n## Quick start\n\n### 0) Clone the repository and set system dependencies\n\n```bash\ngit clone https://github.com/qdrvm/qlean-mini.git\ncd qlean-mini\n```\n\nPrerequisites:\n- CMake ≥ 3.25\n- Ninja\n- A C++23-capable compiler (AppleClang/Clang/GCC)\n- Python 3 (required by the CMake build)\n- vcpkg (manifest mode)\n\nNote: Dependencies are also listed in the `.ci/.env` file for both macOS and Linux. To install on Debian Linux:\n\n```bash\nsource .ci/.env\nsudo apt update \u0026\u0026 sudo apt install -y $(echo $LINUX_PACKAGES)\n```\n\nMake sure gcc-$GCC_VERSION is default compiler (where GCC_VERSION is defined in .ci/.env):\n\n```bash\nsudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-$GCC_VERSION 100\nsudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-$GCC_VERSION 100\n```\n\nFor macOS:\n\n```bash\nsource .ci/.env\nbrew install $(echo $MACOS_PACKAGES)\n```\n\n### 1) Install and bootstrap vcpkg\n\n```bash\n# Clone vcpkg somewhere on your machine (e.g. in your home directory)\ngit clone https://github.com/microsoft/vcpkg.git \"$HOME/vcpkg\"\n\n# Bootstrap vcpkg\n\"$HOME/vcpkg\"/bootstrap-vcpkg.sh\n\n# Export VCPKG_ROOT for the current shell session (and add to ~/.zshrc if use zsh for convenience)\nexport VCPKG_ROOT=\"$HOME/vcpkg\"\n```\n\nNotes:\n- This project uses vcpkg in manifest mode with custom overlay ports from `vcpkg-overlay/` and the registry settings in `vcpkg-configuration.json`.\n- CMake presets expect `CMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake`.\n\n### 2) Configure and build\n\nUse the provided CMake preset (generator: Ninja):\n\n```bash\n# From the repository root\ncmake --preset default\ncmake --build build -j\n```\n\nYou can also build the project's Docker images with **three-stage build**:\n\n```bash\n# First time (full build)\nmake docker_build_all          # ~25 min\n\n# Daily development (fast rebuild)  \nmake docker_build              # ~3-5 min ⚡\n```\n\n**Three stages:**\n- `qlean-mini-dependencies:latest` - vcpkg libs (**~6-9 GB**, rebuild rarely) \n  - **Safe optimization:** excludes only temporary build files (~10-15 GB saved)\n  - Removed during build: `buildtrees/`, `downloads/`, `packages/` (freed before copying)\n  - Kept: **complete** `vcpkg_installed/` (debug + release, .a + .so, all configs)\n  - **Zero risk:** 100% safe, all dependencies intact, CMake configs work perfectly\n- `qlean-mini-builder:latest` - project code (~8-12 GB, rebuild often)\n- `qlean-mini:latest` - runtime image (~240 MB, production)\n\n**When to rebuild dependencies:**\n- `vcpkg.json` or `vcpkg-configuration.json` changes (new libraries)\n- System dependencies update (`.ci/.env`: cmake, gcc, rust versions)\n- Typically: once per month or when adding new dependencies\n- **Tip:** Push dependencies to registry after rebuild for team reuse\n- **Note:** Dependencies image keeps all files needed for compilation (no rebuild)\n\n**Main commands:**\n```bash\nmake docker_build_all          # Full build (all 3 stages)\nmake docker_build              # Fast rebuild (code only)\nmake docker_build_ci           # CI/CD: pull deps + build (~4 min)\n```\n\n**Platform selection:**\n```bash\n# ARM64 (default)\nmake docker_build_all\n\n# AMD64 / x86_64\nmake docker_build_all DOCKER_PLATFORM=linux/amd64\n\n# Multi-arch: CI/CD on native runners\n# Job 1 (ARM64 runner):\nDOCKER_PLATFORM=linux/arm64 make docker_build_all\nmake docker_push_platform              # Push with -arm64 tag\n\n# Job 2 (AMD64 runner):\nDOCKER_PLATFORM=linux/amd64 make docker_build_all\nmake docker_push_platform              # Push with -amd64 tag\n\n# Job 3 (any machine):\nmake docker_manifest_create            # Create multi-arch manifest for runtime image ONLY\n\n# Run on specific platform\nmake docker_run DOCKER_PLATFORM=linux/amd64 ARGS='--version'\n```\n\n**Push/Pull:**\n```bash\nmake docker_push_dependencies  # Push dependencies to registry (once)\nmake docker_push               # Push all images (commit tag only)\nmake docker_pull_dependencies  # Pull dependencies from registry\n\n# Push with custom tag\nDOCKER_PUSH_TAG=true DOCKER_IMAGE_TAG=v1.0.0 make docker_push  # commit + v1.0.0\n\n# Push with latest tag\nDOCKER_PUSH_LATEST=true make docker_push  # commit + latest\n\n# Push all 3 tags (commit + custom + latest)\nDOCKER_PUSH_TAG=true DOCKER_PUSH_LATEST=true DOCKER_IMAGE_TAG=v1.0.0 make docker_push\n```\n\n**Image tagging:**\n\nDependencies (platform-specific, one per architecture):\n- Tags: `qlean-mini-dependencies:latest-arm64`, `qlean-mini-dependencies:latest-amd64`\n- Configurable via `DOCKER_DEPS_TAG` (default: `latest`)\n- Examples: `v2-arm64`, `staging-amd64`\n- **Note:** Dependencies are NOT multi-arch (each platform uses its own image)\n- Changes only when `vcpkg.json` or system dependencies change\n\nBuilder \u0026 Runtime (per commit):\n- Each build creates 2 local tags: `qlean-mini:608f5cc` (commit) + `qlean-mini:localBuild` (default)\n- Push behavior:\n  - **Commit tag** (`608f5cc`): always pushed to registry\n  - **Custom tag** (`DOCKER_IMAGE_TAG`): pushed if `DOCKER_PUSH_TAG=true` (default: `localBuild`, not pushed)\n  - **Latest tag**: pushed if `DOCKER_PUSH_LATEST=true`\n- Push up to 3 tags: commit + custom (v1.0.0) + latest\n\n**Utility:**\n```bash\nmake docker_run                # Run node\nmake docker_run ARGS='--version'\nmake docker_verify             # Test runtime image\nmake docker_clean              # Clean builder + runtime (keep deps)\nmake docker_clean_all          # Clean everything (including deps)\n```\n\n**For CI/CD:**\n```bash\n# One command - pulls dependencies from registry, builds code\nexport DOCKER_REGISTRY=your-registry\nmake docker_build_ci           # ~4 min\nmake docker_verify\nmake docker_push               # Push commit tag only\n\n# Production release with version and latest\nDOCKER_PUSH_TAG=true DOCKER_PUSH_LATEST=true DOCKER_IMAGE_TAG=v1.0.0 make docker_push\n# Pushes: qlean-mini:608f5cc + qlean-mini:v1.0.0 + qlean-mini:latest\n\n# Only latest\nDOCKER_PUSH_LATEST=true make docker_push  # qlean-mini:608f5cc + qlean-mini:latest\n\n# Staging environment\nDOCKER_PUSH_TAG=true DOCKER_IMAGE_TAG=staging make docker_push  # commit + staging\n```\n\nSee [DOCKER_BUILD.md](DOCKER_BUILD.md) for details. See the `Makefile` for all Docker targets.\n\n### Automated CI/CD (GitHub Actions)\n\nThis project includes GitHub Actions workflow for automated multi-arch Docker builds:\n\n- ✅ **Auto-build on push** to `ci/docker` branch (or tags)\n- ✅ **Manual builds** via GitHub UI with flexible parameters\n- ✅ **Native multi-arch** (ARM64 + AMD64) on free GitHub-hosted runners\n- ✅ **Fast builds** (~20-30 min per architecture, native compilation)\n- ✅ **Smart caching** (rebuilds dependencies only when `vcpkg.json` changes)\n- ✅ **Flexible tagging** (commit hash + custom tag + latest)\n- ✅ **Zero setup** - works out of the box, 100% free for public repos\n\n**Quick actions:**\n\n```bash\n# Push to ci/docker branch → auto-build and push\ngit push origin ci/docker\n\n# Create tag → auto-build and push with tag\ngit tag v1.0.0 \u0026\u0026 git push origin v1.0.0\n```\n\n**Manual build via GitHub UI:**\n\nGo to: **Actions → Docker Build → Run workflow**\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 📦 Dependencies Image (rebuild rarely)                  │\n│    ☐ Build dependencies image (vcpkg libs)             │\n│    📝 Dependencies tag: latest                          │\n├─────────────────────────────────────────────────────────┤\n│ 🏗️  Main Build Configuration                            │\n│    ☑ Build linux/amd64                                  │\n│    ☑ Build linux/arm64                                  │\n├─────────────────────────────────────────────────────────┤\n│ 🚀 Push \u0026 Tagging                                       │\n│    ☐ Push images to Docker Hub                         │\n│    📝 Custom tag: (e.g., v1.0.0, staging)               │\n│    ☐ Also push 'latest' tag                            │\n└─────────────────────────────────────────────────────────┘\n```\n\n**Common scenarios:**\n- **Test build:** Just select architectures, leave rest unchecked\n- **Production:** Check `build_deps`, `push`, fill `custom_tag`, check `push_latest`\n- **Hotfix:** Select one arch, check `push`, fill `custom_tag`\n- **Dependencies only:** Check `build_deps` and `push`\n\nSee [.github/workflows/README.md](.github/workflows/README.md) for CI/CD documentation.\n\nThis will:\n- Configure the project into `./build/`\n- Build the main node executable at `./build/out/qlean`\n\n### 3) Ensure build was successful\nPrint help:\n\n```bash\n./build/out/qlean --help\n```\n\n## Run the node\n\nFor step-by-step instructions to run a local single-node devnet, see `example/0-single/README.md`. It includes the exact CLI command and an explanation of all flags.\n\n\n## Generate a node key\n\nThe binary includes a helper subcommand to generate a node key and corresponding PeerId:\n\n```bash\n./build/out/qlean key generate-node-key\n```\n\nThis prints two lines:\n1) The private key (hex)\n2) The PeerId (base58)\n\n\n## Tests\n\nIf `TESTING` is enabled (default ON in top-level CMakeLists), tests are built and can be run with CTest:\n\n```bash\n# After building\nctest --test-dir build --output-on-failure\n```\n\nIndividual test binaries are placed under `build/test_bin/`.\n\n## License\n\nSPDX-License-Identifier: Apache-2.0 — Copyright Quadrivium LLC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrvm%2Fqlean-mini","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqdrvm%2Fqlean-mini","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrvm%2Fqlean-mini/lists"}