Skip to content
Open
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
2 changes: 1 addition & 1 deletion STYLE_GUIDE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Sei Docs Style Guide

Check warning on line 1 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L1

Use sentence case for headings: 'Sei Docs Style Guide'.

This style guide contains general rules and principles to ensure the documentation is cohesive, useful, and organized.

Expand All @@ -6,7 +6,7 @@

This documentation strives to be:

### Beginner Friendly

Check warning on line 9 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L9

Use sentence case for headings: 'Beginner Friendly'.

The Sei community welcomes members from all walks of life. As such, the documentation should be understandable by anyone, including those who are new to Web3 or non-technical.

Expand All @@ -22,8 +22,8 @@

- To be clear and inclusive, avoid using jargon and obscure words where possible.
- Limit the number of clauses in a sentence and make sure that your points are structured.
- Avoid qualifying language, which is ~~quite~~ often ~~completely~~ unnecessary.

Check warning on line 25 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L25

'quite' is often unnecessary qualifying language — consider removing it.

Check warning on line 25 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L25

'completely' is often unnecessary qualifying language — consider removing it.
- Information should be simply organized and easy to find.

Check warning on line 26 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L26

'simply' is often unnecessary qualifying language — consider removing it.

### Self-explanatory

Expand Down Expand Up @@ -76,30 +76,30 @@
- If a TypeScript example uses top-level `await`, tell readers to run it as a `.mts` file with `npx tsx`. In a new npm project, `tsx` compiles a plain `.ts` file as CommonJS, where top-level `await` fails.
- End with a "You are done when you see" block that shows the expected output.

### Cosmos-SDK (Deprecated)

Check warning on line 79 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L79

Use sentence case for headings: 'Cosmos-SDK (Deprecated)'.

> ⚠️ **Deprecation Notice**: Cosmos SDK and CosmWasm functionality is being deprecated in favor of EVM-only. For more details, see [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md) and [Proposal 99](https://seistream.app/proposals/99).

The Learn tab lists the single deprecation page, `cosmos-sdk/index.mdx`, in the Governance group after the SIPs page. New development should focus on the EVM.

### Operate (Node)

Check warning on line 85 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L85

Use sentence case for headings: 'Operate (Node)'.

The Operate section covers topics related to running Sei infrastructure. This is relevant for node operators, validators, and those looking to contribute to chain infrastructure.

**Contents include:**

- **Node Operations**: Overview, Seictl setup, statesync, snapshot sync, node types, troubleshooting, API configuration, validators, oracle price feeder
- **Advanced Operations**: Configuration & monitoring, Giga SS Store migration, frozen nodes, technical reference
- **Advanced Operations**: Configuration & monitoring, Giga SS Store migration, frozen nodes, ingress nodes, technical reference

## Style Guidelines

Check warning on line 94 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L94

Use sentence case for headings: 'Style Guidelines'.

### Acronyms and Abbreviations

Check warning on line 96 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L96

Use sentence case for headings: 'Acronyms and Abbreviations'.

To maximize clarity, we should avoid acronyms and abbreviations where possible, especially for shorter, more ambiguous acronyms:

- Just use 'CosmWasm' instead of 'CW'

However, there are occasions where acronyms might be more easily understandable (e.g., NFT instead of Non-Fungible Token, RPC instead of Remote Procedure Call), or referred to very frequently.

Check warning on line 102 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L102

'very' is often unnecessary qualifying language — consider removing it.

In these cases, we should first use the spelled-out term followed by the shortened form in parentheses:

Expand Down Expand Up @@ -264,7 +264,7 @@
</Frame>
```

### Callouts and Admonitions

Check warning on line 267 in STYLE_GUIDE.md

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

STYLE_GUIDE.md#L267

Use sentence case for headings: 'Callouts and Admonitions'.

Use callouts to highlight important information. Mintlify supports the following callout types:

Expand Down
1 change: 1 addition & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,7 @@
"node/advanced-config-monitoring",
"node/giga-storage-migration",
"node/frozen-nodes",
"node/ingress-nodes",
"node/technical-reference"
]
}
Expand Down
3 changes: 3 additions & 0 deletions node/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@
timedatectl
```

##### Install Go

Check warning on line 64 in node/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/index.mdx#L64

Use sentence case for headings: 'Install Go'.

You need Go only if you build `seid` from source. The prebuilt binary and Docker
install paths in the next step do not require it.
Expand Down Expand Up @@ -293,7 +293,7 @@

**2. Configure archive node peers**: To sync from the height at which your snapshot was created, you need peers that keep many historical blocks. During the initial sync, the node needs these specific peers. You can change them later.

#### Mempool configuration

Check warning on line 296 in node/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/index.mdx#L296

Use sentence case for headings: 'Mempool configuration'.

For optimal transaction handling and resource management, update the mempool settings in your `config.toml` file.

Expand Down Expand Up @@ -451,6 +451,9 @@
<Card horizontal title="Frozen nodes" icon="snowflake" href="/node/frozen-nodes">
Serve history from before an upgrade with a read-only node on the outgoing release.
</Card>
<Card horizontal title="Ingress nodes" icon="right-to-bracket" href="/node/ingress-nodes">
Serve EVM transaction submission and WebSocket traffic from a low-footprint full node.
</Card>
<Card horizontal title="Technical reference" icon="terminal" href="/node/technical-reference">
Detailed technical specifications, API endpoints, and commands for node operators.
</Card>
Expand Down
197 changes: 197 additions & 0 deletions node/ingress-nodes.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
---
title: 'Run ingress nodes for transaction submission'
sidebarTitle: 'Ingress Nodes'
description: 'Run a low-footprint seid full node for EVM transaction submission and WebSocket subscriptions, for example next to high-frequency trading systems.'
keywords: ['sei node', 'ingress node', 'ingress mode', 'ingress-only node', 'seid start --ingress', 'transaction submission', 'high-frequency trading', 'HFT', 'market maker', 'EVM RPC', 'WebSocket', 'low footprint', 'state sync']
---

An ingress node is a full node that runs with a small memory and disk footprint. It serves EVM JSON-RPC and WebSocket traffic for the most recent 1000 blocks, which covers transaction submission and live subscriptions. The name comes from transaction ingress, the point where your transactions enter the network.

Run an ingress node when you want your own endpoint for transaction submission and need less memory and disk than a full RPC node uses. For example, a high-frequency trading (HFT) operator can run one next to its trading systems in each region where it trades.

<Warning>
No tagged `seid` release includes ingress mode yet. A release without it refuses to start with `--ingress` and reports `unknown flag: --ingress`. The same release ignores `ingress = true` in `app.toml` and starts a regular full node. Check the [`sei-chain` release notes](https://github.com/sei-protocol/sei-chain/releases) for the first release that includes ingress mode.
</Warning>

## How ingress mode works

You turn on ingress mode with `seid start --ingress`. At startup, `seid` overrides a fixed set of settings in `app.toml` and `config.toml`. The node still executes every block and computes the same app hash as any other full node. P2P networking and the mempool work as on any full node, so the node gossips the transactions that you submit to its peers.

An ingress node serves:

- EVM JSON-RPC over HTTP on port `8545` and over WebSocket on port `8546`. Ingress mode turns on both servers.
- The Tendermint RPC on port `26657`, without transaction queries.
- State and EVM transaction receipts for the last 1000 blocks.

Ingress mode turns off:

- The REST API on port `1317`.
- The transaction index. The Tendermint RPC methods `tx`, `tx_search`, `block_search`, and `broadcast_tx_commit` return errors.
- Snapshot production for state sync. Other nodes cannot state sync from an ingress node.
- Gas simulation in `eth_sendRawTransaction`. The node broadcasts each transaction without simulating it first.
- State-store snapshots, state proofs, trace baking, and the supply invariant check.

Ingress mode also keeps only the latest memIAVL snapshot and writes memIAVL snapshot trees one at a time. It shrinks the FlatKV caches and memtables too. For every setting that it changes, see [Settings that ingress mode overrides](#settings-that-ingress-mode-overrides).

### History on an ingress node

The node keeps state and receipts for the last 1000 blocks. It keeps blocks for longer. The node does not prune blocks inside the evidence window, so it keeps at least as many blocks as the `max_age_num_blocks` evidence parameter. To read the parameter, run:

```bash
curl -s http://localhost:26657/consensus_params | jq -r .consensus_params.evidence.max_age_num_blocks
```

A request that needs state or receipts from an older height fails. The error names the earliest height that the node still serves. Send these requests to a full RPC node, an [archive node](/node/node-types), or an [RPC provider](/learn/rpc-providers). This applies to `eth_getLogs` backfills, `debug_trace*` calls on older transactions, and indexers that read history.

## Before you begin

You need:

- A `seid` release that includes ingress mode.
- A node in `full` mode. Ingress mode refuses validator and seed mode. It also refuses to start with Autobahn enabled, that is, with a non-empty `autobahn-config-file` in `config.toml`. You cannot combine ingress mode with a non-zero `freeze-height`.
- An empty data directory. State sync runs only on a node without local state. To reuse a host, first follow [Clean up](/node/statesync#clean-up) in the state sync guide.
- A host sized for your workload. An ingress node needs less memory and disk than the full node [hardware requirements](/node#hardware-requirements). Its disk use still grows with the current state of the network and with the blocks in the evidence window. Measure a test node under your workload before you size production hosts.

## Set up an ingress node

These steps set up an ingress node on Sei Mainnet (`pacific-1`). For Sei Testnet, use the chain ID `atlantic-2`.

<Steps>

<Step title="Install and initialize the node">

Install a `seid` release that includes ingress mode. The [node setup guide](/node) covers the prebuilt binary, a build from source, and Docker.

Initialize the node without `--mode`. The default mode is `full`, which ingress mode requires.

```bash
seid init <your-moniker> --chain-id pacific-1
```

</Step>

<Step title="Configure state sync">

Configure state sync with the script in [Statesync script](/node/statesync#statesync-script). Do not start `seid` at the end of that guide. You start it in ingress mode in the next steps.

</Step>

<Step title="Turn on ingress mode">

Create a systemd service that starts `seid` with the `--ingress` flag. Run these commands as the user that runs `seid`:

```bash
sudo tee /etc/systemd/system/seid.service > /dev/null << EOF
[Unit]
Description=Sei ingress node
After=network-online.target

[Service]
User=$USER
ExecStart=$(which seid) start --ingress
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable seid
```

Instead of the flag, you can set `ingress = true` in `app.toml`. Put the key in the base configuration at the top of the file, before the first `[section]` header:

```toml app.toml
# Run this full node in ingress mode.
ingress = true
```

<Tip>
Prefer the flag. A `seid` release without ingress mode refuses to start with the flag, so you notice the problem at once. The same release ignores the `app.toml` key and starts a regular full node.
</Tip>

</Step>

<Step title="Start the node">

Start `seid` and follow the log:

```bash
sudo systemctl start seid
sudo journalctl -fu seid
```

The node restores a state sync snapshot and then follows the chain. If it exits right after it starts, look for one of these errors in the log:

- `--ingress requires Tendermint mode "full"`: set `mode = "full"` in `config.toml`.
- `--ingress is not supported with Autobahn`: leave `autobahn-config-file` empty in `config.toml`.
- `--ingress cannot be combined with --freeze-height`: set `freeze-height = 0` in `app.toml`, and do not pass the `--freeze-height` flag.

</Step>

<Step title="Verify the ingress node">

Check that the node has caught up and that the EVM RPC answers. The first command prints `false` after the node has caught up:

```bash
curl -s http://localhost:26657/status | jq -r .sync_info.catching_up
# false

curl -s -X POST http://localhost:8545 -H 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'
# {"jsonrpc":"2.0","id":1,"result":"0x531"}
```

`0x531` is the Sei Mainnet EVM chain ID, `1329`. On Sei Testnet, the result is `0x530`.

Then check the ports that the node listens on:

```bash
ss -ltn | grep -E ':(1317|8545|8546) '
```

The output lists ports `8545` and `8546`, and it has no line for port `1317`. `seid init` turns on the REST API in `app.toml`, so a regular full node listens on port `1317`. If the output lists that port, the node did not start in ingress mode. Check that your `seid` release includes ingress mode and that the service passes `--ingress`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[suggestion] ss -ltn lists listeners for the whole host, so an unrelated service on 1317 would make this check misreport that ingress mode is off. The check also assumes the default EVM ports. Consider sudo ss -ltnp | grep seid to limit the output to seid's own listeners. You could also note that operators with custom ports should check the [evm] and [api] addresses they configured. (Raised by Codex.)


</Step>

</Steps>

## Use ingress nodes for high-frequency trading

Latency-sensitive operators, such as market makers and HFT firms, often want their own transaction submission and WebSocket endpoints in each region where they trade. Ingress mode lowers the memory and disk that each of these nodes needs. When you plan such a setup, follow these guidelines:

- **Run each node near the systems that use it.** Put an ingress node in the same region or data center as the systems that submit transactions through it. Their requests then do not cross regions.
- **Submit and subscribe on your own node.** Send signed transactions with `eth_sendRawTransaction`. Subscribe to `newHeads` and `logs` with `eth_subscribe` on port `8546`. For client examples, see [WebSocket connections](/evm/evm-parity/websocket).
- **Set gas limits close to what your transactions use.** An ingress node does not simulate a transaction before it broadcasts it, so it reports the gas limit as the estimated gas. Block proposers count each EVM transaction at its estimated gas when they fill a block. A gas limit far above actual use takes up more of the block's gas budget than the transaction needs.
- **Keep the node well connected.** The node gossips your transactions to its peers through the mempool, like any full node. It does not send them to validators directly, and it does not give them priority. Keep `broadcast = true` under `[mempool]` in `config.toml`, which is the default. To check the peer count, run `curl -s http://localhost:26657/net_info | jq -r .n_peers`.
- **Restrict access.** The EVM servers listen on all network interfaces. Allow only your own systems through the firewall to ports `8545`, `8546`, and `26657`. Keep port `26656` open for P2P.
- **Plan for restarts and upgrades.** Run at least two ingress nodes in each region, so that one serves traffic while the other restarts. An ingress node executes every block, so upgrade it at each upgrade height, like any full node. See [Update procedures](/node/node-operators#update-procedures).

Ingress mode does not add subscription types or earlier block signals. Its WebSocket subscriptions are the same as on any other full node.

## Settings that ingress mode overrides

Ingress mode sets these values at startup. While ingress mode is on, the values in your configuration files for these settings have no effect.

| File and section | Setting | Value in ingress mode |
| --- | --- | --- |
| `app.toml`, base configuration | `min-retain-blocks` | `1000` |
| `app.toml`, `[state-sync]` | `snapshot-interval` | `0` |
| `app.toml`, `[state-commit]` | `sc-enable-state-proof` | `false` |
| `app.toml`, `[state-commit]` | `sc-hash-logger-blocks-to-retain` | `1000` |
| `app.toml`, `[state-commit]` | `sc-snapshot-writer-limit` | `1` |
| `app.toml`, `[state-store]` | `ss-enable` | `true` |
| `app.toml`, `[state-store]` | `ss-keep-recent` | `1000` |
| `app.toml`, `[state-store]` | `ss-snapshot-enable` | `false` |
| `app.toml`, `[evm]` | `http_enabled` | `true` |
| `app.toml`, `[evm]` | `ws_enabled` | `true` |
| `app.toml`, `[evm]` | `enable_simulation` | `false` |
| `app.toml`, `[evm]` | `trace_bake_enabled` | `false` |
| `app.toml`, `[api]` | `enable` | `false` |
| `app.toml`, `[wasm]` | `memory_cache_size` | `16` (MiB) |
| `app.toml`, `[light_invariance]` | `supply_enabled` | `false` |
| `config.toml`, `[tx-index]` | `indexer` | `["null"]` |

Ingress mode also tunes two stores in ways that no `app.toml` setting controls. memIAVL keeps only its latest snapshot. FlatKV uses smaller caches, memtables, and write backlogs, and it keeps only one old snapshot.
2 changes: 2 additions & 0 deletions node/node-types.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ You can run a few types of nodes on the Sei network. Each type has a different p

- Frozen nodes: these full nodes stop one block before an upgrade height. They keep running the outgoing release and serve queries for the heights before the upgrade. To run one, see [Run frozen nodes](/node/frozen-nodes).

- Ingress nodes: these full nodes serve EVM transaction submission and WebSocket subscriptions with a small memory and disk footprint. They keep state and receipts for only the last 1000 blocks. To run one, see [Run ingress nodes](/node/ingress-nodes).

- State sync nodes: these nodes serve snapshot data that other nodes use to bootstrap onto the chain. To enable this type of node, set a non-zero `snapshot-interval` under `[state-sync]` in `app.toml`. The `enable=true` setting under `[statesync]` in `config.toml` does the opposite: it makes a node bootstrap from the snapshots of other nodes.

- Validator nodes: these nodes propose and sign blocks to secure the chain. To enable this type of node, set `mode=validator` in `config.toml`. Because Sei uses proof of stake, you must have enough delegation to join the active set.
Expand Down
25 changes: 25 additions & 0 deletions node/technical-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,31 @@
SEI_CONFIG_MANAGER=v2 seid start
```

#### Ingress mode (`--ingress`)

Ingress mode runs a full node that serves EVM traffic over the last 1000 blocks with a small memory and disk footprint. Use the `--ingress` start flag or a top-level `ingress = true` key in `app.toml`. No tagged `seid` release includes ingress mode yet. For setup steps and deployment guidance, see [Run ingress nodes](/node/ingress-nodes).

At startup, ingress mode overrides a fixed set of settings:

- The EVM HTTP and WebSocket servers stay on.
- The REST API, the transaction index, state proofs, snapshot production for state sync, state-store snapshots, gas simulation in `eth_sendRawTransaction`, trace baking, and the supply invariant check are off.
- The node keeps state, receipts, and hash logs for the last 1000 blocks. It keeps blocks for at least the evidence window.
- P2P networking and the mempool do not change.

```bash
# Start a full node in ingress mode
seid start --ingress
```

```toml
# app.toml — top-level key in the base configuration, not under any [section]
ingress = true
```

<Warning>
Ingress mode is supported only for full nodes. In validator or seed mode, startup fails with `--ingress requires Tendermint mode "full", got "<mode>"`. Ingress mode also does not run with Autobahn. When `autobahn-config-file` is set in `config.toml`, startup fails with `--ingress is not supported with Autobahn`. You also cannot combine ingress mode with a non-zero `freeze-height`. The node then fails with `--ingress cannot be combined with --freeze-height`.
</Warning>

#### Freeze mode (`--freeze-height`)

As of v6.6.3, you can put a full node into read-only freeze mode at a specified block height. Use the `--freeze-height` start flag or the corresponding `freeze-height` field in `app.toml`. 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. It does not shut down at the boundary or execute the upgrade block with code that no longer matches that state. For setup steps and the freeze heights of each network, see [Run frozen nodes](/node/frozen-nodes).
Expand Down Expand Up @@ -135,7 +160,7 @@

Responses proxied to a single backend carry a `Sei-RPC-Route` header. The header identifies which backend served the response: `frozen:<height>` for the frozen node at that freeze height, or `live` for the live node. A batch split across multiple backends returns `mixed`. Router-generated errors (oversized or malformed requests, batches over the limit, block ranges that span intervals, and unreachable backends) do not carry the header. Neither does non-`POST` traffic that passes through to the live node.

### seidb tooling commands

Check warning on line 163 in node/technical-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/technical-reference.mdx#L163

Use sentence case for headings: 'seidb tooling commands'.

The `seidb` binary has low-level tools to inspect and maintain a node's on-disk state.

Expand Down Expand Up @@ -266,7 +291,7 @@
- `--full`: Show every column for each block with differences. By default, the command shows only the columns that differ. Use `--full` when the archives hold a different number of records for a block.
- `--json`: Print JSON instead of text.

### Autobahn (GigaRouter) config generation

Check warning on line 294 in node/technical-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/technical-reference.mdx#L294

Use sentence case for headings: 'Autobahn (GigaRouter) config generation'.

When you use the Autobahn (GigaRouter) networking layer, you can generate the Autobahn JSON config from a set of node directories. Each directory must contain `validator_pubkey.txt`, `node_pubkey.txt`, `autobahn_address.txt`, and `evmrpc_url.txt`. Unlike the key files, `evmrpc_url.txt` is not written automatically, so you must create it by hand with the node's EVM RPC URL. If the file is missing, the command fails with an error. The `mempool_size` field is no longer part of `autobahn.json`. Remove it from existing config files.

Expand Down
Loading