docs: v6.6.3 catch-up

node/node-types.mdx

@@ -13,7 +13,7 @@
 
 - Validator Nodes provide security to the chain by proposing and signing blocks. To enable this type of node, set `mode=validator` in `config.toml`. Note that because Sei is proof-of-stake, you must have enough delegation to join the active set.
 
 ## Commonly Used Ports
 
 Seid uses the following TCP ports. Toggle their settings to match your environment.
 
@@ -21,13 +21,13 @@
 - `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. The linked example keeps the router on `8545` and moves the nodes to `9545` and `9546`.
 - `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.
 
 These ports are all customizable in `$HOME/.sei/config/config.toml` and `$HOME/.sei/config/app.toml`.
 
 ## Systemd File Template
 
 ```toml
 [Unit]

node/technical-reference.mdx

@@ -9,13 +9,13 @@
 troubleshooting procedures. For API documentation, please refer to our API
 Documentation section.
 
 ## Command Line Interface Reference
 
 The `seid` binary provides extensive functionality for managing your Sei node.
 Understanding these commands is essential for effective node operation and
 troubleshooting.
 
 ### Node Management Commands
 
 These commands help you control and monitor your node's operation:
 
@@ -37,7 +37,95 @@
 seid query node info
 ```
 
+#### Freeze mode (`--freeze-height`)
+
+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. Freeze mode exists for historical RPC nodes. A node frozen at an upgrade height keeps running the pre-upgrade binary and keeps serving the state that binary produced, instead of shutting down at the boundary or executing the upgrade block with code that no longer matches that state. 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`). The EVM endpoint submits transactions through the same path, so `eth_sendRawTransaction` fails with the same error.
+- Mempool gossip is disabled — the mempool reactor is not started and the mempool p2p channel is not advertised to peers.
+- State sync is disabled. If it is enabled in `config.toml`, the node logs a notice and falls back to block sync.
+
+Block sync and consensus stop before executing the configured height and will not advance beyond it.
+
+The node must not have reached the freeze height yet. If the application, block store, or state store height is already at or above `freeze-height`, startup fails with `<source> height <n> has already reached freeze height <h>`. To build a frozen node, start from a data directory that is below the freeze height (a fresh sync from genesis, or a [snapshot](/node/snapshot) taken below that height) and let block sync stop at the boundary.
+
+```bash
+# Start a full node in read-only freeze mode at a given block height
+seid start --freeze-height <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 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
+# app.toml — top-level key in the base configuration (next to halt-height), not under any [section]
+freeze-height = 0
+```
+
+<Warning>
+  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> mode`). `freeze-height` also cannot be combined with `halt-height`, `halt-time`, or the `--grpc-only` start flag; each combination is rejected at startup.
+</Warning>
+
+### 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 at a different upgrade height and running the binary that was live for its interval — 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).
+
+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`:
+
+```bash
+git clone https://github.com/sei-protocol/sei-chain.git
+cd sei-chain
+git checkout <version-tag>  # v6.6.3 or later
+make build-frozen-rpc-router
+```
+
+```bash
+# 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
+```
+
+<Warning>
+  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.
+</Warning>
+
+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 `host:port` addresses and `http://` or `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
+
+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 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, 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.
+- Calls whose backend cannot be reached return JSON-RPC error `-32001` (`upstream request failed`).
+
+<Warning>
+  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`).
+</Warning>
+
+#### Route header
+
+Responses proxied to a single backend carry a `Sei-RPC-Route` header identifying which backend served them: `frozen:<height>` 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, unreachable backends) and non-`POST` traffic passed through to the live node do not carry the header.
+
 ### seidb Tooling Commands
 
 The `seidb` binary provides low-level tooling for inspecting and maintaining a node's on-disk state.
 
@@ -63,7 +151,7 @@
 - `version_at` — the FlatKV version that was read.
 - `migration_version` — the on-disk migration version (`0` means the FlatKV EVM migration has not yet completed).
 - `migrate_evm_complete` — `true` once the migration version has reached the FlatKV EVM (v1) target.
 - `boundary_present` — `true` while the migration is in flight (the in-progress resume cursor is still present).
 - `boundary_hex` — hex-encoded migration boundary cursor, included only when a boundary is present.
 - `version_raw_hex` — hex-encoded raw migration-version bytes, included only when a migration version is present.
 
@@ -103,7 +191,7 @@
 - `--key-prefix` — inspect mode: hex prefix, relative to `--key-offset`, used to filter physical keys.
 - `--shard-next-bytes` — inspect mode: group matching keys by this many bytes after `--key-prefix`.
 - `--list` — inspect mode: list matching key/logical-value pairs instead of shard `bucket_digest` values.
 - `--list-limit` — inspect mode: maximum pairs to print with `--list` (default `1000`; a value `<= 0` means unlimited).
 - `--details` — inspect list mode: include backend-specific version metadata.
 - `--find-hash` — optional 32-byte hex per-entry hash to hunt for. When two `bucket_digest` values differ by exactly one entry, their XOR is that entry's hash; this prints every matching entry so a single diverging row can be located.
 
@@ -134,7 +222,7 @@
 - `autobahn_address.txt` — the network address (`host:port`) the node advertises to peers.
 - `evmrpc_url.txt` — the node's EVM RPC URL, written into the validator's `evmrpc` field for cross-shard transaction proxying.
 
 The `validator_pubkey.txt` and `node_pubkey.txt` files are written automatically alongside `priv_validator_key.json` and `node_key.json` whenever those keys are saved, so they are typically already present in each node's config directory.
 
 The generated `autobahn.json` file describes the validator set along with transaction limits, block interval, view timeout, and dial interval; gas limits are not part of this file and come from the genesis block parameters instead. To have a node consume it, reference the file from `config.toml` using the `autobahn-config-file` key.
 
@@ -152,7 +240,7 @@
 - **Maximum transactions per block:** the lower of the configured `max_txs_per_block` and the built-in maximum of 2,000 (see the transaction payload caps below).
 - **Maximum total transaction bytes per block:** a fixed per-block byte cap; a single transaction larger than this cap is rejected with a `transaction too large` error.
 - **Wanted gas per block (`MaxGasWantedPerBlock`):** derived from the genesis `MaxGasWanted` block param. A transaction whose `GasWanted` exceeds this per-block limit is rejected as too large.
 - **Estimated gas per block (`MaxGasEstimatedPerBlock`):** derived from the genesis `MaxGas` block param. A transaction whose (normalized) estimated gas exceeds this per-block limit is rejected as too large.
 
 When filling a block the producer seals the current block and starts a new one as soon as adding the next transaction would exceed any of the transaction-count, byte, wanted-gas, or estimated-gas limits.
 
@@ -171,7 +259,7 @@
 
 Any message whose fields exceed these limits is rejected at decode time, so an oversized network payload never reaches the consensus logic.
 
 <Note>
   Because Giga replaces the CometBFT mempool, the `unsafe_flush_mempool` RPC endpoint is not supported under Giga and returns `unsafe_flush_mempool is not supported with autobahn mempool`.
 </Note>
 
@@ -196,7 +284,7 @@
 # Import key
 seid keys import <name> <keyfile>
 
 # Show key address
 seid keys show <name> -a
 ```
 
