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
8 changes: 5 additions & 3 deletions skill/references/cli/seid-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ All transaction commands require a funded key in the local keyring (`--from`).

```bash
# Associate a Sei address with an EVM address
seid tx evm associate-address [optional-priv-key-hex] --from <name> --evm-rpc <url>
seid tx evm native-associate <custom-message> --from <name> -y

# Send native SEI (amount in wei)
seid tx evm send <to-evm-addr> <amount-wei> --from <name> --gas-fee-cap <cap> --gas-limit <limit>
Expand Down Expand Up @@ -303,10 +303,10 @@ For writes: sign first, then submit via `eth_sendRawTransaction`. Prefer a walle

- **Finality:** `safe`, `finalized`, and `latest` are equivalent on Sei (instant single-block finality).
- **Proofs:** Sei stores state in SeiDB state-commit (SC), a memiavl-based tree, not Merkle Patricia Tries. The legacy IAVL backend has been fully removed and SeiDB SC is mandatory — a node started with `sc-enable = false` panics with `SeiDB state-commit (SC) must be enabled; IAVL backend has been fully deprecated`. Proofs from Cosmos-side queries are IAVL-style (memiavl) proofs, not Merkle Patricia Trie proofs.
- **`eth_getProof` is not supported** (since v6.7.0, [sei-chain#3926](https://github.com/sei-protocol/sei-chain/pull/3926)): it returns `-32000` `eth_getProof is not supported yet; please reach out to the Sei Labs if you need this endpoint`.
- **`eth_getProof` is not supported** (since v6.7.0, [sei-chain#3926](https://github.com/sei-protocol/sei-chain/pull/3926)): it returns `-32000` `eth_getProof is not supported yet on Sei EVM RPC; please reach out to the Sei team if you need this endpoint`. It is registered but deliberately unimplemented (so callers get `-32000`, not `-32601` method-not-found), and is deprecated pending further work rather than a permanent incompatibility.
- **Filter limits:** Open-ended log queries return up to 10,000 logs; closed-range queries cover up to 2,000 blocks.
- **Legacy `sei_*` methods:** As of v6.7.0 only three remain, all deprecated: `sei_getSeiAddress`, `sei_getEVMAddress`, `sei_getCosmosTx` (EVM HTTP only). The `sei2_*` namespace and every other `sei_*` method (block/receipt/count getters, filters, logs, `sei_getTransactionReceipt`, `sei_sign`, `sei_associate`) were removed ([sei-chain#3912](https://github.com/sei-protocol/sei-chain/pull/3912), [#3924](https://github.com/sei-protocol/sei-chain/pull/3924), [#3927](https://github.com/sei-protocol/sei-chain/pull/3927), [#3945](https://github.com/sei-protocol/sei-chain/pull/3945)); the `sei_traceBlockBy*ExcludeTraceFail` endpoints were removed in v6.6.0. Use standard `eth_*` / `debug_*` methods.
- **Legacy `sei_*` gating:** The three remaining methods are served only if listed in `[evm].enabled_legacy_sei_apis` in `app.toml` (also settable via the `evm.enabled_legacy_sei_apis` AppOptions flag); the `seid init` default lists all three, and other names in the list are ignored. All responses return HTTP 200. Any other `sei_*` name returns a JSON-RPC error with code `-32601` and `data` `"legacy_sei_deprecated"` (the message says the method is not enabled; for removed methods, adding them to the allowlist does nothing). `sei2_*` calls return the standard `-32601` "does not exist". Allowed calls pass through with an unchanged JSON body but may set the HTTP response header `Sei-Legacy-RPC-Deprecation`.
- **Legacy `sei_*` gating:** The three remaining methods are served only if listed in `[evm].enabled_legacy_sei_apis` in `app.toml` (also settable via the `evm.enabled_legacy_sei_apis` AppOptions flag); the `seid init` default lists all three (`sei_getCosmosTx`, `sei_getEVMAddress`, `sei_getSeiAddress`), and other names in the list are ignored. `sei_getTransactionReceipt` is removed entirely (since v6.7.0, [sei-chain#3945](https://github.com/sei-protocol/sei-chain/pull/3945)): it is no longer a gated method, so adding it to `enabled_legacy_sei_apis` does nothing — `BuildSeiLegacyEnabledSet` drops it and the name returns the standard not-enabled error. Clients must use `eth_getTransactionReceipt`; there is no longer any JSON-RPC method for discovering synthetic logs from Cosmos-originated transactions. All responses return HTTP 200. Any other `sei_*` name returns a JSON-RPC error with code `-32601` and `data` `"legacy_sei_deprecated"` (the message says the method is not enabled; for removed methods, adding them to the allowlist does nothing). `sei2_*` calls return the standard `-32601` "does not exist". Allowed calls pass through with an unchanged JSON body but may set the HTTP response header `Sei-Legacy-RPC-Deprecation`.
- **`debug_traceTransaction`:** Only available if the RPC node exposes debug methods. If unavailable, fall back to standard RPC queries.
- **`debug_trace*` tracer gating (deviation from upstream geth):** `debug_traceCall`, `debug_traceTransaction`, `debug_traceBlockByNumber`, `debug_traceBlockByHash`, and `debug_traceTransactionProfile` now reject any caller-supplied `TraceConfig.Tracer` name that is not in the `[evm].trace_allowed_tracers` allowlist in `app.toml` (also settable via the `evm.trace_allowed_tracers` AppOptions flag). The default allowlist is the native geth tracers `["callTracer", "prestateTracer", "flatCallTracer", "4byteTracer", "noopTracer", "muxTracer"]`; set it to `[]` to disable all named tracers. Requesting a name not on the list returns an error like `debug tracer "<name>" is not allowed; JavaScript tracers are disabled and only native tracers listed in evm.trace_allowed_tracers may be used`. Omitting `Tracer` (the default struct logger) is always available. Request-supplied JavaScript tracer source is rejected unless `[evm].trace_allow_js_tracers` (`evm.trace_allow_js_tracers`, default `false`) is explicitly enabled — upstream geth accepts JS tracers by default, Sei does not. Enabling `trace_allow_js_tracers` does **not** widen the native allowlist: native tracer names must still be listed in `trace_allowed_tracers` to be usable. `trace_allowed_tracers` is validated native-only at startup (a non-native/typo'd name fails startup), and `muxTracer` nested tracer names are validated recursively up to a bounded depth of 16. The baked-tracer list `[evm].trace_bake_tracers` is held to the same native-only rule at startup. (v6.7.0, [sei-chain#3718](https://github.com/sei-protocol/sei-chain/pull/3718))

Expand Down Expand Up @@ -424,6 +424,8 @@ Notes:
- The primary comparison is `account+code+storage+misc`, printed as one `FINAL_DIGEST` line. flatkv can contain flatkv-only migration rows that a memiavl-only node never owns — the migration-version marker (`migration/migration-version`, once a migration completes) and the migration-boundary cursor (only while a migration is in flight). Both are folded into the `misc` bucket but XORed back out for the final comparison, and a `flatkv_marker_adjustment` line reports this. This makes the flatkv `FINAL_DIGEST` comparable apples-to-apples against memiavl-only output.
- To hunt the single diverging entry when two `bucket_digest` values differ by exactly one row, XOR those two 32-byte hex values and pass the result to `--find-hash`.

- A FlatKV migration can be inspected while it is still in flight: the `composite` backend digests the union of flatkv (migrated) rows and memiavl (not-yet-migrated) rows, and in `flatkv`/`composite` modes the migration-boundary cursor is present (folded into the `misc` bucket and reported via `flatkv_marker_adjustment`) so a mid-migration node can be compared against a memiavl-only or completed node at the same height. The `--inspect-bucket`/`--inspect-plan` inspect reports work against such an in-flight migration too — run the inspect against the `misc` bucket (where the migration-version marker and boundary cursor live) or against `account`/`code`/`storage` to examine the normalized rows that have migrated so far. Combine with `--json` (since [sei-chain#4255](https://github.com/sei-protocol/sei-chain/pull/4255)) to capture the inspect report as one JSON object for scheduled/automated digest checks.

Compare a migrated FlatKV node against a memiavl-only node at height `H` — the two `FINAL_DIGEST` lines should match:

```bash
Expand Down
35 changes: 35 additions & 0 deletions skill/references/contracts/performance-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,41 @@ Source: https://github.com/sei-protocol/sei-chain/tree/main/loadtest

You don't need to fork it. Build your own loadtest in TypeScript with viem (above) — same shape, easier to iterate.


### EVM-only executor load harness (`evmonly-loadtest`)

sei-chain v6.7.0 added a standalone harness at `giga/evmonly/cmd/evmonly-loadtest` that feeds synthetic blocks directly into the EVM-only executor with mock state and receipt sinks — no Cosmos SDK, mempool, RPC, or chain persistence. It isolates executor/OCC throughput from block production, so it's the most direct way to see how a workload behaves under parallel execution.

Basic bounded run:

```bash
go run ./giga/evmonly/cmd/evmonly-loadtest --blocks=1000 --txs-per-block=1000
```

The synthetic workload defaults to local EVM chain ID `1337` (override with `--chain-id`). `--blocks` is required and must be greater than `0`; the harness prebuilds every block before the measured phase.

Three workloads, selected with `--workload` (default `transfer`):

- `transfer` — pure EVM legacy transfer transactions. Recipients are unique by default (optimistic no-overlap). Pass `--recipient-conflict-rate=<0..1>` to pair that fraction of each block onto shared recipients, `--recipient=0x...` to force one recipient, or `--same-sender` to use one sender with sequential nonces per block.
- `erc20-transfer` — ERC20 transfer calls using sei-load's compiled contract runtime.
- `snapshot-revert` — a contract-call workload that exercises nested StateDB snapshot/revert behavior (`--snapshot-revert-contract`, `--snapshot-revert-helper`).

The three OCC scenarios map to conflict-free (unique senders/recipients), hot-recipient (`--recipient=0x...`), and same-sender nonce chain (`--same-sender`). Zero gas settings keep the conflict-free case focused on no-overlap:

```bash
go run ./giga/evmonly/cmd/evmonly-loadtest \
--blocks=400 --txs-per-block=5000 \
--gas-price-wei=0 --min-gas-price-wei=0 \
--recipient-conflict-rate=0.10
```

Non-zero fees make every tx update the coinbase balance — a real intra-block conflict.

Useful tuning flags: `--workers` (parallel executors, default `1`), `--executor-workers` (OCC workers per executor, default `min(12, GOMAXPROCS)`), `--prepare-workers`, `--parse-workers`, `--builders`, `--queue-size` (default `64`). Result handling: `--result-sink=discard|file`, with `--persist-dir`, `--persist-sync`, `--persist-buffer-size`, `--persist-queue-size` for the file sink. Profiling: `--cpu-profile`, `--heap-profile`, `--trace-profile`.

Observability: unless `--metrics-addr=` is empty, an HTTP server listens on `--metrics-addr` (default `127.0.0.1:9698`) exposing Prometheus metrics at `/metrics` and a `/healthz` endpoint. `--report-interval` (default `5s`) also prints throughput to stdout. Metrics include block input/preparation/finishing throughput, finished/successful/failed tx per second, gas per second, total OCC rerun attempts, queue depths, and result-sink stats. `sink_enqueue_wait` is the primary backpressure signal — a non-zero value means executor workers waited for async sink queue capacity.


## Common bottlenecks discovered by load testing

| Symptom | Likely cause | Fix |
Expand Down
10 changes: 6 additions & 4 deletions skill/references/ecosystem/node-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,21 +189,23 @@ SeiDB has two layers: **State Commit (SC)** — a memiavl Merkle tree that holds

## Legacy `sei_*` JSON-RPC gating (`[evm] enabled_legacy_sei_apis`)

As of v6.7.0 only three legacy `sei_*` methods remain on the EVM HTTP endpoint (port `8545` — not WebSocket, and not the Cosmos REST API on `1317`): `sei_getSeiAddress`, `sei_getEVMAddress`, and `sei_getCosmosTx`. They are deprecated; build new integrations on `eth_*` / `debug_*`. The `sei2_*` namespace and all other `sei_*` methods were removed ([sei-chain#3912](https://github.com/sei-protocol/sei-chain/pull/3912), [#3924](https://github.com/sei-protocol/sei-chain/pull/3924), [#3927](https://github.com/sei-protocol/sei-chain/pull/3927), [#3945](https://github.com/sei-protocol/sei-chain/pull/3945)); the `sei_traceBlockBy*ExcludeTraceFail` endpoints went in v6.6.0.
Only three legacy `sei_*` methods remain on the EVM HTTP endpoint (port `8545` — not WebSocket, and not the Cosmos REST API on `1317`): `sei_getSeiAddress`, `sei_getEVMAddress`, and `sei_getCosmosTx`. They are deprecated; build new integrations on `eth_*` / `debug_*`. The `sei2_*` namespace and all other `sei_*` methods were removed ([sei-chain#3912](https://github.com/sei-protocol/sei-chain/pull/3912), [#3924](https://github.com/sei-protocol/sei-chain/pull/3924), [#3927](https://github.com/sei-protocol/sei-chain/pull/3927), [#3945](https://github.com/sei-protocol/sei-chain/pull/3945)); the `sei_traceBlockBy*ExcludeTraceFail` endpoints went in v6.6.0.

Which of the three are served is controlled by the `enabled_legacy_sei_apis` allowlist under `[evm]` in `app.toml`:
`sei_getTransactionReceipt` has been **fully removed** — it is no longer available even when explicitly listed in the allowlist. Use `eth_getTransactionReceipt` instead. There is no longer any JSON-RPC method for discovering synthetic logs from Cosmos-originated transactions.

Which of these are served is controlled by the `enabled_legacy_sei_apis` allowlist under `[evm]` in `app.toml`:

```toml
[evm]
# seid init / DefaultConfig list all three remaining methods.
# seid init / DefaultConfig list all three remaining address/Cosmos helpers.
enabled_legacy_sei_apis = [
"sei_getSeiAddress",
"sei_getEVMAddress",
"sei_getCosmosTx",
]
```

- **Only these three names have any effect.** Names are matched case-insensitively; any other name in the list is ignored, so a removed method cannot be re-enabled.
- **Only these three names have any effect.** Names are matched case-insensitively; any other name in the list is ignored, so a removed method (including `sei_getTransactionReceipt`) cannot be re-enabled.
- **Internally read through the AppOptions/viper key** `evm.enabled_legacy_sei_apis` (an environment-variable override via viper is possible; there is no dedicated `seid` CLI flag).
- The Docker localnet config (`docker/localnode/config/app.toml`) lists the same three.

Expand Down
1 change: 1 addition & 0 deletions skill/references/ecosystem/rpc-providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ The following methods are also **registered but explicitly unsupported** on Sei
|---|---|
| `eth_syncing` | `eth_syncing is not supported on Sei EVM RPC` |
| `eth_newPendingTransactionFilter` | `eth_newPendingTransactionFilter is not supported on Sei EVM RPC` |
| `eth_getProof` | `eth_getProof is not supported yet on Sei EVM RPC; please reach out to the Sei team if you need this endpoint` |
| `debug_getRawBlock` | `debug_getRawBlock is not supported on Sei EVM RPC` |
| `debug_getRawHeader` | `debug_getRawHeader is not supported on Sei EVM RPC` |
| `debug_getRawReceipts` | `debug_getRawReceipts is not supported on Sei EVM RPC` |
Expand Down
2 changes: 1 addition & 1 deletion skill/references/evm/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ These methods are **registered** on Sei's EVM RPC but return JSON-RPC error code
| Method | `error.message` |
|---|---|
| `eth_blobBaseFee` | `blobs not supported on this chain` |
| `eth_getProof` | `eth_getProof is not supported yet; please reach out to the Sei Labs if you need this endpoint` (since v6.7.0) |
| `eth_getProof` | `eth_getProof is not supported yet on Sei EVM RPC; please reach out to the Sei team if you need this endpoint` (since v6.7.0, [sei-chain#3926](https://github.com/sei-protocol/sei-chain/pull/3926)) |
| `eth_syncing` | `eth_syncing is not supported on Sei EVM RPC` |
| `eth_newPendingTransactionFilter` | `eth_newPendingTransactionFilter is not supported on Sei EVM RPC` |
| `debug_getRawBlock` | `debug_getRawBlock is not supported on Sei EVM RPC` |
Expand Down
Loading