feat: state-actor + eest payload generation

.hack/orbstack.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+#
+# Provision an OrbStack Linux machine to run benchmarkoor with a copy-on-write
+# datadir method (overlayfs). macOS has no overlayfs/zfs/schelk, so the large
+# stateful prestates (e.g. config.state-actor-eest.full.amsterdam.stateful.yaml,
+# ~77 GB) can't use anything but `copy` on the host — which is infeasible at that
+# size. An OrbStack Linux machine has a real kernel (overlayfs works) and we run
+# a DEDICATED dockerd inside it so benchmarkoor, dockerd, and the overlay mounts
+# all share one filesystem namespace (the merged dir must be bind-mountable into
+# the client containers — the host's shared Docker engine can't see VM-local
+# overlay mounts).
+#
+# Prereqs: OrbStack installed (https://orbstack.dev). The repo is auto-shared
+# into the machine at the same path, so no copying is needed.
+#
+# Usage:
+#   .hack/orbstack.sh [machine-name]          # default: bench
+#
+# After it finishes the binary is at <repo>/bin/benchmarkoor (also symlinked onto
+# PATH, so a bare `benchmarkoor` works). Run it INSIDE the machine as root
+# (overlayfs mount needs CAP_SYS_ADMIN), e.g.:
+#   orb -m bench sudo benchmarkoor build \
+#     --config $(pwd)/examples/configuration/config.state-actor-eest.full.amsterdam.stateful.yaml --force
+#   orb -m bench sudo benchmarkoor run \
+#     --config $(pwd)/examples/configuration/config.state-actor-eest.full.amsterdam.stateful.yaml --limit-instance-id=geth
+set -euo pipefail
+
+MACHINE="${1:-bench}"
+DISTRO="${ORBSTACK_DISTRO:-ubuntu}"
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if ! command -v orb >/dev/null 2>&1; then
+  echo "error: 'orb' not found — install OrbStack first (https://orbstack.dev)" >&2
+  exit 1
+fi
+
+echo "==> Repo root: ${REPO_ROOT}"
+echo "==> OrbStack machine: ${MACHINE} (${DISTRO})"
+
+# 1. Create the machine if it doesn't already exist (idempotent).
+if orb list 2>/dev/null | awk '{print $1}' | grep -qx "${MACHINE}"; then
+  echo "==> Machine '${MACHINE}' already exists, reusing it."
+else
+  echo "==> Creating machine '${MACHINE}'..."
+  orb create "${DISTRO}" "${MACHINE}"
+fi
+
+# 2. Provision inside the machine: dedicated dockerd + Go toolchain, then build
+#    benchmarkoor natively. Everything below runs as root in the machine.
+orb -m "${MACHINE}" sudo bash -s -- "${REPO_ROOT}" <<'PROVISION'
+set -euo pipefail
+REPO_ROOT="$1"
+
+echo "==> apt: docker.io + golang-go + make + git"
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+# make + git let you run the repo's Makefile targets (e.g. `make build-core`,
+# `make test-core`) inside the machine; git also stamps the version/commit.
+apt-get install -y -qq docker.io golang-go make git
+
+echo "==> Starting the machine's own dockerd"
+systemctl enable --now docker
+systemctl is-active --quiet docker || { echo "dockerd failed to start" >&2; exit 1; }
+
+# A dedicated, VM-local docker daemon is the whole point — confirm it.
+docker version --format '   dockerd {{.Server.Version}}' >/dev/null
+
+echo "==> Go: $(go version)"
+case "$(go version)" in
+  *go1.2[3-9]*|*go1.[3-9][0-9]*|*go[2-9].*) : ;;
+  *) echo "warning: Go < 1.23 detected; benchmarkoor needs >= 1.23. Install a newer Go." >&2 ;;
+esac
+
+echo "==> Building benchmarkoor (make build-core)"
+cd "${REPO_ROOT}"
+GOCACHE=/root/.cache/go-build GOPATH=/root/go make build-core
+# The binary lands in ${REPO_ROOT}/bin/benchmarkoor. Symlink it onto PATH so a
+# bare `benchmarkoor` works from anywhere and a later `make build-core` (rebuild
+# after a code change) is picked up automatically — no stale copy.
+ln -sf "${REPO_ROOT}/bin/benchmarkoor" /usr/local/bin/benchmarkoor
+benchmarkoor --help >/dev/null \
+  && echo "==> benchmarkoor built at ${REPO_ROOT}/bin/benchmarkoor (symlinked onto PATH at /usr/local/bin/benchmarkoor)"
+
+echo "==> Verifying overlayfs works in this machine"
+d="$(mktemp -d)"; mkdir -p "$d"/{low,up,work,merged}; echo ok > "$d/low/f"
+mount -t overlay overlay -o "lowerdir=$d/low,upperdir=$d/up,workdir=$d/work" "$d/merged"
+docker run --rm -v "$d/merged:/m" alpine cat /m/f >/dev/null && echo "==> overlayfs + dockerd bind-mount: OK"
+umount "$d/merged"; rm -rf "$d"
+PROVISION
+
+cat <<EOF
+
+==> Done. The '${MACHINE}' machine is ready (dedicated dockerd + overlayfs + benchmarkoor).
+
+benchmarkoor is built at ${REPO_ROOT}/bin/benchmarkoor (symlinked onto PATH).
+Run it inside the machine as root (the repo is shared at ${REPO_ROOT}):
+
+  orb -m ${MACHINE} sudo benchmarkoor build \\
+    --config ${REPO_ROOT}/examples/configuration/config.state-actor-eest.full.amsterdam.stateful.yaml --force
+
+  orb -m ${MACHINE} sudo benchmarkoor run \\
+    --config ${REPO_ROOT}/examples/configuration/config.state-actor-eest.full.amsterdam.stateful.yaml --limit-instance-id=geth
+
+Tear down with:  orb delete ${MACHINE}
+EOF

Dockerfile.eest-filler

@@ -0,0 +1,60 @@
+# Dockerfile.eest-filler
+#
+# Builds the toolchain image referenced by `builder.eest_payloads.fill_image`:
+# it carries only `uv` + python + the build toolchain — NOT the execution-specs
+# repo. benchmarkoor clones execution-specs at build time (at the configured
+# `eest_ref`, caching it on disk) and mounts the checkout into this container at
+# /eest, then runs `uv run fill-stateful`. uv builds the venv into the mounted
+# checkout on first use (cached across runs). This keeps the EEST version in
+# config and changeable without rebuilding the image.
+#
+# fill-stateful drives a *live* EL client over testing_buildBlockV1, so — unlike
+# the t8n-based `fill` — it needs NO evmone/eels transition-tool binary.
+#
+# Build:
+#   docker build -f Dockerfile.eest-filler -t ghcr.io/your-org/eest-fill-stateful:latest .
+#   # (podman build works identically)
+#
+# Then point your config at it:
+#   builder:
+#     eest_payloads:
+#       fill_image: ghcr.io/your-org/eest-fill-stateful:latest
+#       eest_ref: forks/amsterdam   # optional; defaults to forks/amsterdam
+
+ARG PYTHON_VERSION=3.12
+
+FROM python:${PYTHON_VERSION}-slim-bookworm
+
+# uv: copy the static binary from the official image (recommended pattern).
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+# Runtime deps: git (fill-stateful reads its commit hash from the checkout, and
+# uv resolves git deps); ca-certificates for HTTPS to PyPI; build-essential plus
+# clang/libclang-dev/pkg-config for EEST dependencies without a prebuilt wheel.
+# In particular `ethereum-execution[optimized]` pulls in rust-pyspec-glue, whose
+# native mdbx-sys crate has no arm64 wheel and is compiled from source: its build
+# script runs bindgen, which dlopens libclang. Cargo itself is bootstrapped by uv
+# at build time, so only the clang toolchain has to be present in the image.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        git \
+        ca-certificates \
+        build-essential \
+        clang \
+        libclang-dev \
+        pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+# Point bindgen/clang-sys straight at the bookworm-default LLVM 14 libclang so it
+# never falls back to its "couldn't find any valid shared libraries" failure. The
+# base image is pinned to bookworm (above), so the LLVM major version is stable.
+ENV LIBCLANG_PATH=/usr/lib/llvm-14/lib
+
+ENV UV_NO_PROGRESS=1
+
+# The execution-specs checkout is bind-mounted here by benchmarkoor at run time;
+# the relative test paths (e.g. tests/benchmark/stateful) resolve against it.
+WORKDIR /eest
+
+# Standalone default; benchmarkoor overrides this with the full fill-stateful argv.
+CMD ["uv", "--version"]

_typos.toml

@@ -4,3 +4,11 @@ extend-exclude = ["go.mod"]
 [default.extend-words]
 PANC = "PANC"
 ERRO = "ERRO"
+BULD = "BULD"
+
+# EIP-7928 block access lists. typos splits the identifier "BALs" into "BA"+"Ls"
+# and flags "BA" as a typo of "BY"/"BE"; allow the whole identifier (and the
+# singular "BAL") so the BAL terminology in comments/config passes.
+[default.extend-identifiers]
+BAL = "BAL"
+BALs = "BALs"