Skip to content

Document Gloas support, add a testnet runbook, and publish a helix-builder image - #578

Open
0w3n-d wants to merge 2 commits into
od/gloas-build-amsterdam-step4from
od/gloas-docs-step5
Open

Document Gloas support, add a testnet runbook, and publish a helix-builder image#578
0w3n-d wants to merge 2 commits into
od/gloas-build-amsterdam-step4from
od/gloas-docs-step5

Conversation

@0w3n-d

@0w3n-d 0w3n-d commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator

Issue: #561 (step 5 of 5, final)

What this PR does

Adds docs/gloas-testnet.md: what to configure, in what order, to run relay +
ethrex simulator + ethrex builder on a Gloas CL with an Amsterdam EL, and how to
tell it is working.

Most of it records things that are not discoverable from the code, which is
the reason the runbook is worth having:

  • The two EIP-8282 predeploys must be in the EL genesis. Without them every
    Amsterdam block is invalid with SystemContractCallFailed ... has no code after deployment. This cost me the first four step 4 tests.
  • Every relay simulators entry needs ssz_url. Dispatch is per simulator
    and sim_request_builder still returns None for Gloas, so a JSON-only entry
    silently drops every Gloas submission as UnsupportedFork. That is Gloas (ePBS) support in helix-simulator #518
    showing up as a config requirement, and silence is the worst failure mode.
  • simulators[].url is still required even when ssz_url is set, because
    the relay uses it for eth_syncing and eth_getBalance. Point it at the same
    node's ethrex JSON-RPC. The builder README's "serves no JSON-RPC" refers to
    the validation methods, which is easy to misread as "no RPC at all".
  • A flat 21000-gas transfer to a fresh address fails under Amsterdam. Any
    funding or traffic-generating tooling needs a higher limit. Such transactions
    are included with failed receipts, which looks like a broken builder.
  • amsterdamTime and the Gloas fork epoch must line up, and why: the block shape
    follows the EL and the submission shape the CL.

It also fixes three statements in crates/builder/README.md that steps 3 and 4
made stale: the simulation role now serves Gloas on /validate (Fulu only on
/validate_merged); the payout formula's gas term is no longer just
payout_gas_reserve; and the building role now carries the access list and slot
number. Plus a Documentation section in the root README, which had no route to
docs/ at all.

The access-list size question, answered

#561 left open whether the builder sending the list is affordable. Measured
against ethrex's encoding at the pinned revision:

item bytes
account (address, balance and nonce change) ~70
storage read (slot only) ~33
storage change (slot, value, index) ~71

A realistic busy block is small — 400 transfers to 400 distinct recipients gave
a 29.7 KB list. The worst case is bounded by EIP-7928 itself, which caps
items at gas_limit / 2000: 0.4-0.9 MB at 25M gas, 0.7-1.6 MB at 45M,
1.0-2.1 MB at 60M. Even the maximum is an order of magnitude inside the relay's
20 MB MAX_PAYLOAD_LENGTH.

So the builder sending it stands. Two measurement traps are worth recording
for anyone re-running this: a contract storing small integers RLP-compresses to
~1.2 bytes/item and understates the size ~50x, and 200 SSTOREs under Amsterdam
runs out of gas and records reads rather than changes. The figures above come
from a run where the writes committed, cross-checked against ethrex's own
item_count().

Also: a helix-builder package

Adds a build-builder job to .github/workflows/build.yml, against the
builder.Dockerfile that was already in the tree but wired to nothing. It
publishes ghcr.io/<owner>/helix-builder, and is byte-identical to the
build-simulator job apart from the component name -- including the
pull_request branch in Set IMAGE_NAME, which is unreachable given the
workflow's triggers but is what the other three jobs carry.

The workflow only fires on pushes to main/develop and on
workflow_dispatch, so it will not run on this PR. To see it pass before
merging, dispatch it manually against this branch.

I verified the Dockerfile is not stale by building its chef and planner
stages, which is where a manifest change would break it -- step 4 added
ethrex-levm to the workspace. I did not run the full cook/build: that is an
ethrex plus rocksdb compile, and CI is the right place for it.

admin.Dockerfile also has no job. Left alone as out of scope; worth a
follow-up if the admin image is meant to be published.

What this PR deliberately does not do

  • No merging. Step 5 of Gloas support across the ethrex builder's three roles #561 was split out to Gloas (ePBS) support in the ethrex builder's merging role #576 -- it needs a
    merging-protocol wire-format change, and the testnet does not depend on it.
    The runbook says so under "What is not supported" rather than leaving a gap.
  • No code changes. Documentation, three stale README lines, and the CI job.
  • No matrix refactor of build.yml. Four near-identical 40-line jobs invite
    drift, but collapsing them would rewrite the three existing jobs in a docs
    PR. Worth doing separately.
  • No scripts. A Kurtosis-style Gloas devnet would be useful but is its own
    piece of work; the runbook is written for a testnet you already have.
  • The measurement probes are not committed. They answered a one-off question
    and would be brittle against ethrex changes; the numbers are in the runbook
    and on Gloas support across the ethrex builder's three roles #561.

Tests

None: no behaviour changes. The existing 414 pass, and I checked the relative
link from crates/builder/README.md resolves. The CI job was checked
structurally against the simulator job and by building the Dockerfile's early
stages, as above.

Placed in docs/ beside architecture.md. Flagging the judgment call since
CLAUDE.md says not to put specs or plans there -- this is neither, it documents
what exists, but say the word and I will move it under scripts/devnet/.

Reviewer checklist

  • CI (lint, unit-test) is green
  • Matches the linked issue/step
  • No unexplained scope creep or unrelated files touched

Records the genesis, relay and builder configuration a Gloas testnet
needs, including the requirements that are not discoverable from the
code: the EIP-8282 predeploys, ssz_url on every simulator, and the
Amsterdam gas cost of a first payment.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Mirrors the existing relay, data-api and simulator jobs against the
builder.Dockerfile that was already in the tree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@0w3n-d 0w3n-d changed the title Document Gloas support and add a testnet runbook Document Gloas support, add a testnet runbook, and publish a helix-builder image Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant