You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0d1eb5d
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: docs/reference/cli.md
+37-1Lines changed: 37 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,7 +75,7 @@ process-wide. Watch the effect on
75
75
| Flag | Default | Description |
76
76
| --- | --- | --- |
77
77
|`--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). |
79
79
|`--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). |
80
80
81
81
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
85
85
`source`, so `requests_total` falling while `gate_skips_total` rises is the relief
86
86
working, not the tracker stalling.
87
87
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
0 commit comments