From c9627437957d7f2ea560627327e698dec03aedb0 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:24:38 +0000 Subject: [PATCH 1/5] docs: The `--freeze-height` flag (and `freeze-height` config 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. (sei-protocol/sei-chain#4006) --- node/technical-reference.mdx | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index f8c9c2d..ee659c8 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -37,6 +37,36 @@ seid tendermint show-validator seid query node info ``` + +#### Freeze Mode (`--freeze-height`) + +The `--freeze-height` start flag (and the corresponding `freeze-height` field in `app.toml`) puts a full node into read-only freeze mode at a specified block height. Query RPC remains available so the node can continue serving reads, but write and network paths are disabled from startup: + +- Transaction and evidence submission is rejected. The `BroadcastTx`, `BroadcastTxAsync`, `BroadcastTxSync`, `BroadcastTxCommit`, and `BroadcastEvidence` RPC calls all return `ErrReadOnly` (`RPC writes are disabled in freeze mode`). +- Mempool gossip is disabled — the mempool reactor is not started and the mempool p2p channel is not advertised to peers. +- State sync is disabled. + +Block sync and consensus stop before executing the configured height and will not advance beyond it. + +```bash +# Start a full node in read-only freeze mode at a given block height +seid start --freeze-height +``` + +The same behavior can be configured persistently via the `freeze-height` field. `freeze-height` is the first block height a full node must not execute; a value of `0` disables freeze mode. + +```toml +# The first block height a full node must not execute. Query RPC remains available, +# while transaction and evidence submission, mempool gossip, and state sync are +# disabled from startup. Set to 0 to disable freeze mode. +freeze-height = 0 +``` + + + Freeze mode is only supported for full nodes. Setting a non-zero `freeze-height` in validator or seed mode is rejected at startup with an error (`freeze height is not supported in mode`). + + + ### seidb Tooling Commands The `seidb` binary provides low-level tooling for inspecting and maintaining a node's on-disk state. From b5a7bc74fb97fde14d163e8e1597090923e46efc Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:25:24 +0000 Subject: [PATCH 2/5] docs: Adds a new `frozen-rpc-router` binary that proxies EVM JSON-RPC 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) --- node/node-types.mdx | 1 + node/technical-reference.mdx | 37 ++++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/node/node-types.mdx b/node/node-types.mdx index 12c4b25..6a82444 100644 --- a/node/node-types.mdx +++ b/node/node-types.mdx @@ -24,6 +24,7 @@ Seid uses the following TCP ports. Toggle their settings to match your environme - `8545`: The default port for EVM HTTP RPC. This port is used for Ethereum JSON-RPC calls and must be open if you want to interact with EVM-compatible applications. - `8546`: The default port for EVM WebSocket RPC. This port provides real-time communication for EVM applications that require WebSocket connections. - `26660`: The default port for interacting with the Prometheus database, which can be used to monitor the environment. In the default configuration, this port is not open. +- `8545`: Also the default listen address (`127.0.0.1:8545`) for the `frozen-rpc-router` binary, which proxies EVM JSON-RPC requests to a live node and one or more freeze-height-frozen nodes based on block number. It shares the standard EVM JSON-RPC port convention with the live node. These ports are all customizable in `$HOME/.sei/config/config.toml` and `$HOME/.sei/config/app.toml`. diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index ee659c8..6a5baa1 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -67,6 +67,43 @@ freeze-height = 0 + +### Frozen RPC Router + +The `frozen-rpc-router` binary is a companion to freeze mode. It exposes a single HTTP EVM JSON-RPC endpoint that transparently proxies requests to a live node and one or more freeze-height-frozen nodes, routing each request to the correct backend based on the block height it references. This lets a set of archival nodes — each frozen before a different height — collectively serve historical state through one endpoint. + +Because a freeze height is an exclusive boundary, a node started with `--freeze-height 100` serves blocks through height 99. The router therefore sends height 99 to that node and height 100 to the next configured interval (or to the live node when no frozen interval covers it). + +```bash +# Route between a live node and two frozen nodes +go run ./cmd/frozen-rpc-router \ + --listen-address 0.0.0.0:8545 \ + --live-node localhost:9545 \ + --frozen-node 1000000=localhost:9546 \ + --frozen-node 2000000=10.0.0.12:8545 +``` + +The binary accepts the following flags: + +- `--listen-address` — address on which the router listens (default `127.0.0.1:8545`). +- `--live-node` — HTTP RPC address of the live node (required). +- `--frozen-node` — a `freeze-height=ip:port` pair; repeat once per frozen node. Bare `ip:port`, `http://`, and `https://` URLs are all accepted. Frozen nodes may be listed in any order, but freeze heights must be unique. +- `--max-request-body-bytes` — maximum JSON-RPC request body size (default 5MiB); larger requests are rejected with HTTP `413`. +- `--shutdown-timeout` — graceful shutdown timeout (default `10s`). + +#### Routing Rules + +- Methods with an explicit numeric block parameter (for example `eth_getBlockByNumber`, `eth_getBalance`, `eth_call`, `eth_getStorageAt`, `debug_traceBlockByNumber`) are routed to the interval that contains that height. The `earliest` tag resolves to height 0. +- `eth_getLogs` and `eth_feeHistory` are routed only when their entire explicit block range falls within a single interval. A range that crosses an interval boundary is rejected with JSON-RPC error `-32000` (`block ranges spanning multiple frozen-node intervals are not supported`). +- Latest-style block tags (`latest`, `pending`, `safe`, `finalized`), requests referencing a block by hash, methods without a block parameter, stateful filter methods, subscriptions, and WebSocket connections are all forwarded to the live node. +- Batch requests are split so each call reaches its correct backend, then reassembled into a single response. + +#### Route Header + +Every HTTP response carries a `Sei-RPC-Route` header identifying which backend served it: `frozen:` for a request served by the frozen node at that freeze height, `live` for the live node, and `mixed` for a batch split across multiple backends. + + + ### seidb Tooling Commands The `seidb` binary provides low-level tooling for inspecting and maintaining a node's on-disk state. From c76347881291d0909127f7460e91cc8da38b8222 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:26:20 +0000 Subject: [PATCH 3/5] docs: The frozen-rpc-router command adds a new --max-block-reference-depth CLI flag (default 16) to bound nested block reference parsing depth. (sei-protocol/sei-chain#4034) --- node/technical-reference.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 6a5baa1..be1c569 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -89,6 +89,7 @@ The binary accepts the following flags: - `--live-node` — HTTP RPC address of the live node (required). - `--frozen-node` — a `freeze-height=ip:port` pair; repeat once per frozen node. Bare `ip:port`, `http://`, and `https://` URLs are all accepted. Frozen nodes may be listed in any order, but freeze heights must be unique. - `--max-request-body-bytes` — maximum JSON-RPC request body size (default 5MiB); larger requests are rejected with HTTP `413`. +- `--max-block-reference-depth` — maximum nested block reference depth (default `16`); bounds how deeply nested `blockNumber` object references are parsed when resolving a request's block parameter. Must be positive. - `--shutdown-timeout` — graceful shutdown timeout (default `10s`). #### Routing Rules From b4f934dc2d30f5e0822c86526d0c97041a56a088 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:26:58 +0000 Subject: [PATCH 4/5] docs: The frozen-rpc-router adds two new CLI flags, --batch-request-limit and --write-timeout, to configure JSON-RPC batch size limits and HTTP response write timeouts. (sei-protocol/sei-chain#4048) --- node/technical-reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index be1c569..47645ee 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -90,6 +90,8 @@ The binary accepts the following flags: - `--frozen-node` — a `freeze-height=ip:port` pair; repeat once per frozen node. Bare `ip:port`, `http://`, and `https://` URLs are all accepted. Frozen nodes may be listed in any order, but freeze heights must be unique. - `--max-request-body-bytes` — maximum JSON-RPC request body size (default 5MiB); larger requests are rejected with HTTP `413`. - `--max-block-reference-depth` — maximum nested block reference depth (default `16`); bounds how deeply nested `blockNumber` object references are parsed when resolving a request's block parameter. Must be positive. +- `--batch-request-limit` — maximum number of calls in a JSON-RPC batch (default `1000`). Must be positive. A batch exceeding this limit is rejected with JSON-RPC error `-32600` (`batch too large`). +- `--write-timeout` — maximum duration for writing an HTTP response (default `30s`). Must be positive. - `--shutdown-timeout` — graceful shutdown timeout (default `10s`). #### Routing Rules From 3bbe23966003c8eb2e00eab4a9947dc2e3e7f632 Mon Sep 17 00:00:00 2001 From: alexander-sei Date: Sat, 5 Sep 2026 15:41:33 +0200 Subject: [PATCH 5/5] docs(node): address seidroid review on v6.6.3 catch-up 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 --- node/node-types.mdx | 3 +- node/technical-reference.mdx | 61 +++++++++++++++++++++++------------- 2 files changed, 41 insertions(+), 23 deletions(-) diff --git a/node/node-types.mdx b/node/node-types.mdx index 6a82444..ff75d7a 100644 --- a/node/node-types.mdx +++ b/node/node-types.mdx @@ -21,10 +21,9 @@ Seid uses the following TCP ports. Toggle their settings to match your environme - `26657`: The default port for the RPC interface. Because this port is used for querying and sending transactions, it must be open for serving queries from `seid`. - `1317`: The default port for interacting with the Seid API server for HTTP RESTful requests. This allows applications and services to interact with the `seid` instance through RPC. - `9090`: The default port for gRPC communication. This is used for high-performance communication with the node. -- `8545`: The default port for EVM HTTP RPC. This port is used for Ethereum JSON-RPC calls and must be open if you want to interact with EVM-compatible applications. +- `8545`: The default port for EVM HTTP RPC. This port is used for Ethereum JSON-RPC calls and must be open if you want to interact with EVM-compatible applications. The [`frozen-rpc-router`](/node/technical-reference#frozen-rpc-router) binary also listens on `127.0.0.1:8545` by default, so when you run the router on the same host as a live node, move one of them to a different port. - `8546`: The default port for EVM WebSocket RPC. This port provides real-time communication for EVM applications that require WebSocket connections. - `26660`: The default port for interacting with the Prometheus database, which can be used to monitor the environment. In the default configuration, this port is not open. -- `8545`: Also the default listen address (`127.0.0.1:8545`) for the `frozen-rpc-router` binary, which proxies EVM JSON-RPC requests to a live node and one or more freeze-height-frozen nodes based on block number. It shares the standard EVM JSON-RPC port convention with the live node. These ports are all customizable in `$HOME/.sei/config/config.toml` and `$HOME/.sei/config/app.toml`. diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 87af15d..fe04dec 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -37,10 +37,9 @@ seid tendermint show-validator seid query node info ``` +#### Freeze mode (`--freeze-height`) -#### Freeze Mode (`--freeze-height`) - -The `--freeze-height` start flag (and the corresponding `freeze-height` field in `app.toml`) puts a full node into read-only freeze mode at a specified block height. Query RPC remains available so the node can continue serving reads, but write and network paths are disabled from startup: +As of v6.6.3, the `--freeze-height` start flag (and the corresponding `freeze-height` field in `app.toml`) puts a full node into read-only freeze mode at a specified block height. Query RPC remains available so the node can continue serving reads, but write and network paths are disabled from startup: - Transaction and evidence submission is rejected. The `BroadcastTx`, `BroadcastTxAsync`, `BroadcastTxSync`, `BroadcastTxCommit`, and `BroadcastEvidence` RPC calls all return `ErrReadOnly` (`RPC writes are disabled in freeze mode`). - Mempool gossip is disabled — the mempool reactor is not started and the mempool p2p channel is not advertised to peers. @@ -53,12 +52,10 @@ Block sync and consensus stop before executing the configured height and will no seid start --freeze-height ``` -The same behavior can be configured persistently via the `freeze-height` field. `freeze-height` is the first block height a full node must not execute; a value of `0` disables freeze mode. +The same behavior can be configured persistently via the `freeze-height` field. `freeze-height` is the first block height a full node must not execute; a value of `0` disables freeze mode. The key is a top-level entry in `app.toml`, in the base configuration next to `halt-height`, and does not belong under any `[section]` header. See the generated [default `app.toml`](/node/node-operators#default-configurations) for the field in context. ```toml -# The first block height a full node must not execute. Query RPC remains available, -# while transaction and evidence submission, mempool gossip, and state sync are -# disabled from startup. Set to 0 to disable freeze mode. +# app.toml — top-level key in the base configuration (next to halt-height), not under any [section] freeze-height = 0 ``` @@ -66,46 +63,64 @@ freeze-height = 0 Freeze mode is only supported for full nodes. Setting a non-zero `freeze-height` in validator or seed mode is rejected at startup with an error (`freeze height is not supported in mode`). +### Frozen RPC router +The `frozen-rpc-router` binary, available as of v6.6.3, is a companion to freeze mode. It exposes a single HTTP EVM JSON-RPC endpoint that transparently proxies requests to a live node and one or more freeze-height-frozen nodes, routing each request to the correct backend based on the block height it references. This lets a set of archival nodes — each frozen before a different height — collectively serve historical state through one endpoint. -### Frozen RPC Router +Because a freeze height is an exclusive boundary, a node started with `--freeze-height 100` serves blocks through height 99. The router therefore sends height 99 to that node and height 100 to the next configured interval (or to the live node when no frozen interval covers it). -The `frozen-rpc-router` binary is a companion to freeze mode. It exposes a single HTTP EVM JSON-RPC endpoint that transparently proxies requests to a live node and one or more freeze-height-frozen nodes, routing each request to the correct backend based on the block height it references. This lets a set of archival nodes — each frozen before a different height — collectively serve historical state through one endpoint. +The router is a standalone binary in the `sei-chain` repository. It is not part of `seid` and is not installed by `make install`, so build it from a source checkout with the `build-frozen-rpc-router` target, which writes the binary to `./build/frozen-rpc-router`: -Because a freeze height is an exclusive boundary, a node started with `--freeze-height 100` serves blocks through height 99. The router therefore sends height 99 to that node and height 100 to the next configured interval (or to the live node when no frozen interval covers it). +```bash +git clone https://github.com/sei-protocol/sei-chain.git +cd sei-chain +git checkout # v6.6.3 or later +make build-frozen-rpc-router +``` ```bash -# Route between a live node and two frozen nodes -go run ./cmd/frozen-rpc-router \ - --listen-address 0.0.0.0:8545 \ +# Route between a live node and two frozen nodes. The router takes the default EVM +# HTTP RPC port (8545), so the live node and the frozen node that share this host +# have been moved to 9545 and 9546. The frozen node on 10.0.0.12 runs on its own +# host and keeps the default port. +./build/frozen-rpc-router \ + --listen-address 127.0.0.1:8545 \ --live-node localhost:9545 \ --frozen-node 1000000=localhost:9546 \ --frozen-node 2000000=10.0.0.12:8545 ``` + + The router has no authentication of its own: anyone who can reach its listen address can query every backend behind it. The example binds to `127.0.0.1` so that only local clients can connect. If you bind to a public interface (for example `--listen-address 0.0.0.0:8545`), put the router behind a firewall or reverse proxy, as you would for a node's own EVM RPC port. + + The binary accepts the following flags: - `--listen-address` — address on which the router listens (default `127.0.0.1:8545`). - `--live-node` — HTTP RPC address of the live node (required). -- `--frozen-node` — a `freeze-height=ip:port` pair; repeat once per frozen node. Bare `ip:port`, `http://`, and `https://` URLs are all accepted. Frozen nodes may be listed in any order, but freeze heights must be unique. -- `--max-request-body-bytes` — maximum JSON-RPC request body size (default 5MiB); larger requests are rejected with HTTP `413`. +- `--frozen-node` — a `freeze-height=ip:port` pair; repeat once per frozen node. Bare `ip:port`, `http://`, and `https://` URLs are all accepted. Frozen nodes may be listed in any order, but each freeze height must be positive and unique. +- `--max-request-body-bytes` — maximum JSON-RPC request body size in bytes (default `5242880`, which is 5 MiB); larger requests are rejected with HTTP `413`. - `--max-block-reference-depth` — maximum nested block reference depth (default `16`); bounds how deeply nested `blockNumber` object references are parsed when resolving a request's block parameter. Must be positive. - `--batch-request-limit` — maximum number of calls in a JSON-RPC batch (default `1000`). Must be positive. A batch exceeding this limit is rejected with JSON-RPC error `-32600` (`batch too large`). - `--write-timeout` — maximum duration for writing an HTTP response (default `30s`). Must be positive. - `--shutdown-timeout` — graceful shutdown timeout (default `10s`). -#### Routing Rules +#### Routing rules + +Only JSON-RPC `POST` requests are inspected and routed. Every other request, including WebSocket upgrade requests, is passed straight through to the `--live-node` address without inspection. Because that address is the live node's HTTP RPC endpoint, which does not accept WebSocket upgrades, clients that need subscriptions should connect directly to the live node's WebSocket port (`8546` by default) rather than through the router. -- Methods with an explicit numeric block parameter (for example `eth_getBlockByNumber`, `eth_getBalance`, `eth_call`, `eth_getStorageAt`, `debug_traceBlockByNumber`) are routed to the interval that contains that height. The `earliest` tag resolves to height 0. +- Methods that take an explicit block number or the `earliest` tag (for example `eth_getBlockByNumber`, `eth_getBalance`, `eth_call`, `eth_getStorageAt`, `debug_traceBlockByNumber`) are routed to the interval that contains that height. `earliest` resolves to height 0. - `eth_getLogs` and `eth_feeHistory` are routed only when their entire explicit block range falls within a single interval. A range that crosses an interval boundary is rejected with JSON-RPC error `-32000` (`block ranges spanning multiple frozen-node intervals are not supported`). -- Latest-style block tags (`latest`, `pending`, `safe`, `finalized`), requests referencing a block by hash, methods without a block parameter, stateful filter methods, subscriptions, and WebSocket connections are all forwarded to the live node. +- Latest-style block tags (`latest`, `pending`, `safe`, `finalized`), requests referencing a block by hash, methods without a block parameter, and stateful filter methods are all forwarded to the live node. - Batch requests are split so each call reaches its correct backend, then reassembled into a single response. -#### Route Header - -Every HTTP response carries a `Sei-RPC-Route` header identifying which backend served it: `frozen:` for a request served by the frozen node at that freeze height, `live` for the live node, and `mixed` for a batch split across multiple backends. + + Only `eth_*` and `debug_*` methods are height-routed. Block-scoped legacy `sei_*` and `sei2_*` methods (for example `sei_getBlockByNumber`, `sei_getBlockReceipts`, `sei_getLogs`) are not in the routing table and are always forwarded to the live node, even when they reference a height that only a frozen node still holds. This only affects nodes whose `enabled_legacy_sei_apis` list in `app.toml` has been widened beyond the three default helpers (`sei_getSeiAddress`, `sei_getEVMAddress`, `sei_getCosmosTx`). + +#### Route header +Responses proxied to a single backend carry a `Sei-RPC-Route` header identifying which backend served them: `frozen:` for the frozen node at that freeze height, or `live` for the live node. A batch split across multiple backends returns `mixed`. Errors generated by the router itself (oversized or malformed requests, batches over the limit, block ranges spanning intervals) and non-`POST` traffic passed through to the live node do not carry the header. ### seidb Tooling Commands @@ -302,6 +317,10 @@ The app.toml file controls application-specific settings: # Minimum gas prices for transaction acceptance minimum-gas-prices = "0.02usei" +# First block height a full node must not execute (read-only freeze mode). +# 0 disables freeze mode. Full nodes only; see "Freeze mode" above. +freeze-height = 0 + # API configuration [api] enable = true