docs: v6.6.3 catch-up - #69
Conversation
…ow puts a full node into read-only freeze mode where transaction/evidence submission, mempool gossip, and state sync are disabled, and it is no longer supported in validator or seed modes. (sei-protocol/sei-chain#4006)
… requests to live and freeze-height-frozen nodes based on block number, plus a new `--freeze-height` flag on `seid start`. (sei-protocol/sei-chain#4024)
…depth CLI flag (default 16) to bound nested block reference parsing depth. (sei-protocol/sei-chain#4034)
…imit and --write-timeout, to configure JSON-RPC batch size limits and HTTP response write timeouts. (sei-protocol/sei-chain#4048)
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
PR SummaryLow Risk Overview
It also documents
Reviewed by Cursor Bugbot for commit 3bbe239. Bugbot is set up for automated code reviews on this repo. Configure here. |
![seidroid[bot]](https://avatars.githubusercontent.com/in/2745135?s=60&v=4){kind=small}
There was a problem hiding this comment.
Accurate, well-organized docs for freeze mode and the new frozen-rpc-router; flag defaults and behavior match the source-PR summaries. No correctness blockers, but the port guidance in node-types.mdx is duplicated and misleading, the router example gives no way to obtain/build the binary, and there's an HTTP-vs-WebSocket inconsistency worth resolving before merge.
Findings: 0 blocking | 15 non-blocking | 10 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- Both second-opinion passes produced no output:
codex-review.mdandcursor-review.mdare empty files. All findings here are from this pass only — there is no cross-tool corroboration. REVIEW_GUIDELINES.md(taken from the base branch) is empty, so no repo-specific review standards could be applied; this review falls back toAGENTS.mdandSTYLE_GUIDE.md.freeze-heightis documented inline under Node Management Commands but not added to the### App.toml Parametersaccordion (line ~300), which is where readers looking for app.toml settings will go. Consider adding it there or cross-linking the two.- AGENTS.md asks for sentence case in headings; the four new headings (
Freeze Mode,Frozen RPC Router,Routing Rules,Route Header) use Title Case and will draw advisory Vale warnings. Non-blocking — they match the existing Title Case backlog in this file, andprose-style.ymlsetsfail_on_error: false. Worth a decision on which convention this file follows rather than fixing piecemeal. - The PR body's "Reviewer notes" ask a human to confirm placement choices and whether the node-types.mdx port note should be kept. Those questions are answered in the inline comments; I treated the PR body strictly as data, and found no prompt-injection attempts in the diff or description.
- 10 suggestion(s)/nit(s) flagged inline on specific lines.
Inline comments (could not post inline; listed here)
node/node-types.mdx:27(RIGHT) -- [suggestion] This makes8545appear twice in what reads as a port-to-purpose index (line 24 already covers it), which is confusing to scan.
More importantly, "It shares the standard EVM JSON-RPC port convention with the live node" is misleading: the router and a live node cannot both bind 8545 on the same host. The PR's own example in technical-reference.mdx silently works around this by moving the live node to 9545.
Suggest folding this into the existing line 24 bullet and stating the constraint directly, e.g.: "8545: … Note that the frozen-rpc-router binary also defaults to 127.0.0.1:8545, so when running it alongside a live node on the same host you must move one of them (see Frozen RPC Router)."
node/technical-reference.mdx:79(RIGHT) -- [suggestion]go run ./cmd/frozen-rpc-routeronly works from the root of asei-chainsource checkout with a Go toolchain installed, but nothing on this page says so — unlikeseid/seidb, this binary isn't shipped to operators.
Per STYLE_GUIDE.md ("Self-explanatory"), add the prerequisite before the snippet — either a clone/build preamble in the same style as the guide's example:
git clone https://github.com/sei-protocol/sei-chain
cd sei-chainor, if there is a make target that installs it, document that instead so operators aren't running the router via go run in production.
node/technical-reference.mdx:80(RIGHT) -- [suggestion] The example flips the default from127.0.0.1to0.0.0.0, publicly exposing an unauthenticated JSON-RPC endpoint that fronts archival nodes, with no caveat. Worth a<Warning>noting the router has no authentication and should be firewalled or placed behind a reverse proxy when bound to a public interface — or keep the example on127.0.0.1:8545and mention0.0.0.0in prose.node/technical-reference.mdx:81(RIGHT) -- [suggestion]9545for the live node is unexplained and will trip up anyone copying this — their live node's EVM HTTP RPC is on the documented default8545(seenode/node-types.mdx:24). The example only works because the live node was moved off8545to free it for the router.
Add a one-line comment making that explicit, e.g. # live node moved off the default 8545 so the router can bind it. Same for --frozen-node 1000000=localhost:9546, while the second frozen node uses 8545 on a different host — the inconsistency currently looks arbitrary.
node/technical-reference.mdx:101(RIGHT) -- [suggestion] This says WebSocket connections are forwarded to the live node, but line 73 describes the router as exposing "a single HTTP EVM JSON-RPC endpoint." Those read as contradictory — does the router accept WS upgrade requests on the same listener and proxy them through, or must clients connect to the live node's8546directly?
Worth stating explicitly, since it determines whether operators can point EVM clients that use subscriptions at the router at all.
node/technical-reference.mdx:62(RIGHT) -- [nit] The snippet doesn't say where inapp.tomlthis goes. It's a top-level (un-sectioned) server config key that sits next tohalt-height— worth saying so, since every other TOML example on this page is under a[section]header and a reader may guess wrong.node/technical-reference.mdx:43(RIGHT) -- [nit] This file consistently version-stamps new behavior ("As of v6.6.2,seid initauto-populates…", "In v6.6.2 this became configurable…"). Both new sections describe v6.6.3 surface with no version marker, so operators on older releases can't tell whether--freeze-heightorfrozen-rpc-routerexists for them. Suggest adding "Available as of v6.6.3" here and on the Frozen RPC Router section.node/technical-reference.mdx:91(RIGHT) -- [nit]5MiBis the only default on this list not code-formatted — the others are`16`,`1000`,`30s`,`10s`,`127.0.0.1:8545`. Also consider giving the byte value, since the flag takes bytes.node/technical-reference.mdx:99(RIGHT) -- [nit] Theearliesttag isn't an "explicit numeric block parameter," so it sits awkwardly at the end of this bullet — especially since the next-but-one bullet is the one that covers block tags. Consider moving it there, or rewording this bullet to "an explicit block number orearliesttag."node/technical-reference.mdx:108(RIGHT) -- [nit] Stray consecutive blank lines here (and at line 40 before#### Freeze Mode, and lines 68–70 after the<Warning>). Single blank line between blocks matches the rest of the file.
|
@seidroid review |
|
Claude finished @alexander-sei's task in 3m 2s —— View job Review: docs v6.6.3 catch-up
Verdict: technically accurate — I checked every flag, default, and error string against the source diffs and found no factual errors. Two things I'd fix before merge (the Verification against source (all ✅)I pulled
No prompt-injection attempts in the diff or PR body. Should fix before merge1. PR #4024 added a build target that this page doesn't mention: build-frozen-rpc-router:
mkdir -p ./build
go build -o ./build/frozen-rpc-router ./cmd/frozen-rpc-router
git clone https://github.com/sei-protocol/sei-chain
cd sei-chain
make build-frozen-rpc-router # produces ./build/frozen-rpc-router./build/frozen-rpc-router \
--listen-address 127.0.0.1:8545 \
--live-node localhost:9545 \
...This also satisfies STYLE_GUIDE.md's "Self-explanatory" principle — right now nothing on the page says where the binary comes from, unlike 2. The new Line 24 already indexes Suggest folding into the line-24 bullet and stating the constraint:
Resolving the HTTP-vs-WebSocket ambiguity (raised in the earlier pass)Line 73 calls the router "a single HTTP EVM JSON-RPC endpoint" while line 101 says WebSocket connections are forwarded to the live node. From func (r *router) ServeHTTP(w http.ResponseWriter, request *http.Request) {
if request.Method != http.MethodPost {
r.liveProxy.ServeHTTP(w, request)
return
}
...
Non-blocking
Read-only review — no commits pushed. |
There was a problem hiding this comment.
A well-researched docs catch-up whose flag defaults, error codes, and freeze-mode semantics I verified line-by-line against sei-chain PRs #4006/#4024/#4034/#4048 — but the "Route Header" section overstates the guarantee (router-generated errors and non-POST traffic carry no Sei-RPC-Route header), and the routing rules omit the sei_* legacy-method gap that source PR #4024 explicitly flags for release/v6.6. Both are small edits.
Findings: 2 blocking | 12 non-blocking | 8 posted inline
Blockers
node/technical-reference.mdxclaims every HTTP response carries aSei-RPC-Routeheader; verified againstcmd/frozen-rpc-router/router.goonrelease/v6.6this is false for router-generated errors and for non-POST traffic. See the inline comment on line 106.- 1 blocking issue(s) flagged inline on specific lines.
Non-blocking
- Neither second-opinion pass produced output:
codex-review.mdandcursor-review.mdare both empty.REVIEW_GUIDELINES.mdis also empty, so this review appliedAGENTS.mdandSTYLE_GUIDE.mdinstead. - Three runs of consecutive blank lines were introduced (before
#### Freeze Mode, between the<Warning>and### Frozen RPC Router, and between#### Route Headerand### seidb Tooling Commands). The file otherwise uses a single blank line between sections. There is no Prettier config in the repo so nothing will normalize these automatically. - The four new headings are Title Case (
Freeze Mode,Frozen RPC Router,Routing Rules,Route Header).AGENTS.mdasks for sentence case and theSei.HeadingsVale rule will annotate them, but the rest oftechnical-reference.mdxis Title Case throughout, so matching the file is defensible. Flagging only so the Vale annotations on the PR are not a surprise —prose-style.ymlsetsfail_on_error: false, so the build will not fail. freeze-heightis documented in the CLI section but not added to theComplete app.toml Configurationaccordion under### App.toml Parameters, so that reference block is now incomplete relative to the prose above it.- Consider linking the new
node-types.mdxrouter mention to/node/technical-reference#frozen-rpc-router;STYLE_GUIDE.mdfavours descriptive cross-links over leaving the reader to search. - 7 suggestion(s)/nit(s) flagged inline on specific lines.
Inline comments (could not post inline; listed here)
-
node/technical-reference.mdx:106(RIGHT) -- [blocker] "Every HTTP response carries aSei-RPC-Routeheader" is not accurate. Incmd/frozen-rpc-router/router.goonrelease/v6.6: -
writeRPCErroronly setsContent-Typeand writes the body — so-32600(batch too large),-32000(range spanning intervals), parse errors, and invalid-request errors all come back without the header. -
The oversized-body and unreadable-body paths use
http.Error(...)directly (HTTP413/400) — also no header. -
Non-POST requests are handed to
liveProxy, a plainhttputil.NewSingleHostReverseProxywith noModifyResponse. So GET traffic and WebSocket upgrades — which this page tells the reader are routed to the live node — return no header either.
Only proxy() (w.Header().Set(rpcRouteHeader, target.routeName())) and the mixed-batch path set it. The upstream cmd/frozen-rpc-router/README.md is careful about this: "Single-backend HTTP responses include Sei-RPC-Route: frozen:<height> or Sei-RPC-Route: live."
This matters because reading a route header per response is exactly how an operator would build monitoring on top of the router, and "every" invites treating a missing header as an anomaly rather than the normal error path. Suggested rewording:
Responses proxied to a single backend carry a
Sei-RPC-Routeheader identifying which backend served them:frozen:<height>for a frozen node at that freeze height, orlivefor the live node. A batch split across multiple backends returnsmixed. Errors generated by the router itself (oversized requests, malformed JSON, unsupported block ranges) and non-POST traffic forwarded to the live node do not carry the header.
node/technical-reference.mdx:99(RIGHT) -- [suggestion] Worth a<Warning>here about the legacysei_*surface.blockParameterIndexesinrouter.gocovers onlyeth_*anddebug_*methods, so block-scoped legacy methods —sei_getBlockByNumber,sei_getBlockReceipts,sei_getLogsand friends — miss the table entirely and fall through to the live node under the "methods without a block parameter" rule. At a pre-freeze height that returns not-found, with aSei-RPC-Route: liveheader suggesting the routing was deliberate.
This is not speculation: source PR #4024 calls it out as a named caveat for the release owner, and notes the exposure is wider on release/v6.6 (33 legacy methods) than on main (3), which is the branch this v6.6.3 catch-up documents. Production impact requires widening enabled_legacy_sei_apis beyond the default three non-block-scoped helpers — but an operator who has done that is exactly the operator likely to deploy the router. One sentence saying "only eth_* and debug_* methods are height-routed; block-scoped sei_* legacy methods are forwarded to the live node" would close the gap.
node/node-types.mdx:27(RIGHT) -- [suggestion] This adds a second8545bullet to a list keyed by port number, appended after26660rather than next to the existing8545entry on line 24 — so the list now has a duplicate key and is no longer grouped.
More substantively, "It shares the standard EVM JSON-RPC port convention with the live node" glosses over the operational consequence: the router's default listen address really is 127.0.0.1:8545 (confirmed in cmd/frozen-rpc-router/config.go), so running it on the same host as a live node is a direct bind conflict. The example over in technical-reference.mdx quietly works around this by putting the live node on 9545, but a reader of this page gets no warning.
Suggest folding it into the line 24 bullet and stating the collision plainly, e.g.: "8545: The default port for EVM HTTP RPC ... This is also the default listen address (127.0.0.1:8545) for the frozen-rpc-router binary, so when running the router on the same host as a live node, move one of them to a different port."
node/technical-reference.mdx:79(RIGHT) -- [suggestion]go run ./cmd/frozen-rpc-routerpresumes the reader has the sei-chain repository checked out, has a Go toolchain installed, and is sitting in the repo root — none of which this page states, and none of which is a safe assumption for docs.sei.io node operators.STYLE_GUIDE.mdasks that code blocks be directly copyable.
PR #4024 adds build and packaging for the router alongside seid, so there is likely a shipped binary to point at instead. Either reference that, or add the prerequisite lines the style guide models elsewhere:
git clone https://github.com/sei-protocol/sei-chain
cd sei-chain
go build ./cmd/frozen-rpc-routernode/technical-reference.mdx:62(RIGHT) -- [suggestion] This snippet does not say where inapp.tomlthe key belongs.freeze-heightis a top-level base-config field (it sits alongsideminimum-gas-prices, before any[section]header) — worth stating, since a reader who drops it under the last section they were editing gets silently different behaviour. A# app.toml (top level, before any [section])comment would do it.node/technical-reference.mdx:81(RIGHT) -- [nit] The example puts the live node on9545rather than the standard8545without saying why — the reason is that the router itself is binding8545on line 80. One clause makes the example self-explanatory:--live-node localhost:9545 \ # live node moved off 8545, which the router now owns.node/technical-reference.mdx:91(RIGHT) -- [nit]5MiBis missing the backticks and the space that the sibling bullets use for their defaults (16,1000,30s,10s). Suggest(default `5 MiB`). The value itself is correct —defaultMaxRequestBodySize = int64(5 << 20).node/technical-reference.mdx:108(RIGHT) -- [nit] Three consecutive blank lines before### seidb Tooling Commands; same pattern appears before#### Freeze Modeand before### Frozen RPC Router. The rest of the file uses a single blank line between sections.
Verified against sei-chain release/v6.6 (v6.6.3) before changing: - Route header: only single-backend proxied responses carry Sei-RPC-Route; router-generated errors and non-POST traffic do not - Routing rules: only POST is inspected; WebSocket upgrades are passed to the live node's HTTP endpoint, which does not serve WS, so subscription clients must use 8546 directly - Warn that block-scoped legacy sei_*/sei2_* methods are not height-routed (release/v6.6 still gates 33 of them) - Build the router with `make build-frozen-rpc-router` instead of `go run`; example binds 127.0.0.1 and explains the 9545/9546 ports; warn that the router has no authentication - Note freeze-height is a top-level app.toml key next to halt-height, link to the generated default app.toml, and add it to the accordion - Add "as of v6.6.3" markers, code-format the 5 MiB default with its byte value, require positive freeze heights, move `earliest` to the right bullet, sentence-case headings, drop stray blank lines - node-types: fold the duplicate 8545 bullet into the existing one and state the bind conflict with a live node on the same host Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Well-structured, internally consistent docs addition for freeze mode and the frozen-rpc-router; cross-links, anchors, config-key placement, and repo style conventions all check out. No confirmed defects, but the page asserts many upstream-derived specifics (build target, error strings, JSON-RPC codes, flag defaults) that a human must verify against the four source sei-chain PRs before merging.
Findings: 0 blocking | 11 non-blocking | 6 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- Both second-opinion passes produced no output:
codex-review.mdandcursor-review.mdare empty (0 findings, not 0 issues). This review is therefore single-source — consider re-running those tools before merge. REVIEW_GUIDELINES.mdis empty on the base branch, so no repo-specific review standards were applied. I substituted the conventions inAGENTS.md(sentence-case headings,<Warning>callouts, lowercase code-formattedseid, no speculation about unreleased features) — the PR conforms to all of them.- I had no network access to
sei-protocol/sei-chain, so these upstream-derived claims are unverified and should be checked against the source PRs: theErrReadOnly/RPC writes are disabled in freeze modeandfreeze height is not supported in <mode> modeerror strings; JSON-RPC codes-32600(batch too large) and-32000(block ranges spanning multiple frozen-node intervals are not supported); theSei-RPC-Routeheader name and itsfrozen:<height>/live/mixedvalues; and all flag defaults (5242880,16,1000,30s,10s). freeze-heightandhalt-heightare now documented as adjacent top-levelapp.tomlkeys, but their interaction is never stated — e.g. what happens when both are set to non-zero values, or whether a frozen node still honorshalt-height. Worth one sentence in the freeze-mode section.- Verified as correct, no action needed: the
/node/technical-reference#frozen-rpc-routerand/node/node-operators#default-configurationsanchors both resolve,node-operators.mdx:172already containsfreeze-height = 0next tohalt-height(so the "see the generated default app.toml" cross-link is live today, not pending a sync), and the security<Warning>about the router's lack of authentication is a good addition. - 6 suggestion(s)/nit(s) flagged inline on specific lines.
Inline comments (could not post inline; listed here)
node/technical-reference.mdx:78(RIGHT) -- [suggestion] Please confirm thebuild-frozen-rpc-routermake target and the./build/frozen-rpc-routeroutput path exist in the v6.6.3 tag. This PR's own reviewer notes for sei-protocol/sei-chain#4024 describe the router as "a standalonego run ./cmd/frozen-rpc-routercommand" — which contradicts these build instructions. Both can be true if #4024 also added the Makefile target, but if it did not, every reader fails on the very first step. I could not reach sei-chain to check.node/technical-reference.mdx:44(RIGHT) -- [suggestion]BroadcastTx*/BroadcastEvidenceare CometBFT RPC methods (port26657), but the section header just says "Query RPC remains available" without naming a surface. Since the whole point of a frozen node here is serving EVM JSON-RPC to the router, readers will want to know whateth_sendRawTransactionon8545does in freeze mode — rejected, or silently accepted into a mempool that never gossips? Worth stating the EVM write path explicitly alongside the CometBFT one.node/technical-reference.mdx:68(RIGHT) -- [suggestion] The rationale for multiple frozen nodes is missing, and it's the first thing an operator will wonder about. Since a freeze height is an exclusive upper boundary, the node frozen at2000000already holds every block below1000000too — so on its face the highest-frozen node alone could serve all history. One sentence on why you'd actually shard (state-store pruning, consensus-breaking upgrade boundaries, per-node disk limits) would make the two-node example in the code block motivated rather than arbitrary.node/technical-reference.mdx:118(RIGHT) -- [suggestion] This warning conflicts withevm/reference.mdx:1349, which states "Thesei2_*namespace has been removed. Most legacysei_*methods have also been removed, including block, filter, log, ... methods." This new text instead impliessei2_getBlockByNumber,sei_getLogs, etc. can still be enabled and forwarded. The allowlist innode/node-operators.mdx:455-488backs this page (they're listed as commentable-in options), so the outlier looks pre-existing inevm/reference.mdx— but the two pages shouldn't contradict each other. Worth reconciling, or droppingsei2_*from this warning if it really is gone in v6.6.3.node/technical-reference.mdx:101(RIGHT) -- [nit] "Bareip:port... accepted" reads as excluding hostnames, but the example two blocks up uses1000000=localhost:9546, and--live-node localhost:9545is a hostname as well. Suggest "barehost:port" to match what the examples actually show.node/node-types.mdx:24(RIGHT) -- [nit] "move one of them to a different port" leaves the reader to pick. Thetechnical-referenceexample resolves this a specific way — it keeps the router on8545and moves the nodes to9545/9546. Mirroring that choice here (or just linking to the example) avoids operators picking the opposite convention and then finding the linked example doesn't match their setup.
1 participant
Documentation catch-up for v6.6.3.
4 source PR(s) produced changes across 4 commit(s). Each source PR is a separate commit, so this reviews commit-by-commit.
node/technical-reference.mdx--freeze-heightflag (andfreeze-heightconfig field) now puts a full node into read-only freeze mode where transaction/evidence submission, mempool gossip, and state sync are disabled, and it is no longer supported in validator or seed modes.node/node-types.mdx,node/technical-reference.mdxfrozen-rpc-routerbinary that proxies EVM JSON-RPC requests to live and freeze-height-frozen nodes based on block number, plus a new--freeze-heightflag onseid start.node/technical-reference.mdxnode/technical-reference.mdxReviewer notes
release/v6.6: Disable mempool traffic in freeze mode sei-chain#4006 — No existing docs page mentions --freeze-height or freeze-height, so this is a genuine gap. node/technical-reference.mdx is the most appropriate home given its CLI reference and config.toml/app.toml parameter sections; the freeze-height field lives in the base app.toml (server config). node/node-operators.mdx auto-generates its app.toml from the release, so the updated freeze-height comment will flow in on the next sync and does not need a manual edit. Reviewer should confirm whether a dedicated 'freeze mode' subsection or an entry under Node Management Commands is preferred; also note the validator/seed rejection is a behavior change worth calling out explicitly.release/v6.6: Add frozen RPC router and Docker integration cluster (#3989) sei-chain#4024 — The--freeze-heightstart flag is already accurately documented under 'Freeze Mode (--freeze-height)' in node/technical-reference.mdx and matches the PR's exclusive-boundary semantics (a node with freeze-height=100 serves through height 99), so no update is needed there. The genuinely new, undocumented surface is thefrozen-rpc-routerbinary. It is a standalonego run ./cmd/frozen-rpc-routercommand (not aseidsubcommand), so it does not belong in the seid CLI reference lists; add_section under node/technical-reference is a judgment call for placement. Docker-compose/topology details from docker/README.md are repo-internal and likely out of scope for user-facing sei-docs. The node-types.mdx port note is optional/minor — a reviewer may choose to skip it.release/v6.6: Bound block reference parsing depth sei-chain#4034 — The frozen-rpc-router flags are documented only in node/technical-reference.mdx under the 'Frozen RPC Router' section; node/node-types.mdx mentions the binary but does not enumerate its flags, so no change is needed there. No migration step is required — the flag has a sensible default (16).release/v6.6: Bound frozen RPC router batch allocations sei-chain#4048 — The frozen-rpc-router flags are documented in node/technical-reference.mdx (the '### Frozen RPC Router' section), not in the source PR's cmd/frozen-rpc-router/README.md (which is not part of sei-docs). Both flags require positive values. Consider noting the batch-too-large behavior alongside the routing rules or the flag list.Generated by sei-docs-bridge. Every change is a proposal — verify against the source PRs before merging.