Lanes & concurrency

How it works

A lane is not a config object. It is an emergent artifact: when a request carries a use-upstream selector (via X-ERPC-Use-Upstream header, ?use-upstream= query parameter, or directivesDefaults.useUpstream in config), eRPC resolves which upstreams match. If the matched set is a proper subset of at least two upstreams — and the selector is "simple" (see below) — eRPC derives a stable key by SHA-256-hashing the sorted upstream IDs, then lazily creates a servedTipLane for that key (servedTipLaneFor). A lane holds no pick state: only its label and, per axis, an in-process anchor for the advance-age gauge, the regression guard's memory and, on finalized, the finalized floor. The network-wide pick is the lane servedTipAll, labelled "all". The tip itself is the served-tip rule over the matched subset, computed fresh for every selector, lane or not. Only the network-wide lane's finalized floor is shared across pods. Source: erpc/networks.go:L113-132, erpc/networks.go:L628-655

LaneName algorithm. LaneName(ids) sorts the upstream IDs alphabetically, then builds a set of non-empty hyphen-split tokens for each ID (empty strings from consecutive hyphens are discarded). It walks the tokens of the first sorted ID and returns the first token that appears in every other ID's token set. If no universally shared token exists, it falls back to a concatenation of the first two characters of each ID (up to five IDs). The result is deterministic and order-independent — every pod reaches the same name from the same upstream topology. Source: common/lane.go:L25

What counts as a "simple" selector. isSimpleGroupSelector rejects selectors that contain whitespace, |, &, (, ), or , (no boolean combinators), or more than one ! not at position 0, or length > 128 characters. Qualifying examples: flashblocks*, !flashblocks*, family:systx, alchemy-*. Non-qualifying: alchemy | quicknode, (a | b).

Lane lifecycle and cap. Lanes are stored in a sync.Map keyed by "grp:<hex16>" (the first 8 bytes of the SHA-256 digest encoded as 16 hex characters). On the fast path, sync.Map.Load returns an existing lane with no locking. On the slow path, an atomic.Int32 counter is checked against maxServedTipLanes = 16; if at the cap, the request gets the same subset pick with no lane. Because the check-and-create is not atomic, up to 16 + goroutine-concurrency lanes can transiently exist — LoadOrStore guarantees exactly one lane wins per key.

The lane key is derived from the matched upstream set, not the selector text. flashblocks* and fl* targeting the same three upstreams produce the same key and share one lane. Cardinality is bounded by the actual upstream topology, not selector diversity.

Method subsets. Only upstreams that serve the request's method (ignoreMethods/allowMethods) vote on its served tip. A request whose method every upstream serves, or none does, uses its selector's lane. One whose method only some upstreams serve forms no lane of its own: it reads its selector lane's view capped at the block servedTip.quorum of the serving upstreams hold, with the stateless pick (no guard, no finalized floor, no gauges). Each method's voter set is built on its first request and rebuilt when the network's upstreams or an upstream's method filter change; a request reads it with one lookup. Only method names the config or the built-in tables define exactly are cached; a casing variant (ETH_CALL) or an unknown name is resolved per request.

No lane. When a selector is complex, matches fewer than two upstreams, matches all upstreams, or arrives past the cap, laneFor returns nil. The subset pick still applies, with no regression guard, no anchor and no gauge write, so a subset value never overwrites the lane="all" gauge.

UseUpstream directive precedence (highest to lowest):

1. X-ERPC-Use-Upstream header on the request.
2. ?use-upstream=<value> query parameter.
3. networks[*].directivesDefaults.useUpstream config default.

The selector is used in two places: to narrow the served-tip ballot (and resolve its lane), and inside the upstream selection loop (UpstreamMatchesSelector) to filter which upstreams receive the request. Tag-based matching is supported — family:flashblocks matches any upstream whose tags include that key — but negated selectors (prefix !) never match by tag, only by upstream ID.

Config schema

Lanes themselves are not directly configured — they emerge from runtime request selectors and the upstream topology. They need no servedTip block; servedTip.quorum applies inside each lane as it does network-wide.

Worked examples

1. Pin all network traffic to flashblocks upstreams. Set directivesDefaults.useUpstream at the network level so every request on that chain automatically routes to flashblocks providers and gets a flashblocks-accurate tip:

projects:  - id: main    networks:      - architecture: evm        evm: { chainId: 1 }        directivesDefaults:          useUpstream: "flashblocks*"  # all requests → flashblocks lane

2. Per-request lane selection via header. Send X-ERPC-Use-Upstream: systx* on individual requests to route them to system-transaction-capable upstreams. eRPC derives the lane name, computes a systx-scoped tip, and serves block numbers visible to that provider class only.

3. Tag-based lane targeting. If upstreams are tagged with family:archive, a selector family:archive is simple, qualifies for a lane, and routes archive-depth calls to archive nodes — LaneName derives a human-readable label from the matched upstream IDs for your dashboards.

4. Complex selector routing without lane tip tracking. A selector like alchemy | quicknode routes to both providers correctly via UpstreamMatchesSelector in the forwarding loop — but it is not simple, so no lane is created and no lane=... gauge appears. The tip is still computed over the two providers; this is expected behavior for multi-provider round-robin.

Best practices

• Use simple glob selectors (flashblocks*, family:archive) rather than boolean expressions when you need per-group gauges or the regression guard; boolean selectors route and scope the tip correctly but never get a lane.
• Set directivesDefaults.useUpstream at the network level rather than injecting headers per-request — it ensures every request (including retries and hedges) carries the selector without client cooperation.
• Keep the total number of distinct upstream subsets below 16 per network; beyond that, additional groups get no gauges and no regression guard.
• Do not rely on LaneName label values being unique — two different upstream sets can produce the same label. Use the lane key (internal) as the stable identifier; the label is for human readability only.
• Negated selectors (!alchemy-*) match by upstream ID only, not by tag. If you need tag-based exclusion, restructure as an inclusion selector on the desired tag instead.

Edge cases & gotchas

1. A single matched upstream does not form a lane. partitionKeyFor requires len(matched) >= 2; a single-upstream selector gets that upstream's head and emits no gauge.
2. Matching ALL upstreams does not form a lane. len(matched) >= len(all) also falls through, preventing a match-all selector from shadowing lane="all".
3. Boolean combinator selectors are never partitioned. alchemy | quicknode contains |; it routes and scopes the tip correctly but never gets a lane.
4. The 16-lane cap is a soft guard. Concurrent goroutines can transiently exceed 16. Beyond the cap, new groups get no lane.
5. Lane key = hash of matched upstream set, not selector text. flashblocks* and fl* matching the same upstreams share one lane. Cardinality is bounded by topology, not by selector diversity.
6. LaneName is not guaranteed unique. Two different upstream sets could produce the same name if both share the same common token. The lane key is the stable identifier; the name is decorative for dashboards.
7. Negated selectors match by ID only, never by tag. A pattern containing ! skips tag evaluation entirely. !alchemy-* excludes by ID but will not rescue non-matching IDs via tags.
8. LaneName sort is alphabetical. For (quicknode-systx, systx-quicknode), sorted order puts quicknode-systx first; LaneName returns "quicknode", not "systx". Source: common/lane_test.go (order independent test).
9. Lane state is per process. Anchors, regression-guard memory and finalized floors live in memory; a restarted pod rebuilds them from live heads. The network-wide lane's finalized floor is also shared across pods, so a restarted pod serves it again once one of its voters reports it.
10. LaneName output is written to Prometheus labels as-is, without sanitization. If upstream IDs contain unusual characters that cause LaneName to produce an unexpected string, that string becomes the label value verbatim. The label is never normalized or escaped beyond what LaneName itself produces.

Observability

Lanes are the lane label of the four erpc_network_served_tip_* series (meanings): lane="all" is the network-wide pick (servedTipAll), lane=<LaneName> a group's own pick. A named lane's series exist only for networks that receive targeted use-upstream traffic; a request without a lane writes no series. Source: erpc/networks.go:L1647-1677

Source code entry points

• common/lane.go (opens in a new tab) — LaneName(ids []string) string: naming algorithm, pure function.
• common/lane_test.go (opens in a new tab) — unit tests for LaneName: shared-token precedence, order-independence, fallback combo, single-id, empty input, determinism.
• erpc/networks.go:L117-L137 (opens in a new tab) — maxServedTipLanes = 16, servedTipLane struct.
• erpc/networks.go:L640-L667 (opens in a new tab) — servedTipLaneFor: lazy lane materialization with cap and sync.Map.
• erpc/networks.go:L669-L758 (opens in a new tab) — partitionKeyFor: selector → SHA-256 key; EvmUpstreamGroupForSelector; isSimpleGroupSelector filter.
• erpc/networks.go:L883-L971 (opens in a new tab) — servedTip: guard, floors and gauges per lane.
• erpc/networks.go (opens in a new tab) — bindLaneGauges, servedTipGauges.observe: gauges bound once per lane label.
• common/matcher.go:L73-L112 (opens in a new tab) — MatchesSelector + UpstreamMatchesSelector: ID + tag matching primitive.
• common/request.go:L739-L741 (opens in a new tab) — X-ERPC-Use-Upstream header extraction.
• common/request.go:L811-L812 (opens in a new tab) — ?use-upstream= query-param extraction.
• common/request.go:L1424-L1445 (opens in a new tab) — UpstreamMatchesSelector call in the upstream selection loop; filters which upstreams receive the forwarded request.
• erpc/networks.go:L630-L639 (opens in a new tab) — requestSelector(ctx): reads UseUpstream directive from the bound request context for both served-tip and forwarding use.
• common/config.go:L2109 (opens in a new tab) — DirectivesConfig.UseUpstream field.
• telemetry/metrics.go:L198-L250 (opens in a new tab) — metric definitions.

Related pages

• Matcher — the UpstreamMatchesSelector and tag-matching primitives used to resolve which upstreams a selector targets.
• Tag-aware routing — how use-upstream integrates with the upstream selection loop.
• Block tracking & served tip — the served-tip rule that lanes scope.
• Rate limiters — per-upstream rate limits that interact with lane-scoped routing.