Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion skill/references/cli/seid-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ seid version
```

Requirements:
- Go 1.24.x required. Run `go version` to confirm.
- Go 1.25.6 or later. The `go` line in `go.mod` at the tag you check out is authoritative; it has been `1.25.6` since v6.4.0. Run `go version` to confirm.
- If `seid` is not found after install: run `go env GOPATH` and ensure `$GOPATH/bin` is on `PATH`.

## Node Initialization
Expand Down Expand Up @@ -256,6 +256,8 @@ Constraints:
- The target height must not be below the chain's initial height, and the application, block store, and state store must not have reached it yet — otherwise the node refuses to start.
- Auto-remediation restart halts at the freeze boundary rather than restarting past it.

Run v6.6.4+ or v6.7.2+. On v6.6.3 and v6.7.0–v6.7.1 a frozen node's EVM JSON-RPC does not come back after the process restarts, because the EVM servers waited for a processed block ([sei-chain#4448](https://github.com/sei-protocol/sei-chain/pull/4448), [#4447](https://github.com/sei-protocol/sei-chain/pull/4447)). A frozen node runs the latest patch of the release that its upgrade replaced: v6.6.4 for the v6.7 upgrade, `--freeze-height 236450000` on mainnet and `273966500` on testnet. See "Which release a frozen node runs" in [node operations](../ecosystem/node-operations.md).

The freeze height is an *exclusive* boundary: a node started with `--freeze-height 100` serves blocks through height 99 and never executes block 100. This is the interval semantics the `frozen-rpc-router` relies on when routing requests by block number (see [Frozen RPC Router](frozen-rpc-router.md)).

Example — freeze a node just before executing block 5,000,000 while continuing to serve RPC (the node serves blocks through height 4,999,999):
Expand All @@ -264,6 +266,19 @@ Example — freeze a node just before executing block 5,000,000 while continuing
seid start --freeze-height 5000000
```

## Rollback (`seid rollback`)

Stop the node first. `seid rollback` rolls the application and Tendermint state back so the node re-fetches and re-executes the removed blocks on restart. It is the usual first step for `wrong Block.Header.AppHash`.

```bash
seid rollback [--num-blocks <n>] [--home <dir>]
```

- `--num-blocks` / `-n` (default `1`): how many heights to roll back when the application and Tendermint are at the same height. If their heights differ, rollback only brings the one that is ahead down to the other's height.
- **FlatKV retention floor (v6.7.1+, [sei-chain#4496](https://github.com/sei-protocol/sei-chain/pull/4496)):** on a node whose FlatKV store is open (the EVM storage migration has started, or a FlatKV write mode is pinned), rollback first checks that FlatKV can rebuild the target height from its retained snapshots and WAL. If it cannot, it refuses before changing anything: `flatkv cannot roll back to version <N>: version unreachable: ...; use state sync instead`. State sync is then the only way back.

`seid export` was **removed in v6.7.1** ([sei-chain#4478](https://github.com/sei-protocol/sei-chain/pull/4478)). There is no supported way to dump live state to a genesis file; recover with `seid rollback`, state sync, or a snapshot. `seid init`, `seid collect-gentxs`, and starting a chain from a genesis file are unchanged.

## curl and JSON-RPC

Use `curl` when the user wants raw EVM RPC access, debug methods, or JSON-RPC examples. Use `seid` for everything else.
Expand Down
13 changes: 8 additions & 5 deletions skill/references/contracts/common-errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ STAKING.delegate{value: 1 ether}(validatorAddr);
**Fix**:
1. Stop node: `systemctl stop seid`
2. Try rollback: `seid rollback`, then restart
3. If rollback fails: wipe data and state sync from scratch (back up validator keys first)
3. If rollback fails: wipe data and state sync from scratch (back up validator keys first). Since v6.7.1, a node with an open FlatKV store refuses a rollback below the history FlatKV retains, with `flatkv cannot roll back to version <N>: ...; use state sync instead`.

### `Consensus failure - height halted`
**Cause**: Network upgrade required at this height.
Expand All @@ -136,8 +136,11 @@ STAKING.delegate{value: 1 ether}(validatorAddr);
**Cause**: Node has no P2P connections, can't sync.
**Fix**:
```bash
# Check peer count
curl http://localhost:26657/net_info | jq '.result.n_peers'
# Connected peer count (n_peers counts live connections since v6.7.2)
curl -s http://localhost:26657/net_info | jq -r '.result.n_peers'
# Before v6.7.2, n_peers counted every known address (~175-200 on pacific-1),
# not connections. This works on every version:
curl -s http://localhost:26657/net_info | jq '.result.peer_connections | length'
# Update persistent peers in config.toml
# Verify port 26656 is open in firewall
```
Expand Down Expand Up @@ -223,8 +226,8 @@ seid status | jq .SyncInfo.catching_up
# Validator signing info
seid q slashing signing-info $(seid tendermint show-validator) --node https://rpc.sei-apis.com

# Peer count
curl -s http://localhost:26657/net_info | jq '.result.n_peers'
# Connected peer count (v6.7.2+; on older binaries use '.result.peer_connections | length')
curl -s http://localhost:26657/net_info | jq -r '.result.n_peers'

# Current block height
curl -s http://localhost:26657/status | jq '.result.sync_info.latest_block_height'
Expand Down
27 changes: 26 additions & 1 deletion skill/references/ecosystem/node-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ description: Running and maintaining Sei full nodes — node types, setup, state

- Ubuntu 22.04 (recommended) or macOS
- 16+ CPU cores, 256 GB DDR5 RAM, 2 TB NVMe SSD
- Go 1.24.x installed (required for seid v6.3+)
- Go 1.25.6 or later installed (the `go.mod` at the release tag is authoritative)

### Build from Source

Expand Down Expand Up @@ -94,6 +94,12 @@ State sync peers:
- **Mainnet (pacific-1)**: `https://rpc.sei-apis.com:443` or `https://sei-rpc.polkachu.com:443`
- **Testnet (atlantic-2)**: `https://rpc-testnet.sei-apis.com:443`

### Trust period (built into `seid` since v6.7.3)

The trust height must be younger than the chain's state sync trust period. Since v6.7.3 ([sei-chain#4679](https://github.com/sei-protocol/sei-chain/pull/4679)) that period is built into the binary per chain ID: **112h** on `pacific-1`, `atlantic-2`, and `arctic-1`, and 168h on any other chain. An older trust height fails with `old header has expired at ...`. The script above picks the last 100,000-block boundary, which is well under a day old.

`trust-period` is no longer in the `config.toml` template, and a value left under `[statesync]` is ignored. When it differs from the built-in period, `seid start` warns `statesync.trust-period is set in config.toml, but state sync uses the trust period built into seid for this chain; the setting is ignored and can be removed`. Most nodes created from the old template (`trust-period = "168h0m0s"`) log this on every start, whether or not state sync is enabled. Delete the line.

---

## Directory Structure
Expand Down Expand Up @@ -179,6 +185,8 @@ SeiDB has two layers: **State Commit (SC)** — a memiavl Merkle tree that holds
```

The migration is staged: `migrate_evm` drains EVM data in the background and settles at `evm_migrated`; later modes migrate the remaining modules.

Since v6.7.1 ([sei-chain#4484](https://github.com/sei-protocol/sei-chain/pull/4484)), a pin to `evm_migrated`, `all_migrated_but_bank`, or `flatkv_only` is checked against the migration state persisted in FlatKV whenever the store loads, and when `seid rollback` finishes. If they disagree, typically after rolling back below the height where a migration finished, the node refuses to start with an error containing `write mode is pinned to "<pin>" but the persisted migration state is "<mode>"; set state-commit.sc-write-mode-enable-auto = true to follow the migration`. Set `sc-write-mode-enable-auto = true` (or delete the line, since `true` is the default); reopening in `auto` reconciles the backends to the rolled-back height. A store whose history began in FlatKV carries no migration metadata and passes the check for any pin.
- **Giga Executor** (`[giga_executor] enabled`) is a *separate* feature — an evmone-based EVM interpreter for throughput. Don't conflate it with Giga Storage.

> Minimum gas price, block gas limit, and SSTORE/storage gas are governance-adjustable — confirm live values at https://docs.sei.io/evm/differences-with-ethereum, and set `minimum-gas-prices` at or above the mainnet floor (`0usei` is local-dev only).
Expand Down Expand Up @@ -352,6 +360,23 @@ To serve historical EVM JSON-RPC from frozen nodes behind one endpoint, put [fro
- Must **not exceed `MaxInt64`** (`9223372036854775807`).
- Must be **at or above the genesis initial height** and **above the current application, block store, and state store heights** — you cannot freeze at a height the node has already reached or passed.

### Which release a frozen node runs

A frozen node serves history from before a breaking upgrade: set `freeze-height` to the upgrade height and run the **latest patch of the release that upgrade replaced**. Never upgrade it to the release its freeze height introduces; a later patch of the same line (v6.6.4 over v6.6.3) is fine. For the v6.7 upgrade:

| Network | `freeze-height` (v6.7 upgrade height) | Last height served | Frozen node release |
|---|---|---|---|
| Mainnet (`pacific-1`) | `236450000` | `236449999` | v6.6.4 |
| Testnet (`atlantic-2`) | `273966500` | `273966499` | v6.6.4 |

Each later upgrade adds one more frozen node. Read an upgrade's height from the chain (testnet: `https://rest-testnet.sei-apis.com`):

```bash
curl -s https://rest.sei-apis.com/cosmos/upgrade/v1beta1/applied_plan/v6.7 | jq -r .height # 236450000
```

**Use v6.6.4 or later, not v6.6.3.** A frozen node never processes another block, and on v6.6.3 (and v6.7.0–v6.7.1) the EVM HTTP and WebSocket servers only started once a block was processed, so after any restart EVM JSON-RPC stayed down while Tendermint RPC kept working. v6.6.4 ([sei-chain#4448](https://github.com/sei-protocol/sei-chain/pull/4448)) and v6.7.2 ([sei-chain#4447](https://github.com/sei-protocol/sei-chain/pull/4447)) initialize the app from the last stored block header at startup, so EVM RPC comes back after a restart, and a frozen node that is still catching up serves it from startup. After setting one up, restart it once and check that `eth_blockNumber` still answers. Full walkthrough: [docs.sei.io/node/frozen-nodes](https://docs.sei.io/node/frozen-nodes).

---

## Database Management
Expand Down
2 changes: 1 addition & 1 deletion skill/references/ecosystem/staking-governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ seid q params subspace migration NumKeysToMigratePerBlock --output json \

**Operator notes:**
- A node only follows the governance-driven migration when running in **auto** write mode. As of v6.7.0, `state-commit.sc-write-mode-enable-auto` defaults to `true` (it is not written into `app.toml` unless you add it), which forces auto and ignores any explicit `sc-write-mode`. In auto the effective mode comes from the on-disk migration state, advanced by `NumKeysToMigratePerBlock`, so no `app.toml` edit is needed when governance starts the migration.
- To pin an explicit `sc-write-mode` (e.g. `memiavl_only`, `flatkv_only`, `evm_migrated`) you must also set `sc-write-mode-enable-auto = false`; only then is `sc-write-mode` honored. A pinned node does not take part in the governance-driven migration and diverges from the network once the chain migrates.
- To pin an explicit `sc-write-mode` (e.g. `memiavl_only`, `flatkv_only`, `evm_migrated`) you must also set `sc-write-mode-enable-auto = false`; only then is `sc-write-mode` honored. A pinned node does not take part in the governance-driven migration and diverges from the network once the chain migrates. Since v6.7.1, a node pinned to `evm_migrated`, `all_migrated_but_bank`, or `flatkv_only` also refuses to start when the pin disagrees with the migration state on disk (the error contains `write mode is pinned to`); re-enable auto mode to recover. See [node-operations.md](node-operations.md).

### Software Upgrade Proposal

Expand Down
2 changes: 2 additions & 0 deletions skill/references/ecosystem/validators.md
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,8 @@ Key metrics to monitor:
| `tendermint_p2p_peers` | < 5 peers |
| `process_resident_memory_bytes` | > 80% available RAM |

`tendermint_p2p_peers` counts live connections. Since v6.7.2 ([sei-chain#4514](https://github.com/sei-protocol/sei-chain/pull/4514)) seid also exports `tendermint_p2p_known_addresses`: every distinct peer with a known address, connected or learned via PEX. It is useful for watching address-book growth, but it is not a connection count, so don't alert on it like `tendermint_p2p_peers`. The `/net_info` RPC made the same split in v6.7.2 ([sei-chain#4500](https://github.com/sei-protocol/sei-chain/pull/4500)): `n_peers` now counts connected peers, while `peers` still lists every known address.

### Grafana Dashboard

Import the community Sei validator Grafana dashboard (search "Sei Validator" on grafana.com) and point it to your Prometheus endpoint.
Expand Down
Loading