Repository navigation
docs(node): add a guide for running frozen nodes - #97
Conversation
Add node/frozen-nodes.mdx under Advanced Operations. It explains how freeze mode works, lists the v6.7 freeze heights and frozen-node release for Sei Mainnet and Sei Testnet, walks through setting up and verifying a frozen node, routes EVM JSON-RPC by height with frozen-rpc-router, and describes the routine for each later upgrade. Link the guide from the Nodes overview, the node types list, the major update procedure, and the technical reference. In the technical reference, replace "a fresh sync from genesis" with a copy of another node's data directory, since freeze mode disables state sync and the public networks cannot start from genesis. Co-authored-by: Cursor <cursoragent@cursor.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
PR SummaryLow Risk Reviewed by Cursor Bugbot for commit cabe7ab. 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.
This PR adds a frozen-node operator guide and links to it from related pages. It's well structured, follows the repo terminology and component conventions, and is consistent with the existing technical reference. I found no blocking issues, only a few minor notes.
Findings: 0 blocking | 4 non-blocking | 1 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- The Cursor second-opinion review (
cursor-review.md) was empty. Codex reported no material issues.REVIEW_GUIDELINES.mdwas empty, so no repo-specific review guidelines were applied. - I couldn't independently check the hard-coded upgrade heights (
236450000for Sei Mainnet,273966500for Sei Testnet) or the v6.6.4 behavior claims from here. The PR description says they were checked against the on-chainapplied_planand the sei-chain source. A maintainer with chain access should spot-check them before merging. The hex example0xe17f0cfdoes equal 236449999. - The Advanced operations
CardGroupinnode/index.mdxchanged fromcols={3}tocols={2}. With four cards this gives a balanced 2×2 grid, which is fine. Just confirm it renders as intended. - 1 suggestion(s)/nit(s) flagged inline on specific lines.
|
|
||
| ```bash | ||
| sudo systemctl stop seid | ||
| rsync -a $HOME/.sei/ <user>@<frozen-host>:.sei/ |
There was a problem hiding this comment.
[nit] This rsync copies the whole home directory, including config/priv_validator_key.json. That's harmless in full mode, but it's worth saying explicitly. Readers might otherwise think the frozen host needs or should keep validator keys, and a source that was ever a validator would leave a key copy on another host. You could add --exclude config/priv_validator_key.json or a one-line note. Also, the remote path .sei/ is relative to the SSH user's home, so it only works if that user is the one that runs seid on the new host.
Keep the validator signing key off the frozen host. Exclude it from the rsync copy, and delete it on the new host after a volume snapshot. Say that the remote rsync path is relative to the SSH user's home. Spell out the snapshot path. Provider snapshots are usually newer than the freeze height, a new host needs seid init and the archive settings, and the snapshot guide's restart step must be skipped. List Autobahn among the freeze mode startup rejections in the guide and the technical reference. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
This PR adds a thorough, accurate guide for frozen nodes, and it is well linked from related pages. The freeze heights, the hex block number (0xe17f0cf = 236449999), and the routing boundaries are consistent. Two procedural gaps, both raised by Codex, could block operators who follow the steps on a fresh host.
Findings: 0 blocking | 4 non-blocking | 2 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- The Cursor review file was empty, so that pass produced no output. REVIEW_GUIDELINES.md was also empty, so I reviewed against AGENTS.md conventions only.
- Optional: since the page lists v6.6.4 as a requirement, link the v6.6.4 release notes or sei-chain#4448 in the v6.6.3 warning so readers can confirm the restart fix themselves.
- 2 suggestion(s)/nit(s) flagged inline on specific lines.
| ``` | ||
|
|
||
| <Note> | ||
| To start from a provider's archive snapshot instead, install the outgoing release first, as described in the next step. Then run `seid init <moniker> --chain-id pacific-1` on the new host, which writes the configuration files and the genesis file. For full history, set the archive settings from [Node types](/node/node-types). Restore the snapshot with the [snapshot guide](/node/snapshot), but stop before its restart step. Then continue with step 3. |
There was a problem hiding this comment.
[suggestion] In the provider-snapshot path, seid init writes a config with no seeds or persistent peers. Nothing in this path tells the reader to add them. 'Before you begin' says the node needs peers that store the blocks from the snapshot's height up to the freeze height, but if none are configured, block sync can't reach freeze-height - 1. Add a step, or a link, for setting persistent-peers/seeds in config.toml, ideally pointing at archive peers. (Also raised by Codex.)
| Start `seid` and follow the log: | ||
|
|
||
| ```bash | ||
| sudo systemctl start seid |
There was a problem hiding this comment.
[suggestion] On a new host, neither step 1 (rsync of .sei/) nor step 2 (binary install) creates seid.service. Running sudo systemctl start seid then fails with Unit seid.service not found. Add the unit setup or link to it, and make sure ExecStart points to the v6.6.4 binary and that no cosmovisor setup can auto-upgrade it. (Also raised by Codex.)
On the snapshot path, initialize with seid init --mode archive, which keeps all history, and point persistent-peers at archive nodes that still store the blocks up to the freeze height. Note in Before you begin that pruned peers delete old blocks. On a new host, create a systemd unit that runs the v6.6.4 binary directly, not through Cosmovisor. On a host that already has a unit, check its ExecStart. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
This is a well-researched new guide for frozen nodes, and its cross-links and redirect-free additions are consistent. I checked that the example EVM block hex (0xe17f0cf) equals 236449999. One procedural gap is worth fixing before merge: the copy step misses state-store databases kept outside $HOME/.sei.
Findings: 0 blocking | 4 non-blocking | 1 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- The Cursor second-opinion pass produced no output.
REVIEW_GUIDELINES.mdon the base branch is empty, so this review applies only AGENTS.md conventions. seid query upgrade plan(in the freeze heights section and in 'Prepare for each upgrade') has no--nodeflag. On a host without a local synced RPC it will fail. Consider showing--node <rpc>or the REST equivalent (/cosmos/upgrade/v1beta1/current_plan), as you did for the applied-plan query.- The page hard-codes v6.6.4 and a Go version (1.25.6). Both are fine for the v6.7 freeze, but they will go stale for later upgrades. The 'Prepare for each upgrade' section already generalizes this, so consider saying explicitly that the table is the place to update for each new upgrade.
- 1 suggestion(s)/nit(s) flagged inline on specific lines.
|
|
||
| <Step title="Copy the data directory"> | ||
|
|
||
| Stop `seid` on a node that holds the history you want to serve. Take a volume snapshot of its data disk, or copy its whole home directory, including `data/` and `wasm/`, to the new host. Then start the source node again. |
There was a problem hiding this comment.
[suggestion] Raised by Codex, and I agree. Copying $HOME/.sei (or the data disk) skips state-store databases that sit outside the home directory because of a non-empty ss-db-directory or evm-ss-db-directory in app.toml. The frozen node would then start but be unable to serve that historical state. Other pages already warn about this (node/snapshot.mdx:69, node/statesync.mdx:42, node/node-operators.mdx:1762). Please add a step here too: check both settings, copy those directories while the source is stopped, and set matching paths in app.toml on the destination.
This branch was successfully deployed
1 participant
Problem
Freeze mode (
freeze-height) andfrozen-rpc-routerhave shipped since v6.6.3, but the docs only describe them in the technical reference, as flags and routing rules. An operator who wants to keep serving history from before an upgrade has no page that says which height to freeze at, which release to run, when the node has to be set up, or how to route queries by height.The timing matters more than the flag. A node saves each block before it executes it, so a node that has already halted at an upgrade height holds the upgrade block and refuses that
freeze-height. Once the chain passes the upgrade, a frozen node for it can only be built from data below that height.Change
Adds
node/frozen-nodes.mdx(Frozen Nodes under Advanced Operations):236450000) and Sei Testnet (273966500), with v6.6.4 as the frozen node release. v6.6.3 is called out because its EVM RPC does not come back after a restart.app.tomlexcerpt that shows where the key sits), start, verify, and back up.frozen-rpc-router: the exclusive boundary, aSei-RPC-Routeheader check, and the router's limits.The guide is linked from the Nodes overview (new card), the node types list, the major update procedure in
node-operators.mdx, and the freeze mode and router sections of the technical reference. The style guide's Advanced Operations list gets the new page.In the technical reference, "a fresh sync from genesis" becomes "a copy of another node's data directory". Freeze mode disables state sync, and the same page already says that nodes cannot start directly from the genesis file.
Verification
/cosmos/upgrade/v1beta1/applied_plan/v6.7returns236450000on Sei Mainnet and273966500on Sei Testnet, and neither chain has a plan scheduled.v6.6.4andv6.7.1: the startup checks invalidateFreezeHeight, the save-before-execute order in consensus and block sync, the restart fix from sei-chain#4448 (in v6.6.4, not in v6.6.3), the log lines quoted on the page, thesei_chain_app_build_infometric, and the router's routing table and header. The router code is the same in v6.6.4 and v6.7.1./statuson v6.6.4 returns the result object without a JSON-RPC wrapper, so the page reads.sync_info.latest_block_height.typos, Vale (no alerts on changed lines),scripts/check-redirects.mjs,scripts/check-skills.mjs,scripts/audit-seo.mjs(no findings for the new page), andmint broken-links --check-anchors. Rendering checked withmint dev.Notes
llms.txtandllms-full.txtare left to the weekly regeneration workflow, asAGENTS.mdasks.Made with Cursor