@@ -214,12 +302,12 @@
 # Withdraw rewards
 seid tx distribution withdraw-rewards <validator-addr> --from <delegator-key>
 
 # Edit validator
 seid tx staking edit-validator [flags] --from <validator-key>
 ```
 
 ## Configuration Parameters
 
 Understanding configuration parameters is essential for optimizing your node's
 performance and security.
 
@@ -232,6 +320,10 @@
 # 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
@@ -331,11 +423,11 @@
   Out-of-process ABCI support has been removed. The full node now runs only with Tendermint in-process; external stand-alone ABCI processes (socket or gRPC) are no longer supported. As a result:
 
   - The `seid start` flags `--address` and `--transport` are **deprecated and ignored**.
   - The Tendermint node flags `--proxy-app` and `--abci` are **deprecated and ignored**.
   - The `proxy-app` and `abci` fields in `config.toml` are **deprecated and ignored**, and are no longer written to newly generated `config.toml` files. Node operators upgrading should delete these lines from their `config.toml` if present.
 </Warning>
 
 ## Network Parameters
 
 Understanding network parameters helps you operate your node effectively.
 
@@ -363,7 +455,7 @@
                                        slashing module's min_signed_per_window above)
 ```
 
 <Info>
   These values reflect the current on-chain parameters. Query them directly with `seid query staking params` and `seid query slashing params` for the source of truth. Per-validator settings (e.g. commission rate, commission max change rate) are configured per validator and are not chain-level parameters.
 </Info>