Skip to content

docs(node): add a guide for running ingress nodes - #109

Open
alexander-sei wants to merge 1 commit into
mainfrom
docs/ingress-nodes
Open

alexander-sei wants to merge 1 commit into
mainfrom
docs/ingress-nodes

Conversation

@alexander-sei

Copy link
Copy Markdown
Collaborator

Problem

seid start --ingress landed on sei-chain main in sei-chain#4739. It runs a full node that serves EVM transaction submission and WebSocket traffic over the last 1000 blocks with a small memory and disk footprint. Latency-sensitive operators, such as high-frequency trading (HFT) firms, can then run their own submission endpoint in each region without a full RPC node in each.

The docs don't mention the mode. An operator has no page that says what an ingress node serves, what it turns off, how much history it keeps, how to set one up, or which app.toml settings it ignores.

Change

Adds node/ingress-nodes.mdx (Ingress Nodes under Advanced Operations, after Frozen Nodes):

  • How ingress mode works: what the node serves (EVM HTTP and WebSocket, and the Tendermint RPC without transaction queries) and what it turns off (the REST API, the transaction index, snapshot production for state sync, send-time gas simulation, and more).
  • History: state and receipts for the last 1000 blocks, blocks for at least the evidence window, and where to send older requests.
  • Prerequisites and setup as steps: initialize in full mode, configure state sync, start seid with --ingress from systemd, and verify with catching_up, eth_chainId, and the listening ports.
  • A section on using ingress nodes for HFT: placement next to trading systems, submission and eth_subscribe on your own node, tight gas limits, peering, firewalling, and redundancy.
  • A reference table of every setting the mode overrides.

The page is linked from the node types list, the Nodes overview (new card), and a new "Ingress mode (--ingress)" entry in the technical reference, next to freeze mode. The style guide's Advanced Operations list gets the new page.

Release status

No tagged seid release includes ingress mode yet. The newest tag is v6.8.0. The page and the technical reference entry both open with a warning that says so.

A release without the mode rejects --ingress as an unknown flag, but it silently ignores ingress = true in app.toml. The page therefore recommends the flag.

When the first release with the mode ships, replace both warnings with a "first shipped in vX.Y.Z" line, as the frozen nodes page does. Merging earlier puts a flag that no release has on docs.sei.io, so you may want to hold the merge until then.

Verification

  • Behavior was checked against sei-chain main (0bc7ed5): the overrides and startup refusals in configureIngressProfile (sei-cosmos/server/start.go), the memIAVL and FlatKV changes in parseSCConfigs (app/seidb.go), the merge of app.toml into the start command's Viper, and the error strings quoted on the page. v6.8.0 has neither the flag nor the key.
  • The gas-limit advice follows the code. With enable_simulation = false, eth_sendRawTransaction sets the gas estimate to the gas limit (evmrpc/send.go). Validators take that estimate in CheckTx, and proposers reap EVM transactions by estimated gas against the block gas limit.
  • Block retention follows GetBlockRetentionHeight, which never prunes inside the evidence window. min-retain-blocks = 1000 therefore doesn't shorten block history below max_age_num_blocks.
  • The EVM servers bind to 0.0.0.0, and seid init writes enable = true under [api]. The firewall advice and the port check in the verify step rely on these.
  • Local checks: typos, Vale (no alerts on changed lines), scripts/check-redirects.mjs, scripts/check-skills.mjs, scripts/check-snippet-theme-default.mjs, scripts/audit-seo.mjs (no findings for the new page), mint broken-links --check-anchors, and mint validate. Rendering was checked with mint dev.

Notes

  • The page gives no memory, disk, or latency numbers. The measurements in sei-chain#4739 come from arctic-1, not Sei Mainnet.
  • llms.txt and llms-full.txt are left to the weekly regeneration workflow, as AGENTS.md asks.

Made with Cursor

seid start --ingress (sei-protocol/sei-chain#4739) runs a full node that
serves EVM transaction submission and WebSocket traffic over the last 1000
blocks with a small memory and disk footprint. Add a page that explains what
the mode serves and turns off, how to set one up from state sync, how to use
ingress nodes for high-frequency trading, and every setting the mode
overrides. Link it from the node types list, the node home page, and a new
technical reference entry next to freeze mode.

No tagged seid release includes the flag yet, so the page and the technical
reference entry both say so.

Co-authored-by: Cursor <cursoragent@cursor.com>
@mintlify

mintlify Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
sei-docs 🟢 Ready View Preview Nov 20, 2026, 4:43 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@cursor

cursor Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

PR Summary

Low Risk
Documentation-only changes with no runtime or security impact; operators should be aware the guide documents a feature not yet in a released seid binary.

Reviewed by Cursor Bugbot for commit 50f4688. Bugbot is set up for automated code reviews on this repo. Configure here.

@seidroid seidroid Bot left a comment

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.

The new ingress-node guide is clear and follows the house style. It is linked from the node types list, the Nodes overview, the technical reference, docs.json, and the style guide. Nothing blocks the merge, but the page documents a flag that no tagged release has yet, and the port check could be more robust.

Findings: 0 blocking | 4 non-blocking | 1 posted inline

Blockers

  • None at the file/PR level.

Non-blocking

  • Release timing: no tagged seid release includes --ingress yet. AGENTS.md says the docs should contain no speculation about unreleased features. The page warns about this clearly, but consider holding the merge until the first release ships, as the PR description itself suggests. Then replace both warnings with a 'first shipped in vX.Y.Z' line.
  • Codex says the Tendermint RPC jq paths (.sync_info.catching_up, .consensus_params..., .n_peers) need a .result. prefix. I disagree. Sei's Tendermint fork returns GET responses without the JSON-RPC wrapper, and the repo already uses unwrapped paths in node/statesync.mdx (.block.header.height) and node/frozen-nodes.mdx (.sync_info...). Please confirm against a live node before merging. Separately, node/troubleshooting.mdx and evm/reference.mdx use .result. paths, so one of the two conventions is wrong somewhere in the docs. That is worth reconciling in a follow-up.
  • Cursor's review file was empty, so that pass produced no output.
  • 1 suggestion(s)/nit(s) flagged inline on specific lines.

Comment thread node/ingress-nodes.mdx
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.)

This branch was successfully deployed

1 active deployment
staging — 50f46889 Deployed Nov 20, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant