Skip to content

Commit 0d1eb5d

Browse files
committed
docs(cli): --chain-tracker-poll-divisor allows a cadence slower than 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.
1 parent 6ea0c89 commit 0d1eb5d

1 file changed

Lines changed: 37 additions & 1 deletion

File tree

‎docs/reference/cli.md‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ process-wide. Watch the effect on
7575
| Flag | Default | Description |
7676
| --- | --- | --- |
7777
| `--enable-fork-detection` | `false` | Turn on block-hash polling (reorg detection on upstreams). Off by default — the larger of the per-pod savings. |
78-
| `--chain-tracker-poll-divisor` | `2` | The tracker polls every `avgBlockTime ÷ divisor`. `1` halves the polling rate. Allowed `[1,8]`; out-of-range reverts to the default. |
78+
| `--chain-tracker-poll-divisor` | `2` | The tracker polls every `avgBlockTime ÷ divisor`. `1` halves the polling rate; `0.25` — one poll per **four** block times — cuts it eightfold. Allowed `[0.25,8]`; out-of-range reverts to the default. See [Polling slower than the chain](#polling-slower-than-the-chain). |
7979
| `--shared-state` (with `--cache-be`) | `false` | Share poll observations across router replicas through the cache, so an upstream is polled about once per interval **fleet-wide** rather than once per pod. See [Cache & shared state](#cache-shared-state). |
8080

8181
The tracker also skips a poll whenever something else has already kept the upstream's
@@ -85,6 +85,42 @@ poll another replica made. Skipped ticks show up on
8585
`source`, so `requests_total` falling while `gate_skips_total` rises is the relief
8686
working, not the tracker stalling.
8787

88+
### Polling slower than the chain
89+
90+
A divisor below `1` polls less often than the chain produces blocks, which is where
91+
the relief is on a fast chain. Measured requests/min per endpoint:
92+
93+
| Chain | `2` (default) | `1` | `0.5` | `0.25` |
94+
| --- | --- | --- | --- | --- |
95+
| Aptos | 600 | 300 | 150 | 75 |
96+
| Solana | 300 | 150 | 75 | 37.5 |
97+
| Base | 60 | 30 | 15 | 7.5 |
98+
| Ethereum | 9.2 | 4.6 | 2.3 | 1.2 |
99+
100+
What bounds the low end is the staleness window — `max(10 × avgBlockTime, 2s)`, past
101+
which an observation stops counting for consensus, the tip reads unknown, and the probe
102+
scores a healthy upstream not-alive. The window does **not** move with this flag; the
103+
flag moves how long a tip can go unrefreshed, the other side of that comparison. Both
104+
common cases stay well inside it:
105+
106+
- **Idle upstream** — nothing but its own poll refreshes the tip, so the gap *is* the
107+
interval: 4 × `avgBlockTime` at `0.25`, against a 10× window.
108+
- **Served upstream** — relays refresh the same tip, so traffic bounds the gap.
109+
110+
The seam is between them: an upstream that trips the traffic gate and *then* goes quiet
111+
is refreshed by neither, and the worst-case gap becomes `(maxRelaySkips + 1) × interval`
112+
— 20 × `avgBlockTime` at `0.25`. That is a property of the **product** of this flag and
113+
the gate's skip budget, not of either alone, so the router warns once per chain at
114+
startup rather than refusing to start:
115+
116+
```
117+
WRN poll cadence can outrun the staleness window when the traffic gate skips
118+
pollInterval=60s worstCaseGapBetweenPolls=5m0s stalenessWindow=2m30s maxRelaySkips=4
119+
```
120+
121+
It is a line to read, not a failure — the configuration is safe for both common cases.
122+
If you see it on a chain with bursty traffic, step back toward `0.5` or `1`.
123+
88124
## Consistency tuning
89125

90126
| Flag | Default | Description |

0 commit comments

Comments
 (0)