build(l1): modernize Dockerfile with BuildKit + shrink context

[edg-l]

Summary

Bring the Dockerfile up to current best practices and stop leaking gigabytes into the build context.

Build context size (vs main)

Path	Size on main	Status after this PR
.git/	1.1 GB	excluded; vergen-git2 reads branch/SHA from VERGEN_GIT_BRANCH / VERGEN_GIT_SHA env (passed via build ARG)
tooling/ef_tests/blockchain/vectors_zkevm/	2.3 GB	excluded — was leaking (sibling vectors/ was excluded, this one was missed)
tooling/* (non-repl/monitor)	~50 MB	not copied; only tooling/repl and tooling/monitor are referenced as path deps by the root workspace's Cargo.toml. The rest of tooling/ is a separate cargo workspace never used by the ethrex build.
fixtures/blockchain/	340 MB	excluded; pure test data, never read at build time
fixtures/{blobs,cache,rsp,hive}/	~10 MB	excluded; not read at build time
Total transferred	~2.81 GB	~9.5 MB (measured)

Image size

Tag	Size
ethrex:main (current)	180 MB
ethrex:test (this PR)	126 MB (~30% smaller)

Savings come from the slim builder base, removing the redundant runtime copy of cmd/ethrex/networks (those JSONs are include_str!-embedded in the binary), and --no-install-recommends + apt cache mounts not leaking into the layer.

Build speed

• # syntax=docker/dockerfile:1.10 + BuildKit cache mounts on ~/.cargo/registry, ~/.cargo/git, and target/ (survive across builds even when recipe.json changes).
• Apt cache mounts on /var/cache/apt and /var/lib/apt.
• cargo binstall cargo-chef (prebuilt binary) replaces cargo install source build, saves ~2 min cold.
• rust:1.91-slim-bookworm builder base (~700 MB smaller than rust:1.91).
• COPY --link throughout: independent layers can be copied in parallel and their cache survives base-image / earlier-step changes.

Reliability

• CARGO_NET_GIT_FETCH_WITH_CLI=true + git in the builder image. The slim base doesn't ship git, so libgit2 was used by default and could hang inside the container on cold git-dep fetches. Forcing the CLI sidesteps the hang and uses the user's normal git behavior.

Image / runtime

• Add OCI labels (title, description, source, licenses, revision, version).
• ARG TARGETARCH drives solc download (multi-platform-ready) instead of shell uname -m.
• Runtime still ubuntu:24.04 + libssl3 running as root, to keep snapsync compose named-volume mounts working.

Metadata wiring

GIT_SHA / GIT_BRANCH / VERSION now flow consistently through:

• Makefile (new TAG variable; default local, override with make build-image TAG=foo)
• .github/actions/build-docker/action.yml (from github.sha / github.head_ref || github.ref_name)
• .github/actions/snapsync-run/action.yml (from local git)
• tooling/sync/docker_monitor.py (from local git)

Result (verified locally):

$ docker inspect ethrex:test --format '{{json .Config.Labels}}' | jq
{
  "org.opencontainers.image.revision": "626c2f2533bdcdfb92641720914ab5d305356f3b",
  "org.opencontainers.image.version":  "v13.0.0-14-g626c2f253",
  ...
}

$ docker run --rm ethrex:test --version
ethrex/v13.0.0-perf/dockerfile-buildkit-626c2f25.../x86_64-unknown-linux-gnu/rustc-v1.91.1

Previously the image baked in whatever vergen-git2 read from .git; the metadata was correct but cost 1.1 GB of context per build.

Test plan

• make build-image TAG=test succeeds locally; build context transferred ~9.5 MB
• docker inspect ethrex:test shows real revision + version labels
• docker run --rm ethrex:test --version reports the correct branch + full SHA
• PR-main_l2 workflow (L1 + L2 image builds) green
• Daily snapsync compose still mounts /data as root (no perm regressions)
• First CI build after merge is slow (cache-from miss expected); subsequent builds use new cache

[github-actions]

⚠️ Known Issues — intentionally skipped tests

Source: docs/known_issues.md

Known Issues

Tests intentionally excluded from CI. Source of truth for the Known
Issues section the L1 workflow appends to each ef-tests job summary
and posts as a sticky PR comment.

EF Tests — Stateless coverage narrowed to EIP-8025 optional-proofs

make -C tooling/ef_tests/blockchain test calls test-stateless-zkevm
instead of test-stateless. The zkevm@v0.3.3 fixtures are filled against
bal@v5.6.1, out of sync with current bal spec; the broad target trips ~549
fixtures. Re-broaden once the zkevm bundle is regenerated.

Why and resolution path

PR #6527 broadened
test-stateless to extract the entire for_amsterdam/ tree from the
zkevm bundle and run all of it under --features stateless; combined with
this branch's bal-devnet-7 semantics that scope produces ~549
GasUsedMismatch / ReceiptsRootMismatch /
BlockAccessListHashMismatch failures.

test-stateless-zkevm filters cargo to the eip8025_optional_proofs
suite, which still validates the stateless harness without the bal-version
mismatch.

Re-broaden by switching test: back to test-stateless in
tooling/ef_tests/blockchain/Makefile once the zkevm bundle is regenerated
against the current bal spec.

[github-actions]

🤖 Claude Code Review

PR Review: build(l1): modernize Dockerfile with BuildKit + shrink context

Summary: This PR is a pure infrastructure improvement — no Rust logic changed. It shrinks the Docker build context from ~2.81 GB to ~9.5 MB, adds BuildKit cache mounts, wires OCI labels, and propagates git metadata through all build entry points (Makefile, two GH Actions, and the Python monitor script).

The overall approach is sound and the changes are well-reasoned. A few issues are worth addressing before merge.

---

Security

cargo-binstall downloaded from releases/latest with no checksum (Dockerfile, line ~22)

curl -fsSL https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-$(uname -m)-unknown-linux-musl.tgz \
  | tar -xz -C /usr/local/cargo/bin

Two problems here:

• releases/latest is a moving target. The binary can silently change between builds, breaking reproducibility and opening a supply-chain window.
• No checksum verification. A compromised GitHub release would drop arbitrary code into /usr/local/cargo/bin before cargo binstall cargo-chef runs.

Recommendation: pin to a specific cargo-binstall version and verify a SHA-256 digest:

ARG BINSTALL_VERSION=1.14.1
RUN curl -fsSL \
      https://github.com/cargo-bins/cargo-binstall/releases/download/v${BINSTALL_VERSION}/cargo-binstall-$(uname -m)-unknown-linux-musl.tgz \
    | tar -xz -C /usr/local/cargo/bin \
  && echo "<known-sha256>  /usr/local/cargo/bin/cargo-binstall" | sha256sum -c -

---

Correctness

TARGETARCH is empty in non-BuildKit docker build calls (Dockerfile, ~line 57)

RUN case "$TARGETARCH" in \
        arm64) SOLC_URL=... ;; \
        amd64) SOLC_URL=... ;; \
        *) echo "unsupported TARGETARCH=$TARGETARCH" >&2; exit 1 ;; \
    esac

TARGETARCH is a BuildKit-injected magic arg. For any docker build invocation without --platform on an older engine (pre-23) or without BuildKit enabled, it will be empty and the build fails immediately with unsupported TARGETARCH=.

Since # syntax=docker/dockerfile:1.10 mandates BuildKit, this is largely a non-issue on modern Docker. However, the old uname -m fallback was more robust. A simple guard would close the gap:

ARG TARGETARCH
RUN ARCH="${TARGETARCH:-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')}" && \
    case "$ARCH" in ...

VERGEN_GIT_SHA is never passed to the builder

The OCI label org.opencontainers.image.revision correctly receives GIT_SHA via ARG in the runtime stage. But vergen-git2 reads the commit SHA from .git/ at compile time, and .git/ is now excluded from the context. With VERGEN_IDEMPOTENT=1, vergen silently uses an empty/placeholder SHA rather than failing.

If the binary exposes its own version (e.g. ethrex --version or a /version endpoint backed by a vergen constant), the embedded SHA will be empty while the OCI label has the real one. Whether this matters depends on how vergen is configured in the crate, but it is worth auditing. Adding ARG GIT_SHA + ENV VERGEN_GIT_SHA=$GIT_SHA to the builder stage alongside the existing VERGEN_GIT_BRANCH would make them consistent.

test/ directory dropped from the build context

The old planner and builder stages both copied test/. The new ones omit it entirely. If any workspace member references a path in test/, cargo chef prepare will fail; if the path dep is only used by a test-only crate, it works fine. This is almost certainly intentional, but worth a one-line comment or PR-description mention so reviewers can verify.

---

Minor / Style

• COPY Cargo.* . → COPY --link Cargo.toml Cargo.lock ./: Strictly more correct — the glob would also match any future Cargo.something file. The explicit form is better.
• libc6 removed: Was listed explicitly in the old apt install; not present in the new one. libc6 ships in rust:1.91-slim-bookworm so this is fine, but worth a note.
• pkg-config added: Good catch — was implicitly provided by the full rust:1.91 image but missing from slim-bookworm.
• apt-get cache mounts in the runtime stage: Correct usage. The packages are still written to the layer; only the .deb download cache survives across builds. No correctness issue.
• GIT_BRANCH ARG scope: The ARG GIT_BRANCH=unknown and its ENV are declared in the builder stage only, which is the right scope.

---

What looks good

• Context reduction (2.81 GB → ~9.5 MB) is the right call and the .dockerignore additions are accurate.
• Selective tooling/repl + tooling/monitor COPY instead of the full tooling/ tree is well-justified by the workspace dependency graph.
• id=ethrex-target-${TARGETARCH} cache scoping correctly isolates per-architecture target directories.
• The combined build+copy RUN step to keep the target cache mount active is the correct BuildKit pattern.
• Removing COPY cmd/ethrex/networks because the files are include_str!-embedded is a nice cleanup.
• The _git helper in docker_monitor.py is clean and handles both CalledProcessError and missing git binary.
• Git metadata is now consistent across all four entry points (Makefile, two Actions, Python script).

---

Summary

The main actionable items are:

1. Pin cargo-binstall to a specific version and add a checksum (security).
2. Add a TARGETARCH fallback to uname -m (robustness, low priority given BuildKit requirement).
3. Audit vergen configuration to decide whether VERGEN_GIT_SHA should be passed to the builder stage (consistency).

---

Automated review by Claude (Anthropic) · sonnet · custom prompt

[github-actions]

🤖 Kimi Code Review

This PR optimizes Docker builds significantly, but has a few correctness and security issues to address.

Critical Issues

1. Missing VERGEN_GIT_SHA environment variable (Dockerfile)

• Location: Builder stage, lines 39-40
• Issue: The builder accepts GIT_SHA as a build arg but never exports it as VERGEN_GIT_SHA for the vergen crate. The binary will be built with unknown/empty commit hashes.
• Fix: Add to builder stage:

  ARG GIT_SHA=unknown
  ARG GIT_BRANCH=unknown
  ENV VERGEN_GIT_SHA=$GIT_SHA \
      VERGEN_GIT_BRANCH=$GIT_BRANCH \
      VERGEN_IDEMPOTENT=1

2. Unquoted shell variables (Dockerfile)

• Location: Lines 48 and 75
• Issue: $PROFILE and $BUILD_FLAGS are unquoted. If BUILD_FLAGS contains multiple flags (e.g., "--features feature1 feature2"), word splitting will occur.
• Fix: Use "$PROFILE" and $BUILD_FLAGS (quoted individually if needed, or ensure proper array handling).

Security Concerns

3. No checksum verification for downloaded binaries

• Location: Lines 27-30 (cargo-binstall) and Lines 52-57 (solc)
• Issue: Downloading executables from GitHub without checksum verification exposes the build to supply chain attacks if the release artifacts are compromised.
• Recommendation: Pin to specific versions and verify SHA256 checksums, or use the repository's provided checksum files.

Correctness & Robustness

4. Incomplete tooling directory copy

• Location: Lines 62-67
• Issue: Copying only tooling/repl and tooling/monitor assumes no other workspace members depend on other tooling/ crates. If the workspace Cargo.toml includes other tooling crates or if there are path dependencies, the build will fail.
• Verification: Ensure that tooling/ only contains leaf binaries and not shared libraries required by crates/ or cmd/.

5. Profile path assumption

• Location: Line 77
• Issue: cp /ethrex/target/${PROFILE}/ethrex assumes the output directory matches the profile name exactly. For built-in profiles, dev maps to target/debug/, not target/dev/.
• Note: This is a pre-existing issue, but worth noting if users expect to override PROFILE=dev.

Minor Improvements

6. Python error handling

• Location: tooling/sync/docker_monitor.py, lines 394-399
• Issue: _git catches FileNotFoundError but subprocess.run can also raise OSError (e.g., permissions) or ValueError.
• Fix: Consider catching Exception or (subprocess.SubprocessError, OSError).

7. Docker buildx cache scope

• Location: Line 45
• Observation: Using id=ethrex-target-${TARGETARCH} for the target cache is good for multi-arch builds, but ensure that TARGETARCH is always set (it is with BuildKit).

Verdict

The optimizations are solid—particularly the .dockerignore changes saving 1.4GB and the cache mounts. However, Item 1 (missing VERGEN_GIT_SHA) is a functional regression that must be fixed before merge, as it breaks version metadata embedding.

---

Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt

[github-actions]

🤖 Codex Code Review

1. High: the new Docker build trims fixtures/ too aggressively and likely hard-breaks compilation. Dockerfile now only copies fixtures/genesis, but ethrex-config still does include_str!("../../../fixtures/keys/private_keys_l1.txt") at compile time in crates/common/config/networks.rs. cargo build will try to resolve that file while compiling the crate, so the builder needs fixtures/keys/private_keys_l1.txt (or the whole fixtures/keys dir) copied in as well.

2. High: Dockerfile downloads cargo-binstall from releases/latest and immediately executes it as root. That is a supply-chain and reproducibility regression for a blockchain client image: the build is now mutable over time, and there is no checksum/signature pinning. Pin an exact release and verify its digest, or keep using a deterministic install path for cargo-chef.

3. Medium: GIT_SHA is injected by CI/local tooling, but the builder stage never exposes it to vergen, so the binary’s commit metadata regresses once .git/ is excluded from the context. The arg is passed in action.yml and docker_monitor.py, but the builder only sets VERGEN_GIT_BRANCH in Dockerfile. The binary still reads VERGEN_GIT_SHA in cmd/ethrex/utils.rs and metrics initialization in cmd/ethrex/initializers.rs. Add ARG GIT_SHA plus ENV VERGEN_GIT_SHA=$GIT_SHA in the builder stage.

4. Low: the new metadata injection is undermined by the stamp rule in Makefile. make build-image will skip rebuilding on a pure commit/version change, so GIT_SHA/VERSION can be stale even when HEAD changed. If the stamp stays, it should depend on Cargo.lock, relevant fixture inputs, and git refs, or the image build should avoid the stamp shortcut.

No EVM / consensus / trie / RLP logic changed in this diff, so I did not find Ethereum-protocol-specific issues here. I did not run a full build or tests.

---

Automated review by OpenAI Codex · gpt-5.4 · custom prompt

[greptile-apps]

Greptile Summary

This PR modernises the L1 Dockerfile with BuildKit syntax, cache mounts, and a slimmed build context (from ~2.81 GB to ~9.5 MB), and wires git metadata (GIT_SHA, GIT_BRANCH, VERSION) consistently through the Makefile, GitHub Actions, and the Python monitor script.

• Context shrinkage — .dockerignore now excludes .git/, fixtures/blockchain/ (340 MB), and the previously missed tooling/ef_tests/blockchain/vectors_zkevm/ (2.3 GB), eliminating the dominant sources of build-context bloat.
• Build speed — cargo-binstall replaces a source-compiled cargo install cargo-chef, BuildKit cache mounts persist ~/.cargo and target/ across builds, and rust:1.91-slim-bookworm replaces the full rust:1.91 image (~700 MB smaller).
• Metadata propagation — GIT_SHA/GIT_BRANCH/VERSION now flow through every build path (CI action, Makefile, snapsync action, Python monitor), but VERGEN_GIT_SHA is not forwarded as an env var to the builder stage, so the SHA that vergen-git2 embeds in the compiled binary will be an idempotent placeholder rather than the actual commit hash.

Confidence Score: 3/5

The build-context and caching changes are correct, but the binary's embedded git SHA will be wrong on every build until VERGEN_GIT_SHA is wired up in the builder stage — a gap directly contradicting the PR's stated goal of consistent metadata.

The VERGEN_GIT_SHA env var is never exported in the builder stage, so every image produced by this PR will embed a vergen placeholder SHA in the compiled binary while the OCI label carries the correct hash. This inconsistency affects observability and version tracing on every deployment. Additionally, cargo-binstall is pulled from an unpinned releases/latest URL, making builds non-reproducible and silently sensitive to upstream releases.

The builder stage of Dockerfile (lines 48-93) needs the most attention — specifically the missing VERGEN_GIT_SHA env var and the unpinned cargo-binstall download. Makefile has a minor stamp-file dependency gap for tooling/repl and tooling/monitor.

Important Files Changed

Filename	Overview
Dockerfile	Multi-stage BuildKit Dockerfile with cache mounts and slimmed context; VERGEN_GIT_SHA not forwarded to the builder stage so the SHA embedded in the binary by vergen will be incorrect, and cargo-binstall is fetched from an unpinned releases/latest URL.
.dockerignore	Adds exclusions for .git/, heavy fixture directories, and the previously missing vectors_zkevm/ (2.3 GB); cleanly addresses the build-context bloat described in the PR.
.github/actions/build-docker/action.yml	Injects GIT_SHA, GIT_BRANCH, and VERSION build args from GitHub context; logic is straightforward and correct.
.github/actions/snapsync-run/action.yml	Computes git metadata from local checkout and passes them as build args; consistent with the Makefile approach.
Makefile	Adds TAG/IMAGE variables and git-metadata args to the build rule; stamp-file dependencies don't include the newly-copied tooling/repl and tooling/monitor sources.
tooling/sync/docker_monitor.py	Adds a _git helper to derive SHA/branch/version from the local repo before calling docker build; approach mirrors the shell scripts in the GitHub Actions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Build Context\n~9.5 MB after .dockerignore] --> B

    subgraph B[rust:1.91-slim-bookworm — chef base]
        B1[apt-get: build-essential, libclang-dev,\nlibssl-dev, pkg-config, curl]
        B2[curl releases/latest → cargo-binstall\ncargo binstall cargo-chef]
        B1 --> B2
    end

    B --> C & D

    subgraph C[planner stage]
        C1[COPY benches crates metrics cmd\ntest tooling/repl tooling/monitor\nCargo.toml Cargo.lock .cargo]
        C2[cargo chef prepare → recipe.json]
        C1 --> C2
    end

    subgraph D[builder stage]
        D1[ARGs: PROFILE BUILD_FLAGS TARGETARCH\nGIT_BRANCH → ENV VERGEN_GIT_BRANCH\nVERGEN_IDEMPOTENT=1]
        D2[COPY recipe.json from planner]
        D3[cargo chef cook --profile PROFILE\ncache: cargo registry + git + target/]
        D4[case TARGETARCH\narm64 → solc-linux-arm\namd64 → solc-linux]
        D5[COPY source files + fixtures/genesis]
        D6[cargo build --profile PROFILE\ncp target/PROFILE/ethrex → /ethrex/bin/]
        D1 --> D2 --> D3 --> D4 --> D5 --> D6
    end

    C2 -->|recipe.json| D2

    subgraph E[ubuntu:24.04 — runtime]
        E1[ARGs: GIT_SHA VERSION\nLABEL OCI image metadata]
        E2[apt-get: libssl3 ca-certificates]
        E3[COPY ethrex binary from builder]
        E4[ENTRYPOINT ethrex\nEXPOSE 8545 8551 30303 9090 1729 3900]
        E1 --> E2 --> E3 --> E4
    end

    D6 -->|/ethrex/bin/ethrex| E3

    style D1 fill:#ffe0e0,stroke:#cc0000
    style B2 fill:#fff3cd,stroke:#856404

Loading

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
Dockerfile:54-56
`VERGEN_GIT_SHA` is never set as an env var in the builder stage, so with `.git` excluded from the build context, vergen-git2 falls back to its idempotent placeholder for the SHA field. Only the branch is correctly forwarded. The OCI label gets the right SHA, but the SHA embedded in the binary by vergen (and shown by `--version`) will be a placeholder string rather than the actual commit hash.

```suggestion
ARG GIT_BRANCH=unknown
ARG GIT_SHA=unknown
ENV VERGEN_GIT_BRANCH=$GIT_BRANCH \
    VERGEN_GIT_SHA=$GIT_SHA \
    VERGEN_IDEMPOTENT=1
```

### Issue 2 of 3
Dockerfile:20-22
The `cargo-binstall` binary is fetched from `releases/latest`, so every fresh CI build will silently upgrade to whatever the newest release is. This breaks build reproducibility and means a newly published (or compromised) version is picked up without any review. Pin to an explicit release tag so that the version can be bumped deliberately via a reviewed commit.

```suggestion
    curl -fsSL https://github.com/cargo-bins/cargo-binstall/releases/download/v1.14.1/cargo-binstall-$(uname -m)-unknown-linux-musl.tgz \
      | tar -xz -C /usr/local/cargo/bin \
    && cargo binstall --no-confirm cargo-chef
```

### Issue 3 of 3
Makefile:56
The stamp-file rule now triggers a rebuild only when `crates/` or `cmd/` Rust files change, but the new Dockerfile also copies `tooling/repl` and `tooling/monitor`. Changes to those directories won't invalidate the stamp, so `make build-image` will silently skip a needed rebuild.

```suggestion
$(STAMP_FILE): $(shell find crates cmd tooling/repl tooling/monitor -type f -name '*.rs') Cargo.toml Dockerfile
```

_{Reviews (1): Last reviewed commit: "build: modernize Dockerfile with BuildKi..." | Re-trigger Greptile}

[edg-l]

Addressed bot reviews in 3d3e9e7b4:

• VERGEN_GIT_SHA now passed to builder (was already set in 626c2f253)
• fixtures/keys copied so include_str! for private_keys_l1.txt resolves (was already set in b84c33459)
• cargo-binstall pinned to v1.19.1 via ARG (no more releases/latest)
• Builder stage now also COPY test ./test to match planner
• Makefile stamp file tracks tooling/repl and tooling/monitor

Skipped: TARGETARCH fallback to uname -m — # syntax=docker/dockerfile:1.10 mandates BuildKit, where TARGETARCH is always set.