Skip to content

docs(cli): a poll cadence slower than the chain's block time - #38

Merged
nimrod-teich merged 1 commit into
mag-2983from
mag-2990
Aug 23, 2026
Merged

docs(cli): a poll cadence slower than the chain's block time#38
nimrod-teich merged 1 commit into
mag-2983from
mag-2990

Conversation

@nimrod-teich

@nimrod-teich nimrod-teich commented Aug 23, 2026

Copy link
Copy Markdown
Contributor

#Closes MAG-2990

Stacked on #37 — document the fleet tracker gate behind --shared-state. Branched from mag-2983, not main, because #37 rewrites this same section and the new prose cross-references the traffic gate it documents. Base is mag-2983, so the diff here is this change alone; GitHub retargets it to main automatically once #37 merges. Merge #37 first.

Why

smart-router#323 widened --chain-tracker-poll-divisor from [1,8] to [0.25,8]. The reference still says Allowed [1,8] and presents 1 — "halves the polling rate" — as the largest relief available. At 0.25 the tracker polls once per four block times, which is 8x below the built-in cadence and the relief that actually matters on a fast chain.

The old floor of 1 was justified by the claim that below it the router's avgBlockTime-derived windows start to bind. They don't: the staleness window is max(10 × avgBlockTime, 2s) and does not move with this flag — the flag moves how long a tip can go unrefreshed, the other side of that comparison.

What changed

One file, docs/reference/cli.md:

  • The polling-relief flag row now reads [0.25,8] and names 0.25 as the eightfold cut, linking to a new subsection.
  • New "Polling slower than the chain" with the measured per-endpoint request rates (Aptos 600 → 75/min, Solana 300 → 37.5, Base 60 → 7.5, Ethereum 9.2 → 1.2), what actually bounds the low end, and the two common cases that stay inside the window — idle upstream (gap is the interval) and served upstream (relays refresh the tip).
  • The seam, and the warning it produces. An upstream that trips the traffic gate and then goes quiet is refreshed by neither, and the worst-case gap becomes (maxRelaySkips + 1) × interval — 20 × avgBlockTime at 0.25. That's a property of the product of this flag and the gate's skip budget, so the router warns once per chain at startup rather than refusing to start. The warning is reproduced verbatim, with the explicit note that it's a line to read rather than a failed boot, and what to do if you see it on a bursty chain.

The chart-side change is smart-router-helm-chart#120.

How to verify

mkdocs serve
# → /reference/cli/#polling-relief — flag row reads [0.25,8]
# → /reference/cli/#polling-slower-than-the-chain — new subsection, anchor resolves from the row link

…block time

smart-router#323 widened the range from [1,8] to [0.25,8]. At 0.25 the
tracker polls once per four block times — 8x below the built-in cadence,
and the relief that matters on a fast chain.

The old floor of 1 was justified by the claim that below it the
avgBlockTime-derived windows start to bind. They do not: the staleness
window is max(10 x avgBlockTime, 2s) and does not move with this flag —
the flag moves the other side of that comparison. Both common cases stay
well inside it; the exposure is the seam where an upstream trips the
traffic gate and then goes quiet, refreshed by neither polls nor relays.

That seam is a property of the product of this flag and the gate's skip
budget, so the router warns per chain at startup instead of refusing to
start. Documented verbatim, with what to do about it, so the line is read
as guidance rather than a failed boot.
@nimrod-teich nimrod-teich self-assigned this Aug 23, 2026
@nimrod-teich
nimrod-teich changed the base branch from main to mag-2983 August 23, 2026 10:42
@nimrod-teich
nimrod-teich merged commit abc07e7 into mag-2983 Aug 23, 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