Skip to content

docs: fix e2e test port ranges in docs/testing.md - #458

Open
erkancamli wants to merge 2 commits into
SeismicSystems:mainfrom
erkancamli:docs/fix-e2e-port-ranges
Open

erkancamli wants to merge 2 commits into
SeismicSystems:mainfrom
erkancamli:docs/fix-e2e-port-ranges

Conversation

@erkancamli

@erkancamli erkancamli commented Sep 13, 2026 •

Copy link
Copy Markdown

The port ranges in the E2E "Prerequisites" section do not match what the test bins bind, and the first revision of this PR got the correction half wrong. This revision lists every port and states the mapping the numbers come from.

Reth's --instance N moves four different ports, in three different directions. Each instance is spawned with .instance(x + 1) (node/src/bin/stake_and_checkpoint.rs:134, and the same in the other e2e bins). Reth's adjust_instance_ports then applies:

auth_port += instance * 100 - 100
http_port -= instance - 1
ws_port   += instance * 2 - 2

and NetworkArgs::adjust_instance_ports shifts the discovery port by instance - 1. Instances 1 through 6 are used (four genesis nodes, a fifth node in three bins, and observer at OBSERVER_SLOT = NUM_NODES + 1 = 5, node/src/bin/observer.rs:62,251), so:

instances 1..6
HTTP RPC 8545, 8544, 8543, 8542, 8541, 8540
WS 8546, 8548, 8550, 8552, 8554, 8556
auth RPC 8551, 8651, 8751, 8851, 8951, 9051
discovery 30303 .. 30308

HTTP counts down, as docs/running-local-network.md:35 and the header of node/src/bin/testnet.rs say. WS and auth count up, which neither doc mentions. types/src/reth.rs always passes --ws (line 515) and spawn() blocks until reth reports both RPC WS server started and RPC auth server started, so those ports are provably bound on every e2e run.

Each bin also passes --metrics 0.0.0.0:{9001 + node} and --enclave.endpoint-port 1744{node} explicitly, so 9001-9006 and 17440-17445 are bound too.

The Summit and P2P ranges were sized for the four genesis nodes. get_node_flags derives 3030 + node * 10 (RPC), 3031 + node * 10 (admin RPC) and 26600 + node * 10 (P2P). With the fifth node and the observer these reach 3080/3081 and 26650.

Following the current text, a reader frees ports nothing uses and leaves ports the tests need occupied. The run then fails as a node that never reaches its stop height rather than as a clear bind error.

Documentation only, no code change. Same class of fix as #441, which corrected this in docs/running-local-network.md but did not touch docs/testing.md. Filed against fa436b4.


Correcting the record on my own first revision: it said "so 8546-8548 are never bound while 8542-8544 are". That is wrong. 8546 and 8548 are the WS ports of instances 1 and 2, and types/src/reth.rs waits for them before returning. Only 8547 is unbound. The narrowed 8540-8545 range it proposed would have caused exactly the failure this PR is meant to prevent. Fixed in ab0f360.

The Prerequisites list in docs/testing.md does not match what the e2e
bins bind, in three ways.

Reth RPC counts down from 8545, not up. Each instance is spawned with
`.instance(x + 1)`, which reth maps to `8545 - N + 1`, so 8546-8548 are
never bound while 8542-8544 are. docs/running-local-network.md and the
header comment in node/src/bin/testnet.rs already say this.

The Summit and P2P ranges were sized for the four genesis nodes. The
flags are derived as `3030 + node * 10`, `3031 + node * 10` and
`26600 + node * 10`; stake-and-checkpoint, stake-and-join-with-outdated
-checkpoint and sync-from-genesis add a fifth node, and observer runs at
`OBSERVER_SLOT = NUM_NODES + 1`, reaching 3080/3081 and 26650.

Following the current text, a reader frees ports nothing uses and leaves
ports the tests need occupied. The run then fails as a node that never
reaches its stop height rather than as a bind error.

Filed against fa436b4.
The previous revision narrowed the reth range to 8540-8545 and said 8546-8548 are
never bound. That is wrong: reth's --instance N shifts the WS port up by 2 per
instance (8546, 8548, 8550, ...) and the auth port by 100, and types/src/reth.rs
always passes --ws and blocks until reth reports both the WS and the auth server
started. Discovery, metrics and the enclave mock server are bound too.

List them all and state the --instance mapping so the prerequisite is checkable
against the code rather than approximated.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants