Document Gloas support, add a testnet runbook, and publish a helix-builder image - #578
Open
0w3n-d wants to merge 2 commits into
Open
Document Gloas support, add a testnet runbook, and publish a helix-builder image#5780w3n-d wants to merge 2 commits into
0w3n-d wants to merge 2 commits into
Conversation
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>
7 tasks
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>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
Amsterdam block is invalid with
SystemContractCallFailed ... has no code after deployment. This cost me the first four step 4 tests.simulatorsentry needsssz_url. Dispatch is per simulatorand
sim_request_builderstill returnsNonefor Gloas, so a JSON-only entrysilently drops every Gloas submission as
UnsupportedFork. That is Gloas (ePBS) support in helix-simulator #518showing up as a config requirement, and silence is the worst failure mode.
simulators[].urlis still required even whenssz_urlis set, becausethe relay uses it for
eth_syncingandeth_getBalance. Point it at the samenode'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".
funding or traffic-generating tooling needs a higher limit. Such transactions
are included with failed receipts, which looks like a broken builder.
amsterdamTimeand the Gloas fork epoch must line up, and why: the block shapefollows the EL and the submission shape the CL.
It also fixes three statements in
crates/builder/README.mdthat steps 3 and 4made stale: the simulation role now serves Gloas on
/validate(Fulu only on/validate_merged); the payout formula's gas term is no longer justpayout_gas_reserve; and the building role now carries the access list and slotnumber. 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:
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-builderpackageAdds a
build-builderjob to.github/workflows/build.yml, against thebuilder.Dockerfilethat was already in the tree but wired to nothing. Itpublishes
ghcr.io/<owner>/helix-builder, and is byte-identical to thebuild-simulatorjob apart from the component name -- including thepull_requestbranch inSet IMAGE_NAME, which is unreachable given theworkflow's triggers but is what the other three jobs carry.
The workflow only fires on pushes to
main/developand onworkflow_dispatch, so it will not run on this PR. To see it pass beforemerging, dispatch it manually against this branch.
I verified the Dockerfile is not stale by building its
chefandplannerstages, which is where a manifest change would break it -- step 4 added
ethrex-levmto the workspace. I did not run the fullcook/build: that is anethrex plus rocksdb compile, and CI is the right place for it.
admin.Dockerfilealso has no job. Left alone as out of scope; worth afollow-up if the admin image is meant to be published.
What this PR deliberately does not do
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.
build.yml. Four near-identical 40-line jobs invitedrift, but collapsing them would rewrite the three existing jobs in a docs
PR. Worth doing separately.
piece of work; the runbook is written for a testnet you already have.
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.mdresolves. The CI job was checkedstructurally against the simulator job and by building the Dockerfile's early
stages, as above.
Placed in
docs/besidearchitecture.md. Flagging the judgment call sinceCLAUDE.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
lint,unit-test) is green