diff --git a/cosmos-sdk/index.mdx b/cosmos-sdk/index.mdx index ffac8247..71f2944f 100644 --- a/cosmos-sdk/index.mdx +++ b/cosmos-sdk/index.mdx @@ -14,6 +14,10 @@ Cosmos SDK and CosmWasm functionality is being deprecated in favor of EVM-only. In addition, [Proposal 115](https://seistream.app/proposals/115) disables CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) chain-wide. No new CosmWasm contracts can be deployed. Only `execute` and `query` against pre-existing contracts remain available through the [CosmWasm precompile](/evm/precompiles/cosmwasm-precompiles/cosmwasm). + + +As of the v6.8 upgrade (#4564), governance can halt CosmWasm contract execution in stages through two new wasm module params, each settable with a param-change proposal against the `wasm` subspace. While `msgExecuteContractDisabled` is `true`, every `MsgExecuteContract` fails (codespace `wasm`, code 31), whether sent directly, wrapped in an authz `MsgExec`, or dispatched by a contract; the EVM wasmd precompile, solo claims, and wasm gov proposals still execute. While `contractExecutionDisabled` is `true`, no contract runs at all (codespace `wasm`, code 32): every instantiation, execution, migration, and sudo call fails whatever its origin, including the EVM wasmd and solo precompiles and wasm gov proposals, so even `execute` against pre-existing contracts stops working; `query` still works. Both params default to `false` and are stored as `false` at the upgrade (the wasm module moves to consensus version 2, app-hash breaking at the upgrade height). + **IBC is now disabled in both directions.** [Proposal 116](https://seistream.app/proposals/116) and [Proposal 120](https://seistream.app/proposals/120) set the `ibc` module's `InboundEnabled` parameter to `false`, and [Proposal 121](https://seistream.app/proposals/121) set `OutboundEnabled` to `false` on July 31, 2026. No asset can be bridged into or out of Sei over IBC. IBC assets already on Sei can no longer be redeemed on their origin chain. See the [SIP-03 Migration Guide](/learn/sip-03-migration) for the full explanation and the list of affected assets. @@ -22,6 +26,8 @@ In addition, [Proposal 115](https://seistream.app/proposals/115) disables CosmWa -Tokenfactory tutorials and development support have been retired as part of Sei's move to EVM-only under SIP-3. Do not create, mint, burn, administer, or build integrations around tokenfactory denoms. Legacy module and RPC surfaces may still exist for compatibility, but tokenfactory is not a supported path for new development. Deploy an ERC-20 contract instead. +The tokenfactory module is removed as of the v6.8 upgrade. The module, its store, params, CLI commands (`seid tx tokenfactory ...` and `seid q tokenfactory ...`), gRPC/REST query and Msg services, and nearly all CosmWasm bindings are gone. Do not create, mint, administer, or build new integrations around tokenfactory denoms. Only the tokenfactory Msg types remain decodable so historical blocks still trace; any such message now fails validation (codespace `tokenfactory`, code 26, "tokenfactory module is deprecated") and is rejected without charging a fee. Existing `factory/` balances remain in the bank module and can no longer be minted, and denoms that previously carried a transfer allowlist now transfer freely, since the bank `factory/` denom transfer allowlist enforcement has been removed. + +One exception survives the removal (#4549): the `burn_tokens` Wasm custom message still works, so a contract can burn a `factory//` denom it created, from its own balance. The handler accepts only denoms the calling contract created (prefix `factory//`) and burns from that contract's own balance; `mint_tokens` and every other tokenfactory Wasm message remain removed and unsupported. For new tokens, deploy an ERC-20 contract instead. diff --git a/evm/changelog.mdx b/evm/changelog.mdx index d926e02d..086bd99e 100644 --- a/evm/changelog.mdx +++ b/evm/changelog.mdx @@ -10,6 +10,25 @@ Stay up to date with the latest changes, improvements, and new features in Sei. This changelog is automatically synced from the [sei-chain repository](https://github.com/sei-protocol/sei-chain/blob/main/CHANGELOG.md). For the most up-to-date information, you can also view the changelog directly on GitHub. + + +**v6.8 chain upgrade** + +The v6.8 chain upgrade introduces new versioned EVM precompiles that expose additional on-chain query and authorization methods to contract developers. Node operators must upgrade to the v6.8 binary before the scheduled plan height; an unupgraded binary halts at that height. + +Newly exposed precompile methods include: + +- **Auth** (`0x…100D`): `account`, `accounts`, `params`, `nextAccountNumber`. +- **Authz** (`0x…100E`): `grants`, `granterGrants`, `granteeGrants`. +- **Evidence** (`0x…100F`): `evidence`, `allEvidence`. +- **Bank** (`0x…1001`): adds `spendableBalances`, `totalSupply`, `params`, `denomMetadata`, `denomsMetadata` alongside the existing send/balance methods. +- **Distribution** (`0x…1007`): adds `communityPool`, `params`, `validatorOutstandingRewards`, `validatorCommission`, `validatorSlashes`, `delegationRewards`, `delegatorValidators`, `delegatorWithdrawAddress`, `grantWithdrawAuthorization`, `revokeWithdrawAuthorization`, `withdrawDelegationRewardsWithAuthorization`, `withdrawValidatorCommissionWithAuthorization`. +- **Gov** (`0x…1006`): adds `proposal`, `proposals`, `getVote`, `votes`, `params`, `getDeposit`, `deposits`, `tallyResult`, `grantVoteAuthorization`, `grantProposalAuthorization`, `voteWithAuthorization`, `submitProposalWithAuthorization`, `revokeVoteAuthorization`, `revokeProposalAuthorization`, `voteWeighted`. + +The upgrade also adds two governance-settable wasm params that halt CosmWasm contract execution in stages (#4564). While `msg_execute_contract_disabled` is `true`, every `MsgExecuteContract` fails, whether sent directly, wrapped in an authz `MsgExec`, or dispatched by a contract; the EVM wasmd precompile, solo claims, and wasm gov proposals still execute. While `contract_execution_disabled` is `true`, no contract runs: every instantiation, execution, migration, and sudo call fails from any origin, including the EVM wasmd and solo precompiles and wasm gov proposals, while queries still work. Both params default to `false` and are settable via a param-change governance proposal under the `wasm` subspace (keys `msgExecuteContractDisabled` and `contractExecutionDisabled`). The wasm module moves to consensus version 2 and stores both params as `false` at the upgrade, which is app-hash breaking at the upgrade height. + + + **Stay updated** diff --git a/evm/evm-parity/evm-compatibility.mdx b/evm/evm-parity/evm-compatibility.mdx index 5e315790..a86b64b8 100644 --- a/evm/evm-parity/evm-compatibility.mdx +++ b/evm/evm-parity/evm-compatibility.mdx @@ -52,8 +52,8 @@ Standard EVM tools (viem, wagmi, ethers, Foundry, and Hardhat) work on Sei for a | Feature | Sei status | Notes | | --- | --- | --- | -| `eth_getLogs` | Supported with differences | A query fails when it matches more than 10,000 logs (`max_log_no_block`) or about 64 MiB of log data (`max_log_bytes`). The query does not return partial results. Narrow the block range or the filters, then try again. [See Filter and subscription limits.](/evm/reference#filter-and-subscription-limits) | -| Filter lifecycle (`eth_newFilter`, `eth_getFilterChanges`, `eth_getFilterLogs`, `eth_uninstallFilter`) | Supported | | +| `eth_getLogs` | Supported with differences | A query fails when it matches more than 10,000 logs (`max_log_no_block`) or about 64 MiB of log data (`max_log_bytes`). The query does not return partial results. Narrow the block range or the filters, then try again. On a state-synced or snapshot-restored node the receipt store can start later than the block store; the earliest queryable height is this receipt floor. A block-range or block-hash query targeting a height below the floor returns JSON-RPC error `-32000` (receipts pruned) instead of empty results, while an unknown block hash still returns no blocks. `eth_getLogs`, `eth_getFilterLogs`, and each `eth_getFilterChanges` poll share one admission check before reading: a range over `max_blocks_for_log` is refused, and a range over 100 blocks consumes a token from a large-query rate limiter shared by all three. A refusal for rate limiting or server load returns JSON-RPC error `-32005` (limit exceeded, retry later) and carries no internal server counts; retry after a short delay. [See Filter and subscription limits.](/evm/reference#filter-and-subscription-limits) | +| Filter lifecycle (`eth_newFilter`, `eth_getFilterChanges`, `eth_getFilterLogs`, `eth_uninstallFilter`) | Supported with differences | `eth_getFilterLogs` and each `eth_getFilterChanges` poll pass the same admission as `eth_getLogs` (see above), sharing one large-query rate-limit budget. Without a token, `eth_getFilterLogs` is refused with `-32005` while a filter poll is cut to the next 100 blocks so it keeps advancing. A poll refused for server load leaves the cursor in place and returns `-32005`. | | WebSocket subscriptions (`eth_subscribe`) | Supported | [See WebSocket Connections.](/evm/evm-parity/websocket) | ## Execution and simulation @@ -101,8 +101,9 @@ These features are specific to Sei and have no standard Ethereum equivalent. The | Feature | Notes | | --- | --- | | Sei precompiles (staking, governance, distribution, P256, JSON, Solo, pointers, and the CosmWasm bridge) | EVM contracts at deterministic addresses. `@sei-js/precompiles` exports the ABIs and contract addresses for use with any standard EVM library. It does not export the retired Oracle and disabled IBC precompiles. | -| Pointer contracts (CW20 ↔ ERC-20, CW721 ↔ ERC-721, CW1155 ↔ ERC-1155) | Bridge between CosmWasm and EVM token standards. Standard ERC interfaces work with pointer contracts. To look up a pointer, use `POINTERVIEW_PRECOMPILE_ADDRESS` (`0x…100A`). To register a pointer, use `POINTER_PRECOMPILE_ADDRESS` (`0x…100B`). | +| Pointer contracts (CW20 ↔ ERC-20, CW721 ↔ ERC-721, CW1155 ↔ ERC-1155) | Bridge between CosmWasm and EVM token standards. Standard ERC interfaces work with pointers that already exist. Pointer creation is retired: the pointer precompile at `POINTER_PRECOMPILE_ADDRESS` (`0x…100B`) stays registered but every `add*` call reverts with `pointer precompile is retired; EVM pointer creation is disabled`, so no new pointer of any kind can be created. Only lookups remain available — use `POINTERVIEW_PRECOMPILE_ADDRESS` (`0x…100A`) to resolve an existing pointer. | | Native address association (EVM ↔ Cosmos address) | Links an EVM address and a Cosmos address for the same account. Some Sei-native flows require this association first. | +| `milliTimestamp` block-header field | A BEP-520-compatible header field returned by `eth_getBlockByHash`, `eth_getBlockByNumber`, and `eth_subscribe("newHeads")`, carrying the block time as a hex quantity of Unix milliseconds alongside the standard seconds-based `timestamp`. Sei commits blocks faster than once a second, so `timestamp` repeats across consecutive blocks; `milliTimestamp` exposes the sub-second precision the underlying header carries. It is not guaranteed unique per block (under Autobahn blocks less than a millisecond apart can tie). The synthetic genesis block returns `0x0`. | ## Unsupported RPC methods diff --git a/evm/evm-parity/examples/error-handling.mdx b/evm/evm-parity/examples/error-handling.mdx index ff265c76..03146ca4 100644 --- a/evm/evm-parity/examples/error-handling.mdx +++ b/evm/evm-parity/examples/error-handling.mdx @@ -153,6 +153,63 @@ try { ## Classifying any error + + +## Broadcast rejections + +When you submit a signed transaction with `eth_sendRawTransaction`, Sei's mempool may reject it before it is ever included in a block. These rejections are now mapped to the same standard go-ethereum error types that EVM clients already recognize, so you can handle them with the same logic you use against other Ethereum networks: + +| Condition | Returned error | +| --- | --- | +| Transaction is already pending in the mempool | `ErrAlreadyKnown` (`already known`) | +| Transaction nonce is below the sender's lowest pending nonce | `ErrNonceTooLow` (`nonce too low`) | +| A transaction with the same nonce and at least the same priority is already held | `ErrReplaceUnderpriced` (`replacement transaction underpriced`) | +| The transaction would replace a ready transaction but the sender can't afford it | `ErrInsufficientFunds` (`insufficient funds for gas * price + value`) | + +Because these are the canonical Ethereum broadcast errors, you can match on their messages (or the equivalent error classes your client exposes): + + + +```ts viem +try { + await walletClient.sendRawTransaction({ serializedTransaction }); +} catch (err) { + const message = (err as Error).message ?? ''; + if (message.includes('already known')) { + // Transaction is already in the mempool — treat as a duplicate submit, don't resend + console.log('Transaction already known'); + } else if (message.includes('nonce too low')) { + // Nonce was already used — refetch the pending nonce and rebuild + console.error('Nonce too low'); + } else if (message.includes('replacement transaction underpriced')) { + // Bump the gas price/priority fee to replace the pending tx + console.error('Replacement underpriced'); + } else if (message.includes('insufficient funds')) { + console.error('Insufficient funds for this transaction'); + } +} +``` + +```ts ethers +try { + await provider.broadcastTransaction(signedTx); +} catch (err: any) { + const message = err?.error?.message ?? err?.message ?? ''; + if (message.includes('already known')) { + console.log('Transaction already known'); + } else if (err.code === 'NONCE_EXPIRED' || message.includes('nonce too low')) { + console.error('Nonce too low'); + } else if (err.code === 'REPLACEMENT_UNDERPRICED' || message.includes('replacement transaction underpriced')) { + console.error('Replacement underpriced'); + } else if (err.code === 'INSUFFICIENT_FUNDS' || message.includes('insufficient funds')) { + console.error('Insufficient funds for this transaction'); + } +} +``` + + + + This utility handles the most common cases in one place: ```ts diff --git a/evm/evm-parity/examples/pointer-contracts.mdx b/evm/evm-parity/examples/pointer-contracts.mdx index 6fe57d53..5e29f421 100644 --- a/evm/evm-parity/examples/pointer-contracts.mdx +++ b/evm/evm-parity/examples/pointer-contracts.mdx @@ -21,6 +21,10 @@ After you have the pointer address, you interact with it through the standard ER For background on how pointer contracts work, see the [Pointers overview](/learn/pointers). + +This page covers CosmWasm→EVM pointers (a CW20/CW721/CW1155 token exposed through an ERC-20/721/1155 pointer). The reverse direction — wrapping an ERC20/721/1155 token in a CosmWasm CW20/CW721/CW1155 wrapper via `MsgRegisterPointer` — has been retired. That handler now returns `ErrRegisterPointerDeprecated` and the wrapper bytecode is no longer shipped, so no new CW wrappers for ERC tokens can be created. Wrappers registered before the retirement remain live and readable: their registry entries, versions, and queries are unchanged, and `AssociateContractAddress` still gives such a wrapper an EVM address. + + ## Looking up a pointer address The pointerview precompile resolves pointer addresses for existing CosmWasm contracts. `@sei-js/precompiles` exports its ABI and address. diff --git a/evm/evm-parity/finality.mdx b/evm/evm-parity/finality.mdx index 5d60539d..e524d7d0 100644 --- a/evm/evm-parity/finality.mdx +++ b/evm/evm-parity/finality.mdx @@ -19,6 +19,8 @@ On Ethereum, `latest`, `safe`, and `finalized` refer to different points in the On Sei, all three tags resolve to the same block. After a block is committed, there is no reorg risk at any point, so the distinction does not exist. +Under the EVM-only RPC, state-reading methods differ in how they treat an explicit past block. `eth_getBalance`, `eth_getTransactionCount`, `eth_getCode`, and `eth_getStorageAt` accept an explicit block height (or `earliest`, which reads block 0) in addition to the latest-equivalent tags (`latest`, `safe`, `finalized`, `pending`). A past height is served from the EVM state store, so it requires a node that keeps state history (a full node, not a validator) and fails once that height is pruned. A block hash, or a height above the current head, returns an error. `eth_call` still accepts only the latest-equivalent tags; an explicit height, a block hash, or `earliest` returns an error, because calls do not run against historical state. + ```ts viem diff --git a/evm/evm-parity/gas-and-fees.mdx b/evm/evm-parity/gas-and-fees.mdx index ae89c51d..190e9741 100644 --- a/evm/evm-parity/gas-and-fees.mdx +++ b/evm/evm-parity/gas-and-fees.mdx @@ -61,6 +61,16 @@ For dynamic-fee (type 2) transactions, the `effectiveGasPrice` field of the tran In practice, when your priority tip plus the base fee stays below `maxFeePerGas`, the receipt reports `baseFee + maxPriorityFeePerGas`, not `maxFeePerGas`. To compute what a transaction paid, use the receipt's `effectiveGasPrice`, not `maxFeePerGas`. + +### Admission is priced on effective gas price + +Transaction admission at `CheckTx` compares a transaction's **effective gas price** against the minimum gas price, not its fee cap. For a dynamic-fee (type 2) transaction the effective gas price is `min(baseFee + maxPriorityFeePerGas, maxFeePerGas)`, which at a zero base fee reduces to `maxPriorityFeePerGas` (the tip). + +As a result, a dynamic-fee transaction with a high `maxFeePerGas` but a low or zero `maxPriorityFeePerGas` is rejected at admission, even though its fee cap would clear the floor. Admission is priced on the same quantity block validity uses, so a transaction that was admitted on its fee cap alone would later be refused by the executor. + +When setting fees for a dynamic-fee transaction, make sure `maxPriorityFeePerGas` alone (not just `maxFeePerGas`) meets the minimum gas price. A transaction that fails this check is rejected with an `effective gas price is below` error. + + ## SSTORE cost On Sei, governance can adjust the gas cost of `SSTORE` (a write to contract storage). The current cost is **72,000 gas** on both Sei Mainnet and Sei Testnet. For details, see [Differences with Ethereum](/evm/differences-with-ethereum#sstore-gas-cost). Treat this number as the current value, not a constant. Do not hard-code storage write estimates in your application. @@ -101,6 +111,8 @@ Sei precompiles charge gas based on the work that each call does: - The pointer view precompile also charges for the state that each lookup reads. - The P256 precompile also charges a fixed 3,450 gas per verification, the same as RIP-7212 `P256VERIFY`. If the call cannot pay it, the call fails with an out-of-gas error. +When a dynamic-gas precompile (such as JSON, P256, or pointer view) runs out of gas partway through execution, the out-of-gas condition fails as a standard EVM out-of-gas call (#4318): it fails only that EVM call frame rather than the whole transaction. The frame's gas is fully consumed, any state changes it made are reverted, and the enclosing frame is free to continue. The transaction completes as a normal failed EVM execution: it produces a failed EVM receipt carrying the real gas used and effective gas price, and the sender is charged for exactly the gas consumed. + Because the cost depends on your calldata, do not hard-code gas limits for precompile calls. Use `eth_estimateGas`, as shown in the example above. ## Summary diff --git a/evm/evm-parity/transaction-types.mdx b/evm/evm-parity/transaction-types.mdx index 6ba48fff..1f5e4793 100644 --- a/evm/evm-parity/transaction-types.mdx +++ b/evm/evm-parity/transaction-types.mdx @@ -46,6 +46,18 @@ Sei runs the Pectra hardfork without blob transaction support. If you try to sen If you port code from Ethereum that uses blob transactions (for example, for rollup data availability), that code path does not apply to Sei. + +### Blob transaction validation limits + +Beyond RPC-level rejection, blob (EIP-4844) transaction validation enforces EIP-4844 structural limits. A blob transaction is rejected during validation if any of the following hold: + +- It carries more than 6 blob hashes, or a sidecar with more than 6 blobs, commitments, or proofs. +- The sidecar's blob, commitment, and proof counts do not all match each other. +- The number of blob hashes does not match the number of sidecar blobs. +- Any sidecar blob, commitment, or proof does not have the exact fixed KZG byte length. + +If you construct blob-shaped transactions, these checks reject malformed or oversized blob transactions before they can be processed. + ## Sending transactions Standard library defaults work correctly. viem, wagmi, and ethers all default to type 2 (EIP-1559) transactions on chains that support EIP-1559, and Sei does. diff --git a/evm/evm-parity/websocket.mdx b/evm/evm-parity/websocket.mdx index 9795ae70..acd820a3 100644 --- a/evm/evm-parity/websocket.mdx +++ b/evm/evm-parity/websocket.mdx @@ -111,6 +111,38 @@ const unwatch = client.watchEvent({ - Sei has instant finality, so every block emitted over WebSocket is already final. You do not need to wait for more confirmations before you act on an event. - Sei does not support `newPendingTransactions` subscriptions. You can subscribe only to `newHeads` and `logs`. +- `newHeads` notifications include a Sei-specific `milliTimestamp` field alongside the standard seconds-based `timestamp`. It carries the header time as a hex quantity of Unix milliseconds, giving sub-second precision that the seconds-based `timestamp` cannot, since Sei commits blocks faster than once a second and `timestamp` repeats across consecutive blocks. This field is present under both Autobahn and CometBFT consensus. Note that `milliTimestamp` is not guaranteed unique per block under Autobahn, where consecutive blocks may be spaced less than a millisecond apart. + + +## `logs` subscription behavior + +A `logs` subscription polls for matching logs from a cursor that is fixed when the subscription is created. Where that cursor starts depends on the filter's `fromBlock`: + +- A numeric `fromBlock` is used as given. A `fromBlock` in the past makes the subscription's first poll return that history. A numeric `fromBlock` above 0 that is below the earliest available (non-pruned) block is rejected when the subscription is created, with an error such as `requested fromBlock 1 is before earliest available block 2`. A `fromBlock` of 0 (or `earliest`) polls from the earliest available block and is never rejected. +- An omitted or tag `fromBlock` (such as `latest`, `safe`, `finalized`, or `pending`) starts the cursor at the block after the head at creation time, so the subscription delivers only new logs and never replays the block that was the head when it was created. +- A `fromBlock` of 0 paired with a tag `toBlock` — what `ethclient` sends for an open-ended query — is treated as an omitted `fromBlock`, so the subscription starts after the head rather than resolving to the current latest block. + +Each poll scans from the cursor to the head (or to a numeric `toBlock` below the head), covering at most `max_blocks_for_log` blocks per poll; any remaining blocks are returned by later polls. A tag `toBlock` such as `latest` follows the head and never ends the subscription. + +Unlike `eth_getLogs`, `eth_getFilterLogs`, and `eth_getFilterChanges`, subscription polls are not subject to the shared log-query admission (rate-limit tokens for large ranges and worker-queue/DB-semaphore load shedding). A subscription poll is never refused with the `-32005` (limit exceeded, retry later) code, so load or rate limiting cannot end a subscription. A historical `fromBlock` still makes each poll scan up to `max_blocks_for_log` blocks until the subscription catches up to the head. + +### Error notifications + +When a poll fails, the subscription sends a notification containing a JSON object in place of logs: + +```json +{ "error": "" } +``` + +If a poll reaches a block whose matching logs alone exceed the node's log caps, that single poll fails, but the subscription continues past the block instead of wedging on it. In that case the error notification also includes the skipped block's number: + +```json +{ "error": "logs of block 42 skipped: query matches too many logs", "blockNumber": "0x2a" } +``` + +Any other failure ends the subscription after sending its `{ "error": "" }` notification. + + ## Frame size and concurrency limits WebSocket connections use the same request limits as HTTP JSON-RPC. Operators set them in the `[evm]` section of `app.toml`: diff --git a/evm/installing-seid-cli.mdx b/evm/installing-seid-cli.mdx index f30f1350..d47c317b 100644 --- a/evm/installing-seid-cli.mdx +++ b/evm/installing-seid-cli.mdx @@ -22,12 +22,15 @@ To install `seid`, find the version that you want on the [sei-chain releases pag - Each release attaches a statically linked `seid` build for `linux/amd64` with no - runtime dependencies: + Each release attaches statically linked `seid` builds for `linux/amd64` and + `linux/arm64` with no runtime dependencies: ```bash VERSION= # e.g. v6.6.1 — see the version table above - FILE=sei-chain_${VERSION#v}_linux_x86_64.tar.gz # asset filenames omit the leading v + # Pick the asset matching your architecture (asset filenames omit the leading v): + # linux_x86_64 for linux/amd64 + # linux_aarch64 for linux/arm64 + FILE=sei-chain_${VERSION#v}_linux_x86_64.tar.gz curl -fLO https://github.com/sei-protocol/sei-chain/releases/download/${VERSION}/${FILE} curl -fLO https://github.com/sei-protocol/sei-chain/releases/download/${VERSION}/checksums.txt @@ -39,9 +42,11 @@ To install `seid`, find the version that you want on the [sei-chain releases pag ``` - Prebuilt binaries are attached from `v6.6.1` onward. For earlier versions, build - from source. The binaries are `linux/amd64` only and omit hardware Ledger support. - On other architectures, or if you sign with a Ledger device, build from source. + Prebuilt binaries are attached from `v6.6.1` onward. The `linux/arm64` + (`linux_aarch64`) build is published alongside `linux/amd64` since v6.8.0. For + earlier versions, or for other architectures, build from source. The prebuilt + binaries omit hardware Ledger support, so if you sign with a Ledger device, build + from source. @@ -113,7 +118,6 @@ Available Commands: start Run the full node status Query remote node for status tendermint Tendermint subcommands - tools A set of useful tools for sei chain tx Transactions subcommands validate-genesis validates the genesis file at the default location or at the location passed as an arg version Print the application binary version information diff --git a/evm/precompiles/auth.mdx b/evm/precompiles/auth.mdx index 4a900567..dbde93ed 100644 --- a/evm/precompiles/auth.mdx +++ b/evm/precompiles/auth.mdx @@ -6,7 +6,7 @@ keywords: ['auth precompile', 'account query', 'account number', 'account sequen --- **Address:** `0x000000000000000000000000000000000000100D` -The Auth precompile reads data from the Cosmos `auth` module: account details, module parameters, and the next account number. All methods are `view` functions. The precompile is available since v6.7.0. +The Auth precompile reads data from the Cosmos `auth` module: account details, module parameters, and the next account number. All methods are `view` functions. The versioned Auth precompile is available as of the v6.8 chain upgrade, with a v6.7 legacy registration retained for historical calls. ## Interface diff --git a/evm/precompiles/authz.mdx b/evm/precompiles/authz.mdx index 02311d95..7db70ca8 100644 --- a/evm/precompiles/authz.mdx +++ b/evm/precompiles/authz.mdx @@ -6,7 +6,7 @@ keywords: ['authz precompile', 'authorization grants', 'granter', 'grantee', 'se --- **Address:** `0x000000000000000000000000000000000000100E` -The Authz precompile reads grants from the Cosmos `authz` module. A grant lets a grantee account send specific messages for a granter account. All methods are `view` functions. The precompile is available since v6.7.0. +The Authz precompile reads grants from the Cosmos `authz` module. A grant lets a grantee account send specific messages for a granter account. All methods are `view` functions. The precompile is available since the v6.8 chain upgrade (#3618), which registers the versioned Authz precompile alongside the v6.7 legacy implementation. ## Interface diff --git a/evm/precompiles/cosmwasm-precompiles/bank.mdx b/evm/precompiles/cosmwasm-precompiles/bank.mdx index d73913c7..0da93dc0 100644 --- a/evm/precompiles/cosmwasm-precompiles/bank.mdx +++ b/evm/precompiles/cosmwasm-precompiles/bank.mdx @@ -11,6 +11,10 @@ keywords: ['bank precompile', 'native sei', 'ethers.js', 'balance query', 'sei d Do not use the Bank precompile as an IBC or tokenfactory integration path. This page covers native SEI (`usei`) only. IBC is disabled in both directions. Tokenfactory is not supported for new development. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Tokenfactory is not supported](/cosmos-sdk#tokenfactory-is-not-supported). + +The bank module's `factory/` denom transfer allowlist enforcement was removed with the v6.8 upgrade (#4536). Denoms that previously restricted transfers through an allowlist now transfer freely, and the send/receive allowlist checks are gone. Do not rely on allowlist behavior to gate `factory/` denom transfers through this precompile. + + The Bank precompile exposes the Bank Module balance for native SEI. It also lets an EVM caller send SEI to a native `sei1...` address. ## Functions @@ -139,7 +143,7 @@ Validate the recipient before you send SEI. A successful transaction cannot be r ## Other query methods -The Bank precompile also has the read-only queries below. All of them except `supply` are available since v6.7.0. +The Bank precompile also has the read-only queries below. `supply` has been available since earlier releases; the remaining query methods (`spendableBalances`, `totalSupply`, `params`, `denomMetadata`, `denomsMetadata`) are available on the bank precompile version registered for the v6.8 upgrade (#diff adds the v6.8 bank precompile and v6.7 legacy registration). ```solidity function supply(string memory denom) external view returns (uint256 response); @@ -183,7 +187,7 @@ struct Metadata { } ``` -`supply(denom)` returns the supply of one denomination. `totalSupply(pageKey)` returns the supply of every denomination, one page at a time. For paginated methods, pass empty bytes (`0x`) for the first page, then pass the returned `nextKey`. An empty `nextKey` means there are no more pages. `spendableBalances` reverts if `acc` has no associated Sei address. +`supply(denom)` returns the supply of one denomination. `totalSupply(pageKey)` returns the supply of every denomination, one page at a time. For paginated methods, pass empty bytes (`0x`) for the first page, then pass the returned `nextKey`. An empty `nextKey` means there are no more pages. `spendableBalances` resolves `acc` directly, so it also returns balances for unassociated (uncast) EVM addresses that have no associated Sei address (#4). `BANK_PRECOMPILE_ABI` in `@sei-js/precompiles@3` does not include `spendableBalances`, `totalSupply`, `params`, `denomMetadata`, or `denomsMetadata`. Call them with an ABI fragment: diff --git a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx index 41ce914d..a95ff43b 100644 --- a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx +++ b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx @@ -9,7 +9,7 @@ keywords: ['cosmwasm precompile', 'ethers.js', 'wasm execution', 'cross-chain co **Deprecation notice (Prop 115)** - Under [governance Proposal 115](https://seistream.app/proposals/115), CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) are disabled chain-wide. The `instantiate()` function on this precompile **reverts** for all callers. Only calls to `execute()`, `execute_batch()`, and `query()` against pre-existing CosmWasm contracts still work. All CosmWasm functionality is deprecated in favor of EVM-only under [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md). + Under [governance Proposal 115](https://seistream.app/proposals/115), CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) are disabled chain-wide. The `instantiate()` function on this precompile **reverts** for all callers. The `execute_batch()` function is also **disabled** at the precompile level and fails with the error `wasmd execute_batch is disabled`; use single `execute()` calls instead. Only calls to `execute()` and `query()` against pre-existing CosmWasm contracts still work. All CosmWasm functionality is deprecated in favor of EVM-only under [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md). The examples on this page attach only native SEI. Do not use the `coins` field to build IBC or tokenfactory integrations. IBC is disabled in both directions. Tokenfactory is not a supported development path. @@ -440,6 +440,21 @@ contract CosmWasmQuery { **Query limitations:** Consider parsing responses off-chain. CosmWasm queries are read-only operations and do not consume gas. However, parsing JSON responses in Solidity is complex. + + +## Governance kill switches for contract execution + +Governance can halt CosmWasm contract execution in stages through two wasm module parameters, each settable with a param-change proposal against the `wasm` subspace. Both default to `false`. + +| Parameter | Subspace key | Effect on this precompile | +| --- | --- | --- | +| `contract_execution_disabled` | `contractExecutionDisabled` | When `true`, no contract runs from any origin, including the EVM wasmd precompile. Calls to `execute()` and `instantiate()` **revert**; `query()` still works. | +| `msg_execute_contract_disabled` | `msgExecuteContractDisabled` | When `true`, every `MsgExecuteContract` fails, but contract calls that go through the EVM wasmd precompile are **not** affected, so `execute()` on this precompile keeps working. | + +When `contract_execution_disabled` is set, `execute()` and `instantiate()` through this precompile revert with the wasm error `ErrContractExecutionDisabled` (codespace `wasm`, code `32`). Direct `MsgExecuteContract` transactions blocked by `msg_execute_contract_disabled` fail with `ErrMsgExecuteContractDisabled` (codespace `wasm`, code `31`); that param leaves the precompile path open, so only `contract_execution_disabled` stops execution here. + + Because `msg_execute_contract_disabled` does not apply to precompile calls, use `contract_execution_disabled` if you need to halt contract execution reaching CosmWasm through the EVM. Queries remain available under both parameters. + ## Advanced usage examples ### Cross-runtime DeFi integration diff --git a/evm/precompiles/cosmwasm-precompiles/example-usage.mdx b/evm/precompiles/cosmwasm-precompiles/example-usage.mdx index 2409fae8..efbf9c34 100644 --- a/evm/precompiles/cosmwasm-precompiles/example-usage.mdx +++ b/evm/precompiles/cosmwasm-precompiles/example-usage.mdx @@ -13,6 +13,10 @@ You can use the Sei precompiles like any standard smart contract on the EVM. For example, this page uses [ethers.js](https://docs.ethers.org/v6/) to query an existing CosmWasm contract and execute actions on it. + +The `execute_batch` method on the CosmWasm precompile is disabled and now reverts with the error `wasmd execute_batch is disabled`. Only single `execute` and `query` calls are supported. Integrations that previously batched multiple CosmWasm executions in a single call must send each execution individually. + + ## Setup To install `ethers`, run this command in a terminal in your project directory: diff --git a/evm/precompiles/distribution.mdx b/evm/precompiles/distribution.mdx index 5678f776..af3cebce 100644 --- a/evm/precompiles/distribution.mdx +++ b/evm/precompiles/distribution.mdx @@ -425,6 +425,70 @@ contract ValidatorManager { ## Error handling + +## v6.8 query and authorization methods + +The v6.8 chain upgrade (#) expands the distribution precompile with read-only query methods and authorization-based withdrawal methods. The query methods run on a branched context and discard any state writes, so they are safe views even though the underlying distribution queriers can have side effects. + +### Interface additions + +```solidity +interface IDistr { + struct DistributionParams { + string communityTax; + string baseProposerReward; + string bonusProposerReward; + bool withdrawAddrEnabled; + } + + struct Slash { + uint64 validatorPeriod; + string fraction; + } + + // Query methods + function communityPool() external view returns (Coin[] memory pool); + function params() external view returns (DistributionParams memory params); + function validatorOutstandingRewards(string memory validatorAddress) external view returns (Coin[] memory rewards); + function validatorCommission(string memory validatorAddress) external view returns (Coin[] memory commission); + function validatorSlashes(string memory validatorAddress, uint64 startingHeight, uint64 endingHeight, bytes memory pageKey) external view returns (Slash[] memory slashes, bytes memory nextKey); + function delegationRewards(address delegatorAddress, string memory validatorAddress) external view returns (Coin[] memory rewards); + function delegatorValidators(address delegatorAddress) external view returns (string[] memory validators); + function delegatorWithdrawAddress(address delegatorAddress) external view returns (string memory withdrawAddress); + + // Authorization methods + function grantWithdrawAuthorization(address grantee, int64 expiration) external returns (bool success); + function revokeWithdrawAuthorization(address grantee) external returns (bool success); + function withdrawDelegationRewardsWithAuthorization(address delegator, string memory validator) external returns (bool success); + function withdrawValidatorCommissionWithAuthorization(address validatorOperator) external returns (bool success); +} +``` + +### Query methods + +- **`communityPool()`** — Returns the current community pool balances as an array of `Coin` (18-decimal `DecCoins`, with `decimals` set to 18). +- **`params()`** — Returns the distribution module parameters: `communityTax`, `baseProposerReward`, `bonusProposerReward` (decimal strings), and `withdrawAddrEnabled`. +- **`validatorOutstandingRewards(validatorAddress)`** — Returns the outstanding (not-yet-withdrawn) rewards accrued to a validator, as `Coin[]`. +- **`validatorCommission(validatorAddress)`** — Returns the accumulated commission for a validator, as `Coin[]`. +- **`validatorSlashes(validatorAddress, startingHeight, endingHeight, pageKey)`** — Returns the paginated slash events for a validator within a block height range. `startingHeight` and `endingHeight` are block heights (inclusive on both ends), not validator periods — slash events are filtered by the block height at which they occurred. Each `Slash` contains the `validatorPeriod` and the slash `fraction` (a decimal string). Pass an empty `pageKey` for the first page and use the returned `nextKey` to page forward. +- **`delegationRewards(delegatorAddress, validatorAddress)`** — Returns the pending rewards for a single delegation, as `Coin[]`. +- **`delegatorValidators(delegatorAddress)`** — Returns the list of validator addresses a delegator is currently delegating to. +- **`delegatorWithdrawAddress(delegatorAddress)`** — Returns the delegator's configured withdrawal address in Sei bech32 form. + +As with `rewards()`, the reward and pool query methods return amounts with 18-decimal precision (`DecCoins`). Divide by `1e18` for display. Withdrawn amounts remain 6-decimal (usei). + +### Authorization methods + +These methods let a granter authorize another account (the grantee) to withdraw rewards and commission on its behalf, using the native Cosmos authz module. Each EVM-facing permission is backed by one native grant per message type. + +- **`grantWithdrawAuthorization(grantee, expiration)`** — Grants the `grantee` authorization to withdraw delegation rewards and validator commission on behalf of the caller. `expiration` is a Unix timestamp (seconds) and must be after the current block time. +- **`revokeWithdrawAuthorization(grantee)`** — Revokes a previously granted withdraw authorization for the `grantee`. +- **`withdrawDelegationRewardsWithAuthorization(delegator, validator)`** — Withdraws the `delegator`'s delegation rewards from `validator`, executed by the caller under a prior authorization. Emits `DelegationRewardsWithdrawn` with the withdrawn amount. +- **`withdrawValidatorCommissionWithAuthorization(validatorOperator)`** — Withdraws the commission for `validatorOperator`, executed by the caller under a prior authorization. Emits `ValidatorCommissionWithdrawn`. + +The authorized withdrawal methods share the same event and output path as the direct `withdrawDelegationRewards` and `withdrawValidatorCommission` methods; the difference is that execution is routed through the native authz module so the grant is consumed normally. + + This example shows common error scenarios and how to handle them: ```solidity diff --git a/evm/precompiles/evidence.mdx b/evm/precompiles/evidence.mdx index dcb6ea53..6421231d 100644 --- a/evm/precompiles/evidence.mdx +++ b/evm/precompiles/evidence.mdx @@ -6,7 +6,7 @@ keywords: ['evidence precompile', 'equivocation', 'validator misbehavior', 'sei --- **Address:** `0x000000000000000000000000000000000000100F` -The Evidence precompile reads the evidence of validator misbehavior that the Cosmos `evidence` module recorded. All methods are `view` functions. The precompile is available since v6.7.0. +The Evidence precompile reads the evidence of validator misbehavior that the Cosmos `evidence` module recorded. All methods are `view` functions. The precompile is registered as a versioned precompile with both `v6.7` and `v6.8` versions available. ## Interface diff --git a/evm/precompiles/example-usage.mdx b/evm/precompiles/example-usage.mdx index a2929d61..b900c6ef 100644 --- a/evm/precompiles/example-usage.mdx +++ b/evm/precompiles/example-usage.mdx @@ -19,8 +19,8 @@ Sei precompiles are special smart contracts deployed at fixed addresses. They ex | Staking | `0x0000000000000000000000000000000000001005` | Delegation and staking operations | | Governance | `0x0000000000000000000000000000000000001006` | Proposal voting | | Distribution | `0x0000000000000000000000000000000000001007` | Claim staking rewards | -| Pointer view | `0x000000000000000000000000000000000000100A` | Look up pointer contract addresses | -| Pointer | `0x000000000000000000000000000000000000100B` | Register pointer contracts | +| Pointer view | `0x000000000000000000000000000000000000100A` | Look up pointer contract addresses (lookups still work) | +| Pointer | `0x000000000000000000000000000000000000100B` | Pointer creation is retired. The address stays registered with its ABI, but every `add*` method (`addNativePointer`, `addCW20Pointer`, `addCW721Pointer`, `addCW1155Pointer`) reverts with `pointer precompile is retired; EVM pointer creation is disabled`. | | Solo | `0x000000000000000000000000000000000000100C` | Claim Solo migration payloads | | Auth | `0x000000000000000000000000000000000000100D` | Query accounts, auth parameters, and the next account number | | Authz | `0x000000000000000000000000000000000000100E` | Query authz grants | diff --git a/evm/precompiles/governance.mdx b/evm/precompiles/governance.mdx index f76a95e6..0f16f326 100644 --- a/evm/precompiles/governance.mdx +++ b/evm/precompiles/governance.mdx @@ -32,11 +32,26 @@ Sei governance follows a structured timeline with specific parameters: 1. **Proposal submission:** Submit a proposal with a minimum deposit of 3,500 SEI. 2. **Deposit period:** The proposal has 2 days to accumulate the minimum deposit or reach the expedited threshold. -3. **Voting period:** When the proposal meets the minimum deposit, voting is active for 3 days (1 day for expedited proposals). -4. **Tallying:** The results are calculated from the quorum and voting thresholds. +3. **Voting period:** When the proposal meets the minimum deposit, voting is active for 3 days (1 day for expedited proposals). Once a proposal's voting end time is reached, its electorate is frozen: new votes and deposits are rejected with `ErrInactiveProposal`. +4. **Tallying:** The results are calculated from the quorum and voting thresholds. From the v6.8 upgrade, tallying is incremental — work is bounded per block and a proposal's result may be computed across several blocks rather than in a single end-of-period pass. Before activation, legacy single-pass tallying is preserved. + + +**v6.8 incremental tally changes:** From the v6.8 upgrade, governance uses a bounded, incremental tally: + +- Votes and deposits are rejected once a proposal's voting end time is reached or its electorate snapshot is frozen (`ErrInactiveProposal`), rather than being accepted up to the final tally. +- Casting a vote that creates a new deferred tally record consumes additional gas (`DeferredVoteTallyGas`), so budget extra gas for first-time votes on a proposal. +- When an expedited proposal fails and is converted to a regular proposal, the regular round resumes for the remaining window (`VotingPeriod - ExpeditedVotingPeriod`) measured from the conversion time, instead of restarting the full regular voting period from the original voting start time. + To learn more about the governance process on Sei, read the [governance explainer](/learn/general-governance). + + +**Deferred deposit settlement:** When a proposal finishes — either because it fails to meet the minimum deposit within the deposit period, or because voting ends — its deposits are no longer burned or refunded all at once in the same block. Settlement is scheduled and processed incrementally across subsequent blocks, bounded by a per-block budget of up to 1000 deposit records (`MaxDepositsSettledPerBlock`). As a result, there may be a short delay between when a proposal ends and when depositors actually receive their refunds or when burned deposits leave the governance module balance. For proposals with many deposit records, settlement can span several blocks. + +A deposit whose depositor cannot receive funds (for example, a blocked address) remains recorded and stays backed by the governance module balance rather than being refunded. + + **Critical Sei Mainnet considerations:** @@ -101,6 +116,72 @@ function submitProposal( ) payable external returns (uint64 proposalID); ``` + +### Authorization-based functions + +In addition to acting directly, the governance precompile supports [authz](https://docs.cosmos.network/main/build/modules/authz)-style grants so one account (the grantee) can vote or submit proposals on behalf of another account (the granter). Grants are scoped per message type and expire at a Unix timestamp. + +```solidity +/// Grant another account authorization to vote on your behalf. +/// @param grantee The account receiving the authorization. +/// @param expiration Unix timestamp (seconds) at which the grant expires. +/// @return success Whether the authorization was granted. +function grantVoteAuthorization( + address grantee, + int64 expiration +) external returns (bool success); + +/// Grant another account authorization to submit proposals on your behalf. +/// @param grantee The account receiving the authorization. +/// @param expiration Unix timestamp (seconds) at which the grant expires. +/// @return success Whether the authorization was granted. +function grantProposalAuthorization( + address grantee, + int64 expiration +) external returns (bool success); + +/// Revoke a previously granted vote authorization. +/// @param grantee The account whose authorization is being revoked. +/// @return success Whether the authorization was revoked. +function revokeVoteAuthorization( + address grantee +) external returns (bool success); + +/// Revoke a previously granted proposal authorization. +/// @param grantee The account whose authorization is being revoked. +/// @return success Whether the authorization was revoked. +function revokeProposalAuthorization( + address grantee +) external returns (bool success); + +/// Cast a vote on behalf of a voter who granted you a vote authorization. +/// The caller must be the grantee; the vote is recorded for `voter`. +/// @param voter The granter on whose behalf the vote is cast. +/// @param proposalID The ID of the proposal to vote on. +/// @param option The option to vote for. (1=Yes, 2=Abstain, 3=No, 4=NoWithVeto) +/// @return success Whether the vote was successfully cast. +function voteWithAuthorization( + address voter, + uint64 proposalID, + int32 option +) external returns (bool success); + +/// Submit a proposal on behalf of a proposer who granted you a proposal +/// authorization. The caller must be the grantee; the proposal is recorded +/// for `proposer`. Any initial deposit is provided via msg.value. +/// @param proposer The granter on whose behalf the proposal is submitted. +/// @param proposalJSON JSON string containing proposal details. +/// @return proposalID The ID of the created proposal. +function submitProposalWithAuthorization( + address proposer, + string calldata proposalJSON +) payable external returns (uint64 proposalID); +``` + + +Authorization grants are scoped by message type: `grantVoteAuthorization` authorizes only votes, and `grantProposalAuthorization` authorizes only proposal submissions. Grant and revoke each type independently. A grant must have an `expiration` in the future, and `voteWithAuthorization` / `submitProposalWithAuthorization` fail if no matching, unexpired grant exists for the caller. + + ### Query functions Use these read-only methods to read proposal state from a contract. The vote and deposit queries are `getVote` and `getDeposit`, because the transactions already use the names `vote` and `deposit`. Tools such as ethers.js do not handle overloaded function names well. @@ -203,6 +284,9 @@ function deposits( ) external view returns (DepositData[] memory deposits, bytes memory nextKey); /// Query the current tally of votes on a proposal +/// For proposals in the Passed, Rejected, or Failed state this returns the +/// stored FinalTallyResult; proposals still in the deposit period return an +/// empty tally. function tallyResult( uint64 proposalID ) external view returns (TallyResultData memory tallyResult); @@ -724,6 +808,16 @@ const additionalDeposit = ethers.parseUnits('1000', 18); // 1,000 SEI await addDepositToProposal(proposalID, additionalDeposit); ``` + + +**Deposit denom validation (incremental tally):** When incremental tally is enabled, deposits are validated against the proposal's minimum deposit denoms: + +- A deposit may only contain denoms that are a subset of the proposal's minimum deposit denoms. If it includes any other denom, the deposit is rejected with `ErrInvalidCoins`. +- An empty deposit is silently ignored — no deposit record is created and no error is returned. + +In practice, deposit to a Sei governance proposal using SEI (the chain's bond denom), which is part of the minimum deposit set. A deposit carrying an unrelated denom will fail. + + ## Complete integration example Create a script that interacts with the governance precompile: diff --git a/evm/precompiles/json.mdx b/evm/precompiles/json.mdx index 05f2d75a..04c4abcf 100644 --- a/evm/precompiles/json.mdx +++ b/evm/precompiles/json.mdx @@ -703,6 +703,8 @@ async function handleMissingKeys(jsonPrecompile: ethers.Contract, data: any) { | `invalid integer` | Non-numeric value for `extractAsUint256` | Make sure that the value is a valid integer | | `out of gas` | Insufficient gas for large JSON | Use `calculateGasLimit()` for dynamic estimation | +**Out-of-gas behavior:** Because the JSON precompile charges gas dynamically based on input size, a call that exhausts its gas mid-execution now fails only the EVM call frame with an out-of-gas error — its state changes are reverted and its remaining gas is zeroed, exactly like a regular contract call that runs out of gas. The enclosing transaction completes as a normal failed EVM execution, carrying the real gas used and effective gas price on its receipt, and the sender is charged for exactly that gas. The whole transaction no longer fails at the Cosmos layer with a zero-gas receipt. + ## Key considerations and tricks diff --git a/evm/precompiles/p256-precompile.mdx b/evm/precompiles/p256-precompile.mdx index b39b8c1d..46b6a288 100644 --- a/evm/precompiles/p256-precompile.mdx +++ b/evm/precompiles/p256-precompile.mdx @@ -164,7 +164,7 @@ Total length: 160 bytes Each verification costs a fixed 3,450 gas, the same as the RIP-7212 `P256VERIFY` precompile. This cost is much lower than the cost of P-256 verification in Solidity. Like every Sei precompile, the call also pays a charge for its calldata. For details, see [Gas for precompile calls](/evm/evm-parity/gas-and-fees#gas-for-precompile-calls). -The precompile charges for the calldata first. Then it charges the 3,450 gas, and then it checks the signature. If the call cannot pay the calldata charge, it reverts. If the call cannot pay the 3,450 gas, it fails with an out-of-gas error and does not revert. +The precompile charges for the calldata first. Then it charges the 3,450 gas, and then it checks the signature. If the call cannot pay the calldata charge, it reverts. If the call cannot pay the 3,450 gas, the call frame fails with an out-of-gas error (`vm.ErrOutOfGas`): it consumes all remaining frame gas and reverts any state the frame touched, just like a normal failed EVM execution. The enclosing transaction is not aborted at the Cosmos layer — it completes with a failed EVM receipt that carries the real gas used and effective gas price, and the sender is charged for exactly that gas. ## Real-world use cases diff --git a/evm/precompiles/params.mdx b/evm/precompiles/params.mdx index 6c707bc0..353b7795 100644 --- a/evm/precompiles/params.mdx +++ b/evm/precompiles/params.mdx @@ -27,6 +27,8 @@ interface IParams { | Method | Returns | | --- | --- | -| `params(subspace, key)` | The value of the parameter `key` in `subspace`, as a JSON string. For example, `params("staking", "MaxValidators")` returns the maximum number of validators. | +| `params(subspace, key)` | The value of the parameter `key` in `subspace`, amino-JSON encoded. For example, `params("staking", "MaxValidators")` returns the maximum number of validators. | + +The returned value is amino-JSON encoded, so string and decimal values keep their surrounding quotes (for example, `"0.020000000000000000"`). The call reverts if `subspace` or `key` is empty, or if `subspace` does not exist. If `key` does not exist in `subspace`, the call returns an empty string. diff --git a/evm/precompiles/staking.mdx b/evm/precompiles/staking.mdx index ff85ce34..9b40a104 100644 --- a/evm/precompiles/staking.mdx +++ b/evm/precompiles/staking.mdx @@ -405,10 +405,12 @@ function delegatorUnbondingDelegations( bytes memory nextKey ) external view returns (UnbondingDelegationsResponse memory response); -/// Get redelegations with optional filters -/// @param delegator The delegator's address (empty string for all) -/// @param srcValidator The source validator address (empty string for all) -/// @param dstValidator The destination validator address (empty string for all) +/// Get redelegations. Only specific filter combinations are supported: +/// delegator, srcValidator and dstValidator together; srcValidator alone; or +/// delegator alone. Any other combination reverts with "unsupported redelegations filter". +/// @param delegator The delegator's address, or empty when filtering by srcValidator alone +/// @param srcValidator The source validator address, or empty when filtering by delegator alone +/// @param dstValidator The destination validator address, set only together with delegator and srcValidator /// @param nextKey Pagination key /// @return response Redelegations response with pagination function redelegations( diff --git a/evm/reference.mdx b/evm/reference.mdx index 49b295ac..fc220467 100644 --- a/evm/reference.mdx +++ b/evm/reference.mdx @@ -49,6 +49,12 @@ All endpoints follow the standard JSON-RPC format: + + + +**Rate-limited rejections (HTTP 429).** When a POST request is rejected by rate limiting, the response shape mirrors the request shape. A rate-limited valid batch POST (an array of requests within the batch size limit) returns a JSON array of `too many requests` error objects — one per non-notification request — preserving each request's `id`. A batch of only notifications returns an empty response body, just as it would when served normally. A single (non-batch) request returns a single error object carrying that request's `id`. Oversized batches (above the request batch size limit) and malformed batches still return a single error object. + + ### Network endpoints | Network | EVM chain ID | HTTP endpoint | WebSocket endpoint | @@ -68,6 +74,26 @@ curl -s $SEI_TENDERMINT_RPC/status | jq '.result.sync_info.last_committed_block_ The field is serialized to JSON as a string (`last_committed_block_height`), like the other height fields in `SyncInfo`. + + +### ABCI `/store` state proofs disabled by default + + +ABCI `/store` proof queries (requests that set `prove=true`) are deprecated and **disabled by default** since v6.8 (#4573). A node that has not opted in rejects such a query with an `ErrNotSupported` error (ABCI code `37`) and the log `state proofs are disabled on this node; set state-commit.sc-enable-state-proof = true to enable`, instead of returning proof ops. This is a deprecation step before the proof code is removed in a later release. + +This affects any ABCI client that sends `prove=true`, including light clients (which always request a proof) and `sei-cosmos/client` queries with `Prove` set. Only requests that would produce a proof are rejected; the same query without `prove=true` is served normally, and a `/subspace` query that asks for a proof is still served unproven. + +Operators who need to keep serving state proofs (for example, to support light clients) must opt in after upgrading by setting `sc-enable-state-proof = true` in the `[state-commit]` section of `app.toml`: + +```toml +[state-commit] +# Enable deprecated ABCI /store state proofs. Disabled by default; this option will be removed with the proof code in a later release. +sc-enable-state-proof = true +``` + +Each rejected proof query increments the `state_proof_rejected` metric, labeled by store and by whether the query was at the latest height. + + | Field | JSON | Description | | :- | :- | :- | | `last_committed_block_height` | string | Height of the last block finalized by consensus. | @@ -85,14 +111,31 @@ Under Autobahn (`AutobahnConfigFile` set), the CometBFT block store is not popul ### Tendermint block and validator endpoints under Autobahn + +Setting `autobahn-config-file` now makes the node serve the EVM JSON-RPC only; it no longer serves Tendermint RPC. When Autobahn is enabled the node runs the disk-backed EVM-only executor (unless `mock-app` is set), and the Cosmos evmrpc HTTP and WebSocket servers are not started. The EVM-only JSON-RPC surface answers transaction submission, receipt, balance, nonce, code, storage, and log queries (`eth_sendRawTransaction`, `eth_getTransactionReceipt`, `eth_getBalance`, `eth_getTransactionCount`, `eth_getCode`, `eth_getStorageAt`, `eth_getLogs`); it also serves `eth_estimateGas` (the lowest gas limit that lets a message succeed against current committed state, with the same block-tag and revert behavior as `eth_call`), along with `eth_gasPrice` and `eth_feeHistory`. The state-read methods `eth_getBalance`, `eth_getTransactionCount`, `eth_getCode`, and `eth_getStorageAt` accept an explicit past block height or `earliest` in addition to the latest-equivalent tags (`latest`, `safe`, `finalized`, `pending`): a numbered height reads the state after that block, served from the EVM state store, and `earliest` reads block 0. Because a past height is served from the state store, it requires a node that keeps state history (a full node, not a validator), and fails once that height is pruned; a block hash, or a height above the current head, returns an error. `eth_call`, by contrast, remains restricted to the latest-equivalent tags — an explicit height, a block hash, or `earliest` returns an error, because calls do not run against historical state. It does not serve the full evmrpc surface (for example `debug_trace*` or the `sei_*` extensions). The EVM-only JSON-RPC listener binds on all interfaces (`0.0.0.0`) on a configurable TCP port set by `giga.execution.evm_rpc_port` in the `[giga.execution]` section (default `8545`, must be in the range `1..65535`). The same JSON-RPC methods are also served over WebSocket on a separate listener, also bound on all interfaces (`0.0.0.0`), on the port set by `giga.execution.evm_ws_port` in the `[giga.execution]` section (default `8546`, must be in the range `1..65535` and must differ from `evm_rpc_port`). The WebSocket listener accepts upgrades from any `Origin` and is bounded to 2000 concurrent connections. Over this WebSocket endpoint the EVM-only surface also serves `eth_subscribe("newHeads")`, pushing one Ethereum header per executed block; this subscription requires Autobahn execution and is unavailable on nodes that do not execute blocks through Autobahn. The Tendermint block, validator, and `/status` behavior described in the sections below applies to nodes that still run Tendermint RPC; validators configured for EVM-only JSON-RPC under Autobahn do not expose it. + + Under Autobahn (`AutobahnConfigFile` set), the CometBFT `BlockStore` and `StateStore` are not populated. These Tendermint RPC endpoints do not return empty or failing responses in this mode. Instead: - `/block` and `/block_by_hash` route through the GigaRouter's in-memory state (the finalized global blocks that the Autobahn data layer retains). -- `/block_results` and `/validators` synthesize their responses (an empty result set and the genesis committee, respectively). +- `/block_results` synthesizes an empty result set. +- `/validators` returns the committee that certified the requested global block. This keeps downstream consumers, including evmrpc, block explorers, and monitoring tools, working without each one branching on the consensus engine. -`/block` and `/block_by_hash` serve responses only for heights that are still inside Autobahn's retained window. Heights pruned per `RetainHeight` are no longer available. `/block_results` and `/validators` do not read the retained block data. They respond for any height up to the current ABCI head. Requests are validated against the current ABCI head, so heights above it return the same `ErrHeightExceedsChainHead`-class errors as the CometBFT path. Pruned heights on `/block` return `ErrHeightNotAvailable`. + + +### EVM return data and logs omitted from Cosmos result data + + +The Cosmos result data of an EVM transaction (`MsgEVMTransactionResponse`) no longer carries the transaction's return data or logs (#4577). Both fields are now left unset, so they no longer appear in `tx_response.data` or in the per-transaction `ExecTxResult` details (`TxsResults`) returned by the Tendermint `/block_results` endpoint for new transactions. The response still carries the transaction's `GasUsed`, `VmError`, and `Hash`. + +EVM RPC remains the authoritative source for this data: logs are served from the receipt store via `eth_getTransactionReceipt`, `eth_getBlockReceipts`, and the log methods (`eth_getLogs`, `eth_getFilterLogs`), and return data is obtained by re-executing the call through `eth_call`. Clients that previously read EVM logs or return data out of `tx_response.data` or `/block_results` must switch to these receipt- and call-based EVM RPC methods. + +Because omitting these fields changes the data that feeds the result hash, `LastResultsHash` differs from the v6.8 upgrade height onward. This is an app-hash/consensus-relevant change. + + +`/block` and `/block_by_hash` serve responses only for heights that are still inside Autobahn's retained window. Heights pruned per `RetainHeight` are no longer available. `/block_results` does not read the retained block data; it responds for any height up to the current ABCI head. Requests are validated against the current ABCI head, so heights above it return the same `ErrHeightExceedsChainHead`-class errors as the CometBFT path. Pruned heights on `/block` return `ErrHeightNotAvailable`. | Endpoint | Autobahn behavior | | :- | :- | @@ -105,6 +148,10 @@ This keeps downstream consumers, including evmrpc, block explorers, and monitori Because `FinalizeBlock` responses are not stored on disk under Autobahn, `/block_results` cannot return per-transaction execution results (`TxsResults` is empty). For per-transaction EVM data, use the EVM JSON-RPC methods `eth_getTransactionReceipt` and `eth_getBlockReceipts` instead. + +Even when `FinalizeBlock` responses are persisted, a response that serializes to more than 1 GiB is stored without block and transaction events and without transaction logs and infos; only the hashes and core results are preserved, and the node logs an error when this truncation happens. As a result, very large historical blocks may have their events and logs omitted from `/block_results`. For per-transaction EVM data in that case, use the EVM JSON-RPC methods `eth_getTransactionReceipt` and `eth_getBlockReceipts` instead. + + ### Filter and subscription limits @@ -116,6 +163,14 @@ By default, log filters (`eth_getLogs`, `eth_getFilterLogs`) have these limits. A query over a limit fails with `query matches too many logs`, `query matches too many log bytes`, or `block range too large`. It does not return partial results. Narrow the block range or the filters (address and topics), then try again. +Block, filter, and log methods that read historical state for a requested height — including `eth_getBlockByNumber`, `eth_getBlockByHash`, `eth_getLogs`, `eth_getFilterLogs`, and `eth_getBlockReceipts` — now return a `state at height N is unavailable` error when the node cannot load the state for that height (for example on pruned nodes or nodes with state sync (SS) disabled). Previously such a request caused an internal panic; it now surfaces a clear error so callers can narrow the height range or query a node that retains the needed state. + + + +On a Cosmos EVM node, operators can disable the receipt store by setting `receipt-store.rs-enable = false` in the `[receipt-store]` section of `app.toml` (it defaults to `true`). A node in this mode keeps no receipt history. Because most `eth_*` methods read a block's transactions or receipts, the EVM HTTP and WebSocket RPC listeners refuse to start when the receipt store is disabled; turning it off requires both `evm.http_enabled` and `evm.ws_enabled` to be `false`. On a node that does serve EVM RPC with a receipt-dependent method reaching a disabled store, the receipt-reading methods — including `eth_getLogs`, `eth_getFilterLogs`, `eth_feeHistory`, `eth_getBlockReceipts`, and `eth_getBlockTransactionCountByNumber` / `eth_getBlockTransactionCountByHash` — return an explicit `ErrNotConfigured` error rather than empty or null results, so callers are not silently handed incomplete data. + +On a Giga node, the receipt store is controlled instead by `giga.storage.receipts` in the `[giga.storage]` section (it defaults to `true`). The receipt store backs the EVM-only JSON-RPC's transaction receipts, logs, and fee history, so when `giga.storage.receipts = false` the node opens no receipt store and does not start the EVM-only RPC at all; it logs an informational message and continues finalizing blocks without storing receipts. A node refuses to start with receipts disabled while a receipt store that already holds history sits on disk — startup fails with `ErrReceiptStoreDisabledWithHistory`. To run without receipts, move that receipt store directory away first, or re-enable receipts. + Real-time subscriptions (`eth_subscribe` for `newHeads` and `logs`) are available over WebSocket only. For transport details, see [WebSocket connections](/evm/evm-parity/websocket). @@ -128,9 +183,9 @@ You can also browse every method below in the interactive explorer above. This s **Supported.** Submits a signed, RLP-encoded raw EVM transaction to the network and returns its hash. -**Sei-specific behavior:** Decodes the bytes to an ethtypes.Transaction, wraps it in a Cosmos MsgEVMTransaction, and broadcasts it through CometBFT. By default, it uses a CheckTx-level BroadcastTx (that is, `broadcast_tx_sync`), and slow mode uses BroadcastTxCommit. Non-zero CheckTx codes are returned as ABCI errors, not geth mempool errors. Legacy (non-1559) transactions must set gasPrice at or above the governance minimum (currently 50 gwei on Sei Mainnet). Blob (EIP-4844) transactions are not enabled. The method supports per-sender EvmProxy forwarding. +**Sei-specific behavior:** Decodes the bytes to an ethtypes.Transaction, wraps it in a Cosmos MsgEVMTransaction, and broadcasts it through CometBFT. By default, it uses a CheckTx-level BroadcastTx (that is, `broadcast_tx_sync`), and slow mode uses BroadcastTxCommit. Non-zero CheckTx codes are returned as ABCI errors, not geth mempool errors. Mempool rejections, however, are mapped to their standard go-ethereum equivalents for EVM client compatibility: a transaction already in the mempool returns `txpool.ErrAlreadyKnown`, a nonce below the sender's lowest pending nonce returns `core.ErrNonceTooLow`, a same-nonce transaction that does not outbid the one already held returns `txpool.ErrReplaceUnderpriced`, and a replacement the sender cannot afford returns `core.ErrInsufficientFunds`. Other broadcast errors are returned unchanged. Legacy (non-1559) transactions must set gasPrice at or above the governance minimum (currently 50 gwei on Sei Mainnet). Blob (EIP-4844) transactions are not enabled. The method supports per-sender EvmProxy forwarding. -**Under Autobahn (`AutobahnConfigFile` set):** The node runs as a validator when the top-level `mode` in `config.toml` is `"validator"`. With any other mode, it runs as a fullnode without a local mempool. +**Under Autobahn (`AutobahnConfigFile` set):** Any node configured with an autobahn-config-file is rejected in seed mode — setting `mode` to `"seed"` with an autobahn-config-file present fails node startup with `autobahn is not supported in seed mode` (#errAutobahnSeed). Otherwise, the node runs as a validator when the top-level `mode` in `config.toml` is `"validator"`, and as a fullnode without a local mempool in any other (non-seed) mode. Every Autobahn node runs on on-disk persistent storage: `persistent_state_dir` in `autobahn.json` is required and must not be empty (there is no in-memory mode). On a validator, transactions go to Autobahn's producer mempool instead of CometBFT's `TxMempool`. This mempool admits EVM transactions in strict nonce order for each sender. It rejects a transaction with a bad-nonce error if its nonce is not the sender's next expected nonce, so senders must submit nonces without gaps. If another validator owns the sender's EVM shard and is connected, the validator forwards the transaction to that validator instead. The `enable_evm_proxy` field in `autobahn.json` controls this forwarding. Its default is `true`. @@ -561,6 +616,8 @@ If a receipt exists but its block height is above the safe-latest watermark, the **Sei-specific behavior:** Under the eth namespace, only EVM transactions are indexed. Synthetic and bank-transfer transactions are excluded. Block number 0 returns a synthetic genesis block, for compatibility with The Graph. Future or non-existent numeric blocks return null. Uncle and PoW header fields (sha3Uncles, nonce, mixHash, difficulty) are placeholders, and the uncles array is always empty (CometBFT consensus). The safe, finalized, and latest tags are equivalent because of instant finality. +Block headers include a Sei-specific `milliTimestamp` field alongside the standard `timestamp`. The standard `timestamp` stays in whole seconds, as every Ethereum client reads it, but Sei commits blocks faster than once a second, so `timestamp` repeats across consecutive blocks. `milliTimestamp` is a BEP-520-compatible companion that carries the header time as a hex quantity of Unix milliseconds, exposing the sub-second precision the Tendermint header already holds. The synthetic genesis block returns `0x0`. Note that `milliTimestamp` is not guaranteed unique per block either: under Autobahn a proposal spaces consecutive blocks by as little as 1µs, so blocks less than a millisecond apart share the same millisecond value. The same `milliTimestamp` field appears in blocks returned by `eth_getBlockByHash` and in `eth_subscribe("newHeads")` notifications. + **Parameters:** | # | Name | Type | Description | @@ -739,10 +796,18 @@ The base fee comes from the x/evm keeper (GetNextBaseFeePerGas) and is itself fl **Sei-specific behavior:** Base fees and rewards reflect Sei's x/evm fee market (GetNextBaseFee), not an Ethereum EIP-1559 mempool. Sei does not burn the base fee. The method is watermark-aware: pruned or historical blocks may not be available as far back as on Ethereum archive nodes. +The earliest queryable height is the node's receipt floor rather than its block floor. A node's receipt store can start later than its block store — typically after a state-sync or snapshot restore — so the receipt floor can sit above the earliest available block. `eth_feeHistory` starts its window at the receipt floor: a requested range that ends below it fails with `requested last block N is before earliest available height M`, which now names the block numbers involved. + +The same receipt floor applies to every method that takes a block identifier or range — the log methods (`eth_getLogs`, `eth_getFilterLogs`), `debug_traceBlockByNumber` / `debug_traceBlockByHash`, and `eth_getTransactionByBlockNumberAndIndex` / `eth_getTransactionByBlockHashAndIndex`. A height below the receipt floor now returns JSON-RPC error `-32000` of the form `requested height N receipts have been pruned; earliest available is M` (ranges use the `ComputeBlockBounds` wording, for example `requested fromBlock N is before earliest available block M`) rather than an empty or `null` result. Lookups by transaction hash (`eth_getTransactionReceipt`, `eth_getTransactionByHash`, `eth_getTransactionErrorByHash`) still return `null` below the floor, because a hash carries no height to compare. An unknown block hash still returns no blocks. + On ranges where every block has base-fee data, `baseFeePerGas` contains one more element than `gasUsedRatio`. This matches go-ethereum and execution-apis semantics. The trailing element is the projected base fee for the child of the newest block in the range. It is appended only when the newest block's own header base fee was available. Heights with pruned or partial base-fee data are skipped in `baseFeePerGas`, but they still contribute a `gasUsedRatio` row (0.0 fallback). On ranges with pruned history, the two arrays can therefore diverge from that `+1` relationship. Each block's base fee uses header base fee semantics. That is the same value that the block header reports: `GetNextBaseFee` at the parent's committed height. For early blocks, the base fee falls back to `DefaultMinFeePerGas`. +**On the Giga EVM-only RPC server:** The method behaves differently because Giga has no EIP-1559 fee market. `baseFeePerGas` is always zero for every entry (it still carries one more element than `gasUsedRatio`, the projected child base fee, also zero). Reward percentiles are served from per-block reward-percentile statistics recorded alongside each block's receipts, rather than computed on the fly from a mempool oracle; the stored percentile set is controlled by the `receipt-store.rs-reward-percentiles` config field (see below). A requested percentile that is not already covered by the stored stats is recomputed from the block's receipts. The requested `blockCount` is capped at 1024 — a larger value is clamped down rather than rejected. `rewardPercentiles` must be strictly ascending and each entry within `[0, 100]`, otherwise the call returns an error. A `blockCount` below 1 returns an empty result (oldestBlock `0x0`, empty `gasUsedRatio`). + +**Reward-percentile storage (Giga receipt store):** The set of gas-weighted reward percentiles computed and stored per block is configured by `receipt-store.rs-reward-percentiles` in the `[receipt-store]` section of `app.toml`. It applies only to the `littidx` backend. Each entry must be in `[0, 100]` with no duplicates; it can also be set via a comma-separated environment variable. An empty list (`[]`, the default) falls back to `[0, 10, 20, 25, 30, 50, 75, 90, 100]`. + **Parameters:** | # | Name | Type | Description | @@ -795,6 +860,8 @@ Heights with pruned or partial base-fee data are skipped in `baseFeePerGas`, but **Sei-specific behavior:** Has the same range and size caps as `eth_getLogs`. Open-ended ranges return up to 10,000 logs (DefaultMaxLogLimit). Close-ended ranges are limited to 2,000 blocks (DefaultMaxBlockRange), and large queries are rate-limited. +`eth_getLogs`, `eth_getFilterLogs`, and each `eth_getFilterChanges` poll pass the same admission before any blocks are read (#4573 unified them). A range over `max_blocks_for_log` is refused. A range over 100 blocks takes a token from one node-wide large-query rate limiter shared by all three paths and all clients. The limit is configurable via `large_log_query_rps` in the `[evm]` section of `app.toml` (default 30 queries per second; set to 0 to disable the limit, negative values are rejected). Without a token, `eth_getLogs` and `eth_getFilterLogs` are refused, while a filter poll is instead cut to the next 100 blocks so a filter that has fallen behind keeps advancing as long as it is polled often enough. The load check now runs before the rate limiter: any read is refused while the worker queue or the DB read semaphore is 80% used, as seen when it arrives and before it takes a token, so a query refused under load does not spend a rate-limit token. A refused `eth_getFilterChanges` poll leaves the filter's cursor where it was, so the next poll retries the same blocks. Refusals caused by rate limiting or server load carry JSON-RPC error code `-32005` (limit exceeded, retry later) rather than the generic `-32000`, and their messages carry only a retry-later hint — they no longer expose server-internal details such as queue depth or semaphore counts. A range over `max_blocks_for_log` is still a `-32000` `block range too large` error. + **Parameters:** | # | Name | Type | Description | @@ -822,13 +889,17 @@ Heights with pruned or partial base-fee data are skipped in `baseFeePerGas`, but **Supported.** Creates a filter that tracks newly arrived block hashes and returns its ID. +**Sei-specific behavior:** The source of the block hashes depends on whether the node runs Autobahn. Under Autobahn the filter collects hashes from the block-header notifier, and a filter that accumulates more than `max_block_filter_hashes` unpolled hashes is invalidated and removed. On a node without that notifier (the usual Cosmos EVM node), the filter instead polls the CometBFT block store from a numeric cursor that starts at the block after the head at creation, so no poll returns a block from before the filter existed. On a state-synced node whose block store begins above the safe latest height, the cursor starts at the earliest available block instead. + +Each `eth_getFilterChanges` poll on a non-Autobahn node covers at most `max_block_filter_hashes` block heights, from the cursor up to the current head, and returns their hashes oldest-first; later polls return the rest. When pruning passes the cursor — before or during a poll — that poll fails with a JSON-RPC `-32000` error of the form `blocks X to Y were pruned before the filter read them`, after which the filter resumes from the earliest available block. A block-store read failure leaves the cursor where it was, so the next poll retries the same heights, and concurrent polls of one filter may return the same hashes. + **Parameters:** none. #### `eth_getFilterChanges` **Supported.** Polls a filter and returns new logs (log filters) or block hashes (block filters) since the last poll. -**Sei-specific behavior:** For log filters, the method returns an empty array (`[]`) instead of `null` when no logs match. It does the same when a bounded filter's block range has been fully consumed. This is in line with the Ethereum JSON-RPC spec. +**Sei-specific behavior:** A log filter created by `eth_newFilter` fixes where its polling starts, once, at creation time (its poll cursor). A numeric `fromBlock` is kept as given; an omitted or tag `fromBlock` (such as `latest`) starts at the block after the head at creation. A numeric `fromBlock` above 0 that is below the earliest available (non-pruned) block is rejected at creation with `requested fromBlock X is before earliest available block Y`, while a `fromBlock` of 0 (or `earliest`) still polls from the earliest available block. Unlike geth, a numeric `fromBlock` in the past makes the first poll return that history. Each `eth_getFilterChanges` poll then scans from the cursor to the current head — or to a numeric `toBlock` below the head — and advances the cursor past the blocks it covered. A tag `toBlock` such as `latest` follows the head and never ends the filter. When pruning passes an active filter's cursor, the next `eth_getFilterChanges` poll fails with an error naming the pruned block range (`logs of blocks X to Y were pruned before the filter read them`), after which the filter resumes from the earliest available block. A single poll covers at most `max_blocks_for_log` blocks (2,000 by default), and fewer when its logs exceed the log caps; the remaining blocks are returned by later polls. A block whose logs alone exceed the log caps fails only the poll that reaches it (with an error naming the block), after which the cursor advances past that block so the filter continues instead of wedging. For log filters, the method returns an empty array (`[]`) instead of `null` when no logs match. It does the same when a bounded filter's block range has been fully consumed (its cursor has passed a numeric `toBlock`). This is in line with the Ethereum JSON-RPC spec. **Parameters:** @@ -853,7 +924,7 @@ Heights with pruned or partial base-fee data are skipped in `baseFeePerGas`, but **Supported.** Returns all logs that match a previously created log filter, including historical logs. -**Sei-specific behavior:** Has the same caps as `eth_getLogs` (2,000-block range, 10,000-log limit). Large queries are rate-limited. +**Sei-specific behavior:** Has the same caps as `eth_getLogs` (2,000-block range, 10,000-log limit). Large queries are rate-limited. This is a read-only history query: it does not advance the `eth_getFilterChanges` cursor, so calling it will not cause a subsequent `eth_getFilterChanges` poll on the same filter to skip pending changes or redeliver the last history block. **Parameters:** diff --git a/evm/transactions-with-seid.mdx b/evm/transactions-with-seid.mdx index 5f558128..fc9c51a2 100644 --- a/evm/transactions-with-seid.mdx +++ b/evm/transactions-with-seid.mdx @@ -154,6 +154,8 @@ Deployed to: 0x... Transaction hash: 0x... ``` +The `seid tx evm deploy-wsei` command, which deployed the WSEI (Wrapped Sei) ERC20 contract, has been removed and is no longer available. + ## Contract interaction commands ### Call contract @@ -224,6 +226,8 @@ seid tx evm call-precompile staking delegate seivaloper1... --value=100000000000 For each precompile's methods, parameters, and usage patterns, see the [EVM precompiles documentation](/evm/precompiles/example-usage). +EVM pointer creation is retired, so the CLI paths that registered pointers no longer exist. The `seid tx evm register-evm-pointer` command, the `seid tx evm call-precompile pointer addNativePointer` call, and the `seid tx evm add-erc-native-pointer` governance proposal command have all been removed, and the pointer precompile's `add*` methods revert. Any transaction that previously created a pointer now reverts with `pointer precompile is retired; EVM pointer creation is disabled`. + **Output:** ``` diff --git a/node/advanced-config-monitoring.mdx b/node/advanced-config-monitoring.mdx index 8ecf6625..3246f687 100644 --- a/node/advanced-config-monitoring.mdx +++ b/node/advanced-config-monitoring.mdx @@ -81,6 +81,17 @@ Monitoring is one of the most critical components of network infrastructure. Thi First, install Prometheus: + + + +The application Prometheus sink is off by default. A node whose `app.toml` is generated by v6.8.0 gets `prometheus-retention-time = 0` under `[telemetry]`, which leaves the sink uncreated even though `telemetry.enabled` stays `true`. `GET /metrics?format=prometheus` on the app API server (:1317) then returns `prometheus metrics are not enabled`, and `seid` exports no application Prometheus series. If you scrape application metrics, set a positive `[telemetry] prometheus-retention-time` in `app.toml` (the previous default was `7200`) before generating a new configuration file. Nodes that already have `prometheus-retention-time` written in `app.toml` are unaffected (#4032). + +```toml +[telemetry] +prometheus-retention-time = 7200 +``` + + ```bash wget https://github.com/prometheus/prometheus/releases/download/v2.42.0/prometheus-2.42.0.linux-amd64.tar.gz tar xvf prometheus-2.42.0.linux-amd64.tar.gz @@ -373,7 +384,6 @@ sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow 26656/tcp comment 'Sei P2P' sudo ufw allow 26657/tcp comment 'Sei RPC' -sudo ufw allow 9090/tcp comment 'Sei gRPC' sudo ufw enable ``` @@ -509,6 +519,11 @@ scrape_configs: Since v6.7.0, seed nodes serve Prometheus metrics like other nodes. A seed serves no RPC, so its p2p metrics, such as `tendermint_p2p_peers`, are the only way to watch it. Enable them in the `[instrumentation]` section of `config.toml`: + + +Alongside `tendermint_p2p_peers`, the node exports the `tendermint_p2p_known_addresses` gauge, which reports the number of distinct peers with a known address: connected peers plus those learned via PEX. Like the peers gauge, it is published at router construction so the series exists before the node starts, and it is refreshed periodically thereafter. + + ```toml [instrumentation] prometheus = true @@ -537,7 +552,7 @@ The `tendermint` namespace also has these subsystems: | Subsystem prefix | Description | | --- | --- | -| `tendermint_internal_autobahn_avail_*` | Autobahn availability metrics: the commit road index, the commit global block number, the proposal-to-commit latency, and the commit-to-commit latency (with a `timeouts` label). | +| `tendermint_internal_autobahn_avail_*` | Autobahn availability metrics: the commit road index, the commit global block number (the first global block number not covered by the highest observed CommitQC), the proposal-to-commit latency, and the commit-to-commit latency (with a `timeouts` label). | | `tendermint_internal_autobahn_data_*` | Autobahn data metrics: `latency` (time from the production of a resource to each stage, with `resource` and `stage` labels), `next_block` (the next block to process in each stage), `gas_used` (gas used by executed blocks), and `tx_size` (size of executed transactions in bytes). | | `tendermint_internal_p2p_mux_*` | p2p mux stream metrics: the stream `latency`, the number of open streams (`in_flight`), and the per-stream counters `send_msgs`, `recv_msgs`, `send_bytes`, and `recv_bytes`. These metrics have `role` and `kind` labels. | @@ -551,10 +566,70 @@ The EVM RPC layer emits OpenTelemetry metrics through the process-wide `MeterPro | --- | --- | --- | | `evmrpc_request_latency_seconds` | Histogram | EVM RPC request latency in seconds. | | `evmrpc_websocket_connects_total` | Counter | Number of new WebSocket connections. | +| `evmrpc_websocket_connections` | Gauge (Int64UpDownCounter) | Number of currently connected WebSocket clients. Incremented on connect and decremented on disconnect. | | `evmrpc_redirected_requests_total` | Counter | Number of EVM RPC requests forwarded to another validator. Labeled by `endpoint` and `connection`. | | `evmrpc_historical_debug_trace_attempts_total` | Counter | Number of `debug_trace*` requests that target historical blocks beyond the configured max block lookback. Labeled by `endpoint` and `connection`. | | `evmrpc_requests_rejected_total` | Counter | Number of JSON-RPC requests that admission control rejected. Labeled by `protocol` (`http` or `ws`) and `reason`. For HTTP, `reason` is `oversize` (larger than `max_request_body_bytes`, HTTP 413), `budget_midread` (the `max_concurrent_request_bytes` budget ran out, HTTP 429), `slow_body`, `rate_limited`, `unparseable`, or `read_error`. For WebSocket, `reason` is `oversize` (close code `1009`) or `busy` (no budget within `ws_admission_timeout`, JSON-RPC error `-32005`). See [Frame size and concurrency limits](/evm/evm-parity/websocket#frame-size-and-concurrency-limits). | + + + +Rate limiting is now enabled by default across EVM RPC, gRPC, and Tendermint RPC (#4299). A newly generated `app.toml` sets EVM `rate_limiting_enabled = true`, a generated `config.toml` enables Tendermint RPC rate limiting, and gRPC `rate-limiting-enabled` now defaults to `true`. As a result, operators will see HTTP 429 (`too many requests`) rejections by default when clients exceed the per-IP limits, reflected in `evmrpc_requests_rejected_total` with `reason` `rate_limited`. The default EVM `batch_request_limit` also dropped from `1000` to `100`, and the default EVM per-IP burst (`ip_rate_limit_burst`) is now `200`. + +When `rate_limiting_enabled` is inherited (not explicitly set in `app.toml`) and a configured `ip_rate_limit_burst` is below `batch_request_limit`, the node now raises the burst to the batch limit and logs a warning instead of failing to start. If you set `rate_limiting_enabled` explicitly, a burst below the batch limit is still rejected at startup; set `ip_rate_limit_burst >= batch_request_limit` in that case. To restore the previous behavior, set `rate_limiting_enabled = false` under `[evm]`, `rate-limiting-enabled = false` under `[grpc]`, and the corresponding Tendermint RPC switch in `config.toml`. + + + + +The EVM RPC per-IP rate limit is configured by `ip_rate_limit_rps` and `ip_rate_limit_burst` in the `[evm]` section of `app.toml`. These two fields can be overridden at startup by the `EVM_IP_RATE_LIMIT_RPS` and `EVM_IP_RATE_LIMIT_BURST` environment variables. When an environment variable is set, it takes precedence over the corresponding `app.toml` field; when it is unset, the `app.toml` value applies. This override is primarily useful for test and CI setups that drive a node from a single IP and would otherwise hit the default per-IP limits. + +```toml +[evm] +ip_rate_limit_rps = 300 +ip_rate_limit_burst = 1500 +``` + +```bash +# Override the app.toml values at startup +export EVM_IP_RATE_LIMIT_RPS=300 +export EVM_IP_RATE_LIMIT_BURST=1500 +``` + +The node also rejects JSON-RPC batches larger than `evm.batch_request_limit` (default `100`). Clients that submit batched requests must keep each batch at or below this limit. + + + +## Large log query rate limit + +Log queries that span more than 100 blocks (`eth_getLogs`, `eth_getFilterLogs`, and filter polls) are admitted at a node-wide rate shared by all clients. The rate is configured by `large_log_query_rps` in the `[evm]` section of `app.toml`, which sets the admitted queries per second. The default is `30`. Set it to `0` to disable the limit entirely; negative values are rejected at startup. + +When the limit is in effect, an `eth_getLogs` or `eth_getFilterLogs` over 100 blocks that cannot take a token is refused with JSON-RPC error code `-32005` (limit exceeded, retry later), while a filter poll over 100 blocks is instead cut to the next 100 blocks so a filter that has fallen behind keeps advancing. The load check runs before the rate limiter during admission, so a query refused while the node is under load does not spend a rate-limit token. + +```toml +[evm] +large_log_query_rps = 30 +``` + + + +## Block filter polling + +The `max_block_filter_hashes` field in the `[evm]` section of `app.toml` governs how an `eth_newBlockFilter` filter handles block hashes. Its meaning depends on whether the node runs with a block header notifier (Autobahn): + +- Under Autobahn, the filter collects block hashes from the notifier, and a filter that holds more than this many unpolled hashes is invalidated and removed. +- Otherwise there is no notifier, and the filter polls the CometBFT block store from a cursor that starts at the block after the head at filter creation, so no poll returns a block from before the filter existed. In this mode one `eth_getFilterChanges` poll covers at most `max_block_filter_hashes` block heights and returns their hashes oldest-first; later polls cover the rest. When pruning passes the cursor, the poll fails with a `-32000` error naming the pruned blocks, and the filter resumes from the earliest available block. + +```toml +[evm] +max_block_filter_hashes = 10000 +``` + + +`eth_getFilterLogs` rejects a block filter as not existing (`filter does not exist`), matching geth behavior. + + +When rate limiting rejects a JSON-RPC batch POST with HTTP 429 (`too many requests`), the rejection response now mirrors the shape of the request. A valid batch within the request batch size limit returns a JSON array of error objects, one per non-notification request, each preserving its request ID. A batch made up only of notifications returns an empty body, just as it would when served. An oversized batch (above the request batch size limit) or a malformed batch still returns a single JSON-RPC error object. Single (non-batch) requests continue to return a single error object preserving the request ID. + The `evmrpc_request_latency_seconds` histogram carries these labels: | Label | Description | @@ -577,6 +652,31 @@ These legacy `sei_*` metrics remain available today but are deprecated. They are Before the legacy metrics are removed, update your Prometheus and Grafana dashboards to use the `evmrpc_*` metrics. The latency unit changed from milliseconds (`sei_rpc_request_latency_ms`) to seconds (`evmrpc_request_latency_seconds`). Adjust any thresholds and panel formatting to match. + +### EVM RPC per-method deadlines + +EVM JSON-RPC methods are bounded by a per-method deadline over both HTTP and WebSocket (#4299). A method that exceeds its deadline returns a `context deadline exceeded` error. When this happens the node increments the OpenTelemetry counter `rpc_deadline_exceeded_total`, labeled by `plane` (for example, `evm`) and `method_namespace` (for example, `eth`), so you can alert on methods that run past their deadline. + +| Metric | Type | Description | +| --- | --- | --- | +| `rpc_deadline_exceeded_total` | Counter | Number of EVM JSON-RPC requests that exceeded their configured deadline. Labeled by `plane` and `method_namespace`. | + +Configure the deadlines in the `[evm]` section of `app.toml`: + +| Config key | Default | Description | +| --- | --- | --- | +| `rpc_default_timeout` | `30s` | Deadline applied (on both HTTP and WebSocket) to any RPC method with no entry in `rpc_method_timeouts`, such as `eth_getBalance` or `eth_getBlockByNumber`. Set to `0` to disable (no deadline applied). HTTP requests are also bounded by `write_timeout`; raise it to permit a longer method timeout over HTTP. | +| `rpc_method_timeouts` | `["eth_estimateGasAfterCalls=5m"]` | List of `"method=duration"` strings that override `rpc_default_timeout` for individual methods. A method name ending in `*` (for example, `"debug_trace*=0"`) matches every method with that prefix; the longest matching prefix wins. A duration of `0` means no deadline is applied by this mechanism. | + +```toml +[evm] +rpc_default_timeout = "30s" +rpc_method_timeouts = ["eth_estimateGasAfterCalls=5m"] +``` + +The simulation methods `eth_call`, `eth_estimateGas`, and `eth_createAccessList` use the configured `SimulationEVMTimeout` as their dispatch deadline. A wildcard entry in `rpc_method_timeouts` cannot change the timeout for `eth_call`, `eth_estimateGas`, `eth_createAccessList`, `eth_sendRawTransaction`, `eth_sendTransaction`, `eth_getTransactionCount`, or `debug_trace*` methods, because each already has its own exact or prefix entry that takes precedence. To change one of these, name it exactly, for example `"eth_call=1s"`. + + ## FlatKV OpenTelemetry metrics The FlatKV state store emits OpenTelemetry metrics through the process-wide `MeterProvider` (for example, a Prometheus exporter). With these metrics, you can observe commit throughput, catchup progress, snapshotting, rollbacks, and snapshot imports. @@ -619,6 +719,25 @@ FlatKV metrics carry these labels where applicable: FlatKV turns on Pebble's internal metrics for each data DB by default. The node does not apply an `enable-pebble-metrics` key from `app.toml`. + + +### FlatKV snapshot retention + +FlatKV publishes periodic checkpoints and keeps a number of old ones besides the latest so that composite reads and rollbacks can reach a version both backends still hold. Configure retention in the `[state-commit.flatkv]` section of `app.toml`: + +| Config key | Default | Description | +| --- | --- | --- | +| `snapshot-keep-recent` | `10` | Number of old checkpoints to keep besides the latest. `0` keeps only the current checkpoint (no old ones). Ignored entirely when external pruning is set. | + +```toml +[state-commit.flatkv] +snapshot-keep-recent = 10 +``` + +The default retention is `10` old checkpoints (#4322). A composite read needs a version that both FlatKV and memIAVL still hold. At mainnet state size memIAVL publishes a snapshot only about every 50,000 blocks, so FlatKV must reach back further than that: ten old checkpoints at FlatKV's snapshot interval reach roughly 100,000 blocks. Because a checkpoint hardlinks its SSTs, each one costs only what compaction has obsoleted since, about 290 MiB at mainnet state size. + +FlatKV's `snapshot-keep-recent` is no longer derived from memIAVL's `sc-keep-recent`; it uses its own configured or default value. Only FlatKV's snapshot interval follows memIAVL's effective snapshot interval. + ## Pebble estimated read/write metrics SeiDB can count estimated logical reads and writes on its PebbleDB databases. The counters are off by default. They cost less than Pebble's full internal metrics, and you can use them to estimate read amplification (reads divided by writes). @@ -628,6 +747,51 @@ SeiDB can count estimated logical reads and writes on its PebbleDB databases. Th | `pebble_estimated_reads` | Counter | Estimated logical PebbleDB reads. | | `pebble_estimated_writes` | Counter | Estimated logical PebbleDB writes. | + + +## Undo-log state store OpenTelemetry metrics + +When the EVM state store uses the `undolog` backend (a bucketed PebbleDB undo log that keeps recent EVM history), the store emits operation-level OpenTelemetry metrics through the process-wide `MeterProvider` (for example, a Prometheus exporter). Pebble's own internal stats are reported separately, the same way they are for the MVCC state store. + +The backend is selected by the `giga.storage.state_store_backend` config field (`state_store_backend` under the giga `[storage]` section). It accepts `"pebbledb"` (the default, which keeps every version of every key) or `"undolog"` (which records the value each block replaced over the current state and drops expired history a bucket at a time); any other value fails config validation. Set it to `"undolog"` to emit the metrics below. + +### Available undo-log metrics + +| Metric | Type | Unit | Description | +| --- | --- | --- | --- | +| `pebble_undo_get_latency` | Histogram | seconds | Time taken to read a key at a height. Carries a `success` boolean attribute. | +| `pebble_undo_get_probes` | Histogram | `{bucket}` | Number of buckets probed by one read. | +| `pebble_undo_apply_latency` | Histogram | seconds | Time taken to write one block's undo records. Carries a `success` boolean attribute. | +| `pebble_undo_apply_records` | Histogram | `{record}` | Number of undo records written for one block. | +| `pebble_undo_excise_latency` | Histogram | seconds | Time taken to excise expired buckets during pruning. | +| `pebble_undo_buckets_excised` | Counter | `{bucket}` | Number of buckets removed by excise. | +| `pebble_undo_pending_changes` | Gauge | `{block}` | Current depth of the asynchronous write queue (blocks waiting to be applied). | + + + +## Subspace query metrics + +`/store/*/subspace` ABCI queries are served only from the state store (SS). On a node with SS disabled, every `/subspace` query is now rejected with an `ErrNotSupported` error (`subspace queries require the state store`) before it takes a concurrency permit. A scan that would exceed the configured pair or byte caps fails with `subspace result exceeds limit`, empty prefixes are rejected, and queries that exceed the concurrency limit are rejected with `subspace query busy`. The concurrency limit bounds concurrent `/subspace` queries; because only nodes with SS enabled serve `/subspace`, it applies only to those nodes. Indexers and tooling that issue wide `/subspace` queries must narrow their prefixes, shard by sub-prefix, or raise the caps in `app.toml` (#4009). + +| Metric | Type | Description | +| --- | --- | --- | +| `subspace_query_rejected` | Counter | Number of rejected `/subspace` ABCI queries. Labeled by `reason`: `semaphore` (the concurrency limit was exceeded), `cap_exceeded` (the scan hit the pair or byte cap), or `ss_disabled` (the query was rejected because the state store is disabled). | + +Tune the caps in the `[state-commit]` section of `app.toml`. Values `<= 0` resolve to the defaults; there is no unlimited setting: + +| Config key | Default | Description | +| --- | --- | --- | +| `sc-subspace-max-pairs` | `1000` | Maximum number of key/value pairs a `/subspace` scan may return. | +| `sc-subspace-max-bytes` | `4194304` (4 MiB) | Maximum key+value bytes a `/subspace` scan may accumulate. | +| `sc-subspace-query-max-inflight` | `2` | Maximum concurrent `/subspace` queries. Only nodes with SS enabled serve `/subspace`, so this limit applies only to them. | + +```toml +[state-commit] +sc-subspace-max-pairs = 1000 +sc-subspace-max-bytes = 4194304 +sc-subspace-query-max-inflight = 2 +``` + Both counters have a `db` attribute. Its value is the name of the data directory, so you can tell the FlatKV data DBs, the state store, and the receipt store apart. Turn the counters on per store in `app.toml`: | Config key | Section | Store | @@ -636,14 +800,41 @@ Both counters have a `db` attribute. Its value is the name of the data directory | `ss-enable-read-write-metrics` | `[state-store]` | State store, when `ss-backend = "pebbledb"` | | `enable-read-write-metrics` | `[receipt-store]` | Pebble-based receipt store | + +The `[receipt-store]` `enable-read-write-metrics` key is no longer written into the generated `app.toml` template. The config reader still honors `receipt-store.enable-read-write-metrics` if you add it to `app.toml` by hand, but a newly generated file no longer renders it under `[receipt-store]`. + + ```toml [state-commit.flatkv] enable-read-write-metrics = true ``` -## Log query parallelism for `littidx` -With the `littidx` receipt store, each `eth_getLogs` query scans several blocks at the same time. Results stay in block and transaction order. `log-filter-parallelism` under `[receipt-store]` sets how many blocks one query scans at once. The default is `16`, and a value of `0` or less uses the default. The setting has no effect on `pebbledb`. +## State proof metrics + +ABCI `/store` state proofs are deprecated and disabled by default (#4573). When a node receives a proof query (`prove=true` on a `/store` path that would produce a proof), it rejects the request with an `ErrNotSupported` error (`state proofs are disabled on this node; set state-commit.sc-enable-state-proof = true to enable`) and increments the `state_proof_rejected` counter. This affects light clients, which always set `prove=true`, and any ABCI client that sends `prove=true`. The proof code is scheduled for removal in a later release. + +| Metric | Type | Description | +| --- | --- | --- | +| `state_proof_rejected` | Counter | Number of ABCI `/store` state proof queries rejected because proofs are disabled. Labeled by `store` (the store the query targeted) and `latest` (a boolean indicating whether the query was at the latest height). | + +Operators who need to keep serving state proofs (for example, to support light clients) must opt in by setting `sc-enable-state-proof = true` in the `[state-commit]` section of `app.toml`: + +| Config key | Default | Description | +| --- | --- | --- | +| `sc-enable-state-proof` | `false` | Enables deprecated ABCI `/store` state proofs. When `false`, proof queries are rejected with `ErrNotSupported`. This option will be removed with the proof code in a later release. | + +```toml +[state-commit] +sc-enable-state-proof = true +``` + + +## Log query parallelism for the littidx receipt store + +The littidx receipt store is no longer selectable from the standard `[receipt-store]` backend config; `rs-backend` now only accepts `pebble`. The littidx code path (and its block-parallel `eth_getLogs` scanning) is used by the giga/evmonly path through the gigareceipt package rather than by a config-selected littidx backend. + +Where the littidx-based receipt store is in use, each `eth_getLogs` query scans several blocks at the same time, and results stay in block and transaction order. `log-filter-parallelism` under `[receipt-store]` sets how many blocks one query scans at once. The default is `16`, and a value of `0` or less uses the default. The setting has no effect on the `pebble` receipt store backend. ```toml [receipt-store] @@ -706,6 +897,68 @@ LittDB emits its metrics through the process-wide OpenTelemetry `MeterProvider` | `litt_compression_compressed_bytes` | Counter | bytes | Compressed bytes produced since startup. Divide by `litt_compression_uncompressed_bytes` to get the overall compression ratio. | | `litt_compression_ratio` | Histogram | ratio | Compressed bytes divided by uncompressed bytes, per batch. Lower is better. | + + +## evmonly-loadtest Prometheus metrics + +The `evmonly-loadtest` tool serves Prometheus metrics through an OpenTelemetry Prometheus exporter, so the counters it publishes arrive alongside the phase timers of the storage stack it drives (giga, FlatKV, and the view cache). It listens on port `9698` rather than the `9090` the sims use. Add a scrape target for it: + +```yaml +scrape_configs: + - job_name: 'evmonly-loadtest' + static_configs: + - targets: ['host.docker.internal:9698'] + scrape_interval: 5s +``` + +### Phase-timer metrics + +The run is instrumented with two phase timers, each a counter of seconds spent in a labeled phase. Together with the storage stack's own instruments they account for the whole of a block's cost. + +| Metric | Type | Description | +| --- | --- | --- | +| `evmonly_block_phase_duration_seconds_total` | Counter | Wall time of the single executor goroutine, broken into the phases of a store-backed block (`waiting_for_block`, `open_view`, `execute`, `occ_speculate`, `occ_validate`, `occ_merge`, `await_commit`, `encode_changesets`, `encode_receipts`, `write_receipts`, and `commit_state`), carried on a `phase` label. The slices sum to elapsed time. | +| `evmonly_pipeline_phase_duration_seconds_total` | Counter | Work across the goroutines of the stages that run ahead of the executor: `build_block` (constructing and signing a block's transactions), `recover_senders` (sender recovery during block preparation), and `waiting` (blocked rather than working). This is total work across workers, not wall time, and is what the executor's `waiting_for_block` is waiting on. | + +### Pipeline metrics + +The commit of a block runs behind the next block's execution, so a block pays the handoff (`commit_state`) plus whatever the previous commit had not finished (`await_commit`) rather than the write itself. `await_commit` near zero means the overlap is working. + +| Metric | Type | Description | +| --- | --- | --- | +| `evmonly_loadtest_reorder_pending_blocks` | Gauge | Blocks built ahead of the next height in a streaming run (`--blocks=0`), held in the reorder buffer until that height is sent. Bounded by twice `--builders`; pinned near that bound means one builder is holding the rest back. | + +### Grafana dashboard + +The tool ships an `EVMOnly Loadtest` Grafana dashboard (`docker/monitornode/dashboards/evmonly-loadtest-dashboard.json`, uid `evmonly-loadtest`). It breaks down where a block's serial time goes and which stage of the pipeline is the constraint, with rows for block time, pipeline stages, state reads, commit, and runtime. + + + +## Giga EVM-only executor OCC OpenTelemetry metrics + +The Giga EVM-only executor emits optimistic concurrency control (OCC) metrics through the process-wide OpenTelemetry `MeterProvider`, so you can watch parallel-execution behavior without reading `BlockResult`. The executor emits one sample per block. The node binds the meter provider with a `sei_chain` Prometheus namespace, so each name below is scraped with that prefix (for example, `giga_occ_blocks_total` is scraped as `sei_chain_giga_occ_blocks_total`). + +### Available OCC metrics + +| Metric | Type | Description | +| --- | --- | --- | +| `giga_occ_blocks_total` | Counter | One sample per block, labeled by `outcome`. `parallel` and `fallback` are blocks that tried optimistic execution, `sequential` are blocks that had transactions but were ineligible (a single transaction, `OCCWorkers <= 1`, or registered custom precompiles), and `empty` are blocks with no transactions. Splitting the ineligible blocks from the empty ones keeps `parallel / (parallel + fallback + sequential)` a statement about OCC rather than about block rate. | +| `giga_occ_fallbacks_total` | Counter | Blocks that abandoned the optimistic path and re-ran sequentially, labeled by `reason`. | +| `giga_occ_reruns_total` | Counter | Transaction reruns scheduled by optimistic execution validation across the whole block. | +| `giga_occ_conflicts_total` | Counter | State access conflicts observed while validating optimistic execution, labeled by `access` and `kind`. | +| `giga_occ_rerun_depth` | Histogram | The deepest incarnation any single transaction reached (`MaxIncarnation`) per optimistically executed block, bucketed one per reachable incarnation. The histogram records every block that tried optimistic execution, including those that never reran a transaction. | + +### Labels + +| Label | Metric | Values | +| --- | --- | --- | +| `outcome` | `giga_occ_blocks_total` | `parallel`, `fallback`, `sequential`, or `empty`. | +| `reason` | `giga_occ_fallbacks_total` | The fallback reason, such as a validation conflict, a gas limit or gas overflow, max-incarnation exhaustion, or a closed OCC worker pool. | +| `access` | `giga_occ_conflicts_total` | `read` or `write`. | +| `kind` | `giga_occ_conflicts_total` | The conflicting state kind: `account`, `balance`, `nonce`, `code`, or `storage`. | + +Every label vocabulary is closed: an `outcome`, `reason`, `access`, or `kind` value the emitter does not recognize collapses to `unknown` rather than adding a new series. Conflict addresses and storage slots are deliberately not labels, because they are per-contract and per-slot and would make the series unbounded; they remain available in `OCCStats.ConflictSamples` for logs and spans. A block's conflict samples are summed onto the access-by-kind series before being emitted, so the telemetry work per block is bounded by the label space rather than by the number of conflicting state keys. + ### Attributes | Attribute | Description | diff --git a/node/frozen-nodes.mdx b/node/frozen-nodes.mdx index 7fcd07a0..ed8a8989 100644 --- a/node/frozen-nodes.mdx +++ b/node/frozen-nodes.mdx @@ -23,6 +23,29 @@ From startup, freeze mode changes the node like this: Each frozen node covers the heights up to its own upgrade. To serve the full history of a network, run one frozen node for each upgrade, and a live node on the current release for the heights after the last upgrade. Freeze mode first shipped in v6.6.3. The oldest frozen node therefore runs v6.6 and serves every height below the v6.7 upgrade height that its data holds. + +### IBC, feegrant, and gov history after v6.8 + +v6.7 removed the IBC module source and wiring, but kept the `ibc`, `transfer`, and `capability` stores mounted so that pre-v6.7 IBC history remained queryable. It likewise removed the feegrant module but kept the `feegrant` store mounted for historical state access. v6.8 goes further: it deletes the `ibc`, `transfer`, `capability`, and `feegrant` stores from state ([#4563](https://github.com/sei-protocol/sei-chain/pull/4563)), and it rewrites the four passed `ClientUpdateProposal` governance records (proposals 52, 81, 100, and 119) as `TextProposal`s that keep only their title and description. + +As a result, a v6.8 node cannot answer state queries at pre-v6.8 heights for those stores or for those governance records: + +- Querying the retired `ibc`, `transfer`, `capability`, or `feegrant` stores returns a generic `no such store: ` error (`ErrUnknownRequest`) instead of serving data. For example, an ABCI `/store/feegrant/key` query returns `no such store: feegrant`. +- Gov state queries at pre-v6.8 heights for the rewritten IBC proposals return the `TextProposal` content, not the original `ClientUpdateProposal` content. + +To serve the full pre-v6.8 IBC, feegrant, and gov history, run a frozen node on v6.7 or older. Deleting the `feegrant` store at the v6.8 upgrade height is app-hash breaking, so from that height no v6.8 node serves feegrant state at any height; a v6.7 (or older) node is required for that history. A v6.6 freeze node is the only release that also mounts the `ibc`, `transfer`, and `capability` stores with their original content and decodes the original IBC governance proposals, so it answers all of these queries the way the chain did at the time. + + +#### If the v6.8 upgrade halts on missing upgrade-info.json + +The store loader deletes the retired `ibc`, `transfer`, `capability`, and `feegrant` stores only when `data/upgrade-info.json` named the upgrade as the node started. If a node reaches the v6.8 upgrade height without that file naming the upgrade, the retired stores are still present, and the v6.8 upgrade handler now halts rather than running against the undeleted stores ([#4563](https://github.com/sei-protocol/sei-chain/pull/4563)). The error identifies the store that was not deleted and tells you to write the upgrade plan to `data/upgrade-info.json`: + +```json +{"name":"v6.8","height":} +``` + +Write that file, with `` set to the v6.8 upgrade height, to `data/upgrade-info.json` in the node home, then restart the node. On the restart, the store loader deletes the retired stores before the handler runs, and the upgrade proceeds. This applies to a live node upgrading to v6.8; a frozen node stays on v6.7 or older and never runs the v6.8 handler. + ## Freeze heights Set `freeze-height` to the upgrade height. Run the latest patch of the release that the upgrade replaced. diff --git a/node/giga-storage-migration.mdx b/node/giga-storage-migration.mdx index 06760e29..59c8e5da 100644 --- a/node/giga-storage-migration.mdx +++ b/node/giga-storage-migration.mdx @@ -20,6 +20,37 @@ After the migration, the SS layer is repartitioned into two cooperating stores: This migration changes only the **SS** layer. It does not change the SC layer or the app hash, so the change is invisible to the network. + + +## App hash vault on Giga nodes + +Giga nodes persist an app hash vault store alongside the block store at +`data/ledger/app_hash`. The vault (store name `AppHashVault`) holds the app hash +of every committed block and joins the storage garbage collector's shared prune +cycle like the other stores. + +Operators restarting a Giga node must keep this directory present and consistent +with the rest of the data directory. The following behaviors affect upgrades and +restarts: + +- **Recovery converges on the app hash vault head.** After an unclean shutdown, + recovery brings every store onto the lowest head among the block store, the + state WAL, the receipt store, and the app hash vault. If the vault is behind + the other stores (for example, a crash left state ahead of the stored app + hashes), recovery lowers the target to the vault head and the blocks above it + are re-executed, rebuilding their app hashes as they commit. If the vault is + ahead of the state (its WAL tail was not flushed before the crash), the vault + keeps its app hashes and the re-executed blocks are checked against them. +- **Chain ID is validated at startup.** The vault commits to the configured EVM + chain ID. If the stored app hashes belong to a different chain ID than the one + configured, the node fails to start rather than mixing hashes across chains. +- **The vault cannot roll back below block 1.** If the app hash vault holds no + app hash while the other stores hold blocks, recovery errors instead of + attempting a rollback that would reach below block 1. Removing or corrupting + the `data/ledger/app_hash` directory on a node that already has block and + state history therefore blocks startup; restore it from backup alongside the + rest of the data directory, or recover the node with a fresh state sync. + ## Prerequisites Run this migration on **RPC nodes only**. This flow does not support validator nodes or archive nodes yet, so do not run it against either. @@ -76,9 +107,9 @@ evm-ss-split = true ### Step 2: State sync into the new layout -Giga SS Store is fully compatible with the existing state-snapshot format. On -import, the composite state store routes each snapshot node based on the -importing node's `evm-ss-split`: +Giga SS Store is fully compatible with the existing **P2P state-sync** snapshot +format. On import, the composite state store routes each snapshot node based on +the importing node's `evm-ss-split`: - With `evm-ss-split = true`, EVM snapshot nodes go only into EVM SS, and non-EVM nodes go only into Cosmos SS. @@ -88,6 +119,30 @@ importing node's `evm-ss-split`: Both stores are then fully populated at the snapshot height, so the node can serve reads immediately. +P2P state-sync snapshots (the chunks peers serve over the network) are **not** +layout-sensitive. Giga SS Store only changes how the importing node writes those +nodes onto disk. + +#### Alternative: restore a Giga SS data-directory snapshot + +**Data-directory snapshots** (a tarball of `~/.sei/data`) *are* layout-sensitive. +A tarball taken from a Giga SS node contains `data/state_store/evm/` (and +`data/state_store/cosmos/`) instead of a single mixed Cosmos SS directory. You +can enable Giga SS Store by restoring such a snapshot and setting +`evm-ss-split = true`; you do not need to P2P state sync again. + +The restoring node's `ss-backend`, `evm-ss-separate-dbs`, and any +`ss-db-directory` / `evm-ss-db-directory` overrides must match the node the +snapshot was taken from. Both SS paths are backend-qualified +(`data/state_store/{cosmos,evm}/{backend}`), so a backend mismatch opens empty +directories and the node starts against restored SC with empty SS instead of +refusing to launch. A tarball from a non-Giga node cannot be used this way — +convert those nodes with the state sync flow below. + +Snapshot hosts that publish `data/` tarballs may offer both Giga SS and non-Giga +copies while the fleet migrates. Use a Giga SS snapshot only when you intend to +run with `evm-ss-split = true`. + The [state sync guide](/node/statesync) documents the full flow. The minimal flow for this migration is: @@ -216,6 +271,17 @@ config changes: `memiavl_only` to `migrate_evm` at the same height and starts to move keys. The node does not restart. + + +A `pause-state-migration` hard fork handler can force `NumKeysToMigratePerBlock` +to `0` at a configured target height on a specific chain. When it fires, it sets +the migration rate back to zero through the `migration` params subspace, which +pauses key movement without changing the current write mode: a node already in +`migrate_evm` stays in `migrate_evm`, it simply stops advancing the migration +boundary. Operators should be aware that an upgrade may ship this handler to +halt the migration at a coordinated height, after which governance can resume it +by raising `NumKeysToMigratePerBlock` above `0` again. + In v6.7, governance can start only the EVM migration. The later write modes (`migrate_all_but_bank`, `all_migrated_but_bank`, `migrate_bank`, and `flatkv_only`) exist, but no parameter starts them. @@ -227,6 +293,27 @@ advances at most once per block. When the migration starts, the node stops serving state proofs for the `evm` store, because FlatKV has no proof builder. Proofs for other modules still work. + +FlatKV only retains a bounded window of recent history (its snapshots plus +WAL). A rollback or historical read that targets a version below that retained +FlatKV history is now refused up front, before any backend state is touched, +with a non-fatal `version unreachable; use state sync instead` error. The store +is left usable rather than failing partway through a mutation, and historical +reads (`LoadVersionReadOnly` and exporters) below the floor return the same +error instead of panicking or creating a work directory. If you need a version +older than FlatKV retains, recover it with a state sync rather than a rollback. + +FlatKV applies a block's account changes by folding each per-field change (a +nonce, code hash, or balance) onto the row the account already holds. That fold +now runs asynchronously on the account store's own threads after the block has +been staged, rather than reading and merging the old account values synchronously +while the block is applied. As a result, applying a block no longer fails when it +touches a corrupted account row: `ApplyChangeSets` succeeds because the fold has +only been scheduled, and the corruption instead surfaces as a panic when that +account is later read. The `flatkv_account_update_latency` OpenTelemetry metric +measures the time to stage a block's account changes; it replaces the former +`flatkv_batch_read_old_values_latency` metric. + ### Pinning a write mode To pin a write mode, set both keys in the `[state-commit]` section of @@ -360,9 +447,37 @@ In the `localnode` and `rpcnode` configuration scripts, setting `RECEIPT_BACKEND` environment variable explicitly. The explicit value takes precedence over the default. -The supported receipt-store backends are `pebbledb` (also called `pebble`) and -`littidx`. For details on `littidx`, see the -[node operations guide](/node/node-operators). The former `parquet` option was -removed. The node rejects an unsupported value for `RECEIPT_BACKEND` (or -`rs-backend` in `app.toml`) with an error -(`unsupported receipt-store backend "parquet"; supported: pebbledb, littidx`). +The only receipt-store backend selectable from `app.toml` is `pebbledb` (also +called `pebble`). The `littidx` backend can no longer be selected via +`RECEIPT_BACKEND` or `rs-backend`; it is reserved for Giga, which opens it +through its own storage config. Selecting `littidx` from `app.toml` is rejected +with an error stating it cannot be selected from `app.toml` and is opened by +Giga. The former `parquet` option was removed. The node rejects any other +unsupported value for `RECEIPT_BACKEND` (or `rs-backend` in `app.toml`) with an +error (`unsupported receipt-store backend "parquet"; supported: pebbledb`). + + + +### Does the receipt store guard against opening it with the wrong backend? + +Yes. The receipt store records which backend owns its directory in a +`receipt-backend.txt` marker file, written on first open. If you later point a +different backend at that same directory than the one that owns it, the store +refuses to open and fails with a mismatch error that names both the backend +that owns the directory and the one that was requested, instead of silently +presenting an empty store. Point the configured backend at its own store +directory, or configure the backend that owns the one on disk. + +Since `littidx` is no longer selectable from the standard `rs-backend` config, +the only backend you can select from `app.toml` is `pebble`; a directory owned +by Giga's `littidx` store (opened through the `gigareceipt` path) cannot be +adopted by the standard receipt-store config, and the marker guards against +pointing the standard `pebble` backend at it. + +Directories written before the marker existed carry no marker and are adopted +as-is on the next open: the configured backend is taken to be the owner and the +marker is stamped on the way through, so existing nodes keep working without +intervention. A backend the build does not support, or a config the backend +rejects (such as `ExternalPruning` with the `pebble` backend), is refused before +the directory is touched, so a rejected attempt does not leave a marker behind +that would then refuse the corrected config. diff --git a/node/index.mdx b/node/index.mdx index 9c42cb40..3ba5ae60 100644 --- a/node/index.mdx +++ b/node/index.mdx @@ -117,12 +117,15 @@ For the current recommended version, see the Network Versions table above. - Each release attaches a statically linked `seid` build for `linux/amd64` with no - runtime dependencies. You do not need to install a Go toolchain or shared libraries. + Each release attaches statically linked `seid` builds for `linux/amd64` and + `linux/arm64` with no runtime dependencies. You do not need to install a Go toolchain + or shared libraries. ```bash VERSION= # e.g. v6.6.1 — see the Network Versions table above - FILE=sei-chain_${VERSION#v}_linux_x86_64.tar.gz # asset filenames omit the leading v + # Pick the asset for your architecture (asset filenames omit the leading v): + FILE=sei-chain_${VERSION#v}_linux_x86_64.tar.gz # linux/amd64 + # FILE=sei-chain_${VERSION#v}_linux_aarch64.tar.gz # linux/arm64 curl -fLO https://github.com/sei-protocol/sei-chain/releases/download/${VERSION}/${FILE} curl -fLO https://github.com/sei-protocol/sei-chain/releases/download/${VERSION}/checksums.txt @@ -138,9 +141,10 @@ For the current recommended version, see the Network Versions table above. Prebuilt binaries are attached from `v6.6.1` onward. For earlier versions, - build from source or use Docker. Prebuilt binaries are `linux/amd64` only and do not - include hardware Ledger support. On other architectures, or if you sign with a Ledger - device, build from source or use Docker. + build from source or use Docker. Prebuilt `linux/arm64` binaries are attached + alongside `linux/amd64` as of v6.8.0. Prebuilt binaries do not include hardware + Ledger support. If you sign with a Ledger device, or need an architecture other + than `linux/amd64` or `linux/arm64`, build from source or use Docker. @@ -193,6 +197,10 @@ For the current recommended version, see the Network Versions table above. Available architectures: linux/amd64 and linux/arm64. + The official image also ships the `seidb` CLI at `/usr/bin/seidb` alongside + `seid`, so you can run `seidb` directly from the container with no extra build + step. + **Never** use the testing-only image variants in production. Sei's continuous integration (CI) pipelines publish these variants to an internal registry. They are not available on `ghcr.io`. The variants are compiled with special Go build tags: @@ -320,7 +328,10 @@ cache-size = 10000 # Do not remove invalid transactions from the cache keep-invalid-txs-in-cache = true -# Maximum size of a single transaction +# Deprecated: this field no longer controls transaction admission or gossip. +# Admission and gossip are governed by a fixed 1 MiB protocol gossip limit +# (MaxGossipTxBytes). Setting a different value only logs a startup warning and +# otherwise has no effect. max-tx-bytes = 2048576 # Maximum size of a batch of transactions to send to a peer diff --git a/node/node-operators.mdx b/node/node-operators.mdx index 052cba21..6b8a7033 100644 --- a/node/node-operators.mdx +++ b/node/node-operators.mdx @@ -27,6 +27,24 @@ $HOME/.sei/config/ The state-store databases live outside the config directory: + + +When Giga Storage is enabled, the ledger stores live under `$HOME/.sei/data/ledger`: + +- The block store is at `$HOME/.sei/data/ledger/block`. +- The receipt store is at `$HOME/.sei/data/ledger/receipt/{backend}`. +- The app hash vault is at `$HOME/.sei/data/ledger/app_hash`. It holds the + giga app hash vault, which persists the app hash of each committed block + alongside the block store and joins the storage garbage collector's shared + prune cycle (it reports as the `AppHashVault` store). On restart, recovery + converges every store onto the lowest head, now including the app hash + vault's: a crash that leaves the state ahead of the vault re-executes the + blocks above the vault head, while a vault left ahead of the state keeps its + app hashes and checks the re-executed blocks against them. The vault's stored + app hashes must belong to the node's configured chain ID, and the node fails + startup on a mismatch. Keep this directory present and consistent when + restarting a Giga node. + - Cosmos SS uses `$HOME/.sei/data/{backend}` in the legacy layout and `$HOME/.sei/data/state_store/cosmos/{backend}` in the current layout. - EVM SS uses `$HOME/.sei/data/evm_ss` in the legacy layout and @@ -130,6 +148,27 @@ defaults to `pebble`. The former `receipt-store.tx-index-backend` config field has been removed. + + +The receipt store records which backend owns its directory in a +`receipt-backend.txt` marker file, written the first time the store is opened. +On every subsequent open, the node checks this marker and refuses to open a +directory that belongs to a different backend — for example, opening a +`littidx` store directory as `pebbledb`, or vice versa, fails loudly with a +mismatch error rather than presenting a silently empty store. The error names +both the backend that owns the directory and the backend that was requested, so +the fix is to either point `db-directory` at the correct backend's store or set +`rs-backend` to the backend that owns the directory. + +For backwards compatibility, a store directory that carries no marker (one +written before markers existed, or a brand-new directory) is adopted by the +configured backend and stamped with the marker on that first open. An +unsupported backend or a config the backend rejects (for example, `pebbledb` +with external pruning enabled) is refused before the directory is touched, so a +rejected attempt never leaves a marker behind that would then refuse the +corrected configuration. + + ### Default configurations This section shows the full unmodified `app.toml`, `config.toml`, and diff --git a/node/node-types.mdx b/node/node-types.mdx index 1bd64b21..6b6a9c0f 100644 --- a/node/node-types.mdx +++ b/node/node-types.mdx @@ -23,8 +23,8 @@ The `seid` binary uses these TCP ports. Change their settings to match your envi - `26657`: The default port for the RPC interface. This port is used to send queries and transactions, so it must be open to serve queries from `seid`. - `1317`: The default port for HTTP RESTful requests to the `seid` API server. Applications and services can use it to interact with the `seid` instance through RPC. - `9090`: The default port for gRPC communication. This port 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. It 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. If 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 two co-located nodes to `9545` and `9546`. -- `8546`: The default port for EVM WebSocket RPC. EVM applications that need WebSocket connections use this port for real-time communication. +- `8545`: The default port for EVM HTTP RPC. This port is used for Ethereum JSON-RPC calls. It must be open if you want to interact with EVM-compatible applications. On Giga/Autobahn nodes, the EVM-only JSON-RPC listener's port is configurable via `giga.execution.evm_rpc_port` (default `8545`, must be in the range 1..65535); it binds on all interfaces. The [`frozen-rpc-router`](/node/technical-reference#frozen-rpc-router) binary also listens on `127.0.0.1:8545` by default. If 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 two co-located nodes to `9545` and `9546`. +- `8546`: The default port for EVM WebSocket RPC. EVM applications that need WebSocket connections use this port for real-time communication. On Giga/Autobahn nodes, the EVM-only JSON-RPC is also served over WebSocket (in addition to HTTP), with its port configurable via `giga.execution.evm_ws_port` (default `8546`, must be in the range 1..65535 and must differ from `evm_rpc_port`); it binds on all interfaces and accepts upgrades from any Origin. This WebSocket endpoint supports `eth_subscribe("newHeads")`, which pushes one Ethereum header per executed block; it requires Autobahn execution and is unavailable otherwise. - `26660`: The default port for the Prometheus metrics endpoint, which you can use to monitor the environment. The node opens it only when `prometheus = true` under `[instrumentation]` in `config.toml`. In the default configuration, this port is not open. Seed nodes serve it too. See [Seed node Prometheus metrics](/node/advanced-config-monitoring#seed-node-prometheus-metrics). You can change all of these ports in `$HOME/.sei/config/config.toml` and `$HOME/.sei/config/app.toml`. diff --git a/node/seictl.mdx b/node/seictl.mdx index f887ae2e..7a2f6c81 100644 --- a/node/seictl.mdx +++ b/node/seictl.mdx @@ -351,7 +351,8 @@ minimum-gas-prices = "0.02usei" [telemetry] enabled = true -prometheus-retention-time = 60 +# A positive value is required to start the Prometheus metrics sink; the sink stays off when this is 0. +prometheus-retention-time = 7200 [api] enable = true diff --git a/node/snapshot.mdx b/node/snapshot.mdx index 129722a1..09d5be64 100644 --- a/node/snapshot.mdx +++ b/node/snapshot.mdx @@ -27,6 +27,9 @@ You can download snapshots from these providers: