From 7c53582c781d8c7dfad7800d4cb48dc46374b7fc Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:44:41 +0000 Subject: [PATCH 01/30] =?UTF-8?q?docs:=20The=20Gov=20precompile=20adds=20t?= =?UTF-8?q?hree=20new=20functions=E2=80=94grantVoteAuthorization,=20voteWi?= =?UTF-8?q?thAuthorization,=20and=20revokeVoteAuthorization=E2=80=94enabli?= =?UTF-8?q?ng=20delegated=20voting=20via=20authz=20grants=20from=20Solidit?= =?UTF-8?q?y/EVM.=20(sei-protocol/sei-chain#3846)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- evm/precompiles/authz.mdx | 6 ++++- evm/precompiles/governance.mdx | 46 ++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/evm/precompiles/authz.mdx b/evm/precompiles/authz.mdx index 02311d9..b115250 100644 --- a/evm/precompiles/authz.mdx +++ b/evm/precompiles/authz.mdx @@ -6,7 +6,11 @@ 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 on this precompile are `view` functions. The precompile is available since v6.7.0. + + +While this precompile is read-only, `authz` grants can also be created and exercised from the EVM for delegated governance voting. The [Governance precompile](/evm/precompiles/gov) exposes `grantVoteAuthorization`, `voteWithAuthorization`, and `revokeVoteAuthorization`, which write a `MsgVote` grant, cast a vote on a granter's behalf, and revoke the grant respectively. These grants are limited to simple `MsgVote` and do not cover weighted votes; they appear here through the `grants` queries like any other `authz` grant. + ## Interface diff --git a/evm/precompiles/governance.mdx b/evm/precompiles/governance.mdx index f76a95e..a6387f1 100644 --- a/evm/precompiles/governance.mdx +++ b/evm/precompiles/governance.mdx @@ -101,6 +101,52 @@ function submitProposal( ) payable external returns (uint64 proposalID); ``` + +#### Delegated voting with authorization + +The governance precompile also supports delegated voting through authz grants. A granter can authorize another account (the grantee) to cast simple votes on their behalf. The authorization is limited to `MsgVote` and does **not** cover weighted votes. + +```solidity +/// Grant an account permission to cast simple votes on behalf of the caller. +/// The authorization is limited to MsgVote and does not cover weighted votes. +/// @param grantee The account receiving the vote authorization. +/// @param expiration Unix timestamp (seconds) after which the authorization is invalid. +/// Must be after the current block time or the transaction reverts. +/// @return success Whether the authorization was successfully granted. +function grantVoteAuthorization( + address grantee, + int64 expiration +) external returns (bool success); + +/// Cast a simple vote on behalf of a voter using a MsgVote authorization +/// previously granted by that voter. The caller must be the grantee. +/// @param voter The account whose vote is being 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 authorized vote was successfully cast. +function voteWithAuthorization( + address voter, + uint64 proposalID, + int32 option +) external returns (bool success); + +/// Revoke a previously granted vote authorization. +/// @param grantee The account whose vote authorization is being revoked. +/// @return success Whether the authorization was successfully revoked. +function revokeVoteAuthorization( + address grantee +) external returns (bool success); +``` + + +**Authorization scope and expiration:** + +- The grant only authorizes simple `MsgVote` votes. It does not allow the grantee to cast weighted votes on the granter's behalf. +- `expiration` is a Unix timestamp in seconds and must be strictly after the current block time, otherwise `grantVoteAuthorization` reverts. +- `voteWithAuthorization` reverts if no valid, unexpired authorization exists from `voter` to the caller. +- Both the granter and grantee accounts must have a Sei address associated with their EVM address. + + ### 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. From 72c0b0ab5dfac5baa524e541909a05c867e6aaac Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:45:49 +0000 Subject: [PATCH 02/30] docs: Adds a new standalone CLI tool `evmonly-loadtest` for feeding synthetic transfer/ERC20/snapshot-revert blocks to the EVM-only executor, with a large set of tunable flags and Prometheus metrics. (sei-protocol/sei-chain#3658) --- node/technical-reference.mdx | 77 ++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 92c06a4..1775676 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -607,6 +607,83 @@ make install BUILD_TAGS=historical_replay A `historical_replay` binary is not safe for consensus. Do not use it to validate, produce blocks, or serve live traffic. Normal builds do not include the lenient decoder. + + +## EVM-only executor load testing + +`evmonly-loadtest` is a standalone executable for feeding synthetic blocks to the EVM-only executor without Cosmos SDK state, mempool, RPC, or chain persistence. It generates workloads, runs them through the executor against mock state and receipt sinks, and reports throughput both on stdout and over a Prometheus endpoint. It is a developer and performance-tuning tool, not part of `seid`. + +The synthetic workload defaults to the local EVM chain ID `1337`; override it with `--chain-id` when testing another signing domain. It can generate pure EVM legacy transfer transactions, ERC20 transfer transactions, and a contract-call workload that exercises nested StateDB snapshot/revert behavior. By default each generated sender account has one nonce-0 transaction and is funded in the command's in-memory genesis state before its block is queued. Recipients are unique by default, so the transfer workloads exercise the optimistic no-overlap case. + +Run it from a `sei-chain` source checkout: + +```bash +go run ./giga/evmonly/cmd/evmonly-loadtest --blocks=1000 --txs-per-block=1000 +``` + +The command prebuilds every block before starting the prepare and executor workers, which isolates executor throughput from block generation. Prebuilding requires `--blocks > 0` and stores every raw block in memory. + +### Workload and economics flags + +- `--workload`: Workload type: `transfer`, `erc20-transfer`, or `snapshot-revert`. The default is `transfer`. +- `--chain-id`: EVM chain ID used to sign and execute transactions (default `1337`). +- `--gas-price-wei`: Legacy transaction gas price in wei (default `1000000000`). +- `--min-gas-price-wei`: Executor minimum gas price in wei (default `1000000000`). Unless `--disable-gas-price-rule` is set, `--gas-price-wei` must be greater than or equal to this value. +- `--sender-balance-wei`: Generated sender genesis balance in wei (default `1000000000000000000`). It must cover the transfer value plus maximum gas cost of each sender's transactions. +- `--transfer-value-wei`: Wei or token units transferred by each generated transaction (default `1`). +- `--tx-gas-limit`: Gas limit for each generated transaction (default `21000` for the transfer workload, `100000` for `erc20-transfer` and `snapshot-revert` unless overridden). +- `--block-gas-limit`: Block gas limit; `0` (the default) lets the executor use its maximum. +- `--coinbase`: Block coinbase address. +- `--erc20-contract`: EVM address for the generated ERC20 transfer contract. +- `--snapshot-revert-contract`, `--snapshot-revert-helper`: Generated contract addresses used by `--workload=snapshot-revert`. They must differ. +- `--disable-gas-price-rule`: Disable the executor min-gas-price validity rule. + +### Recipient and sender shaping flags + +- `--recipient`: Optional fixed transfer recipient. The default (empty) creates one recipient per transaction, so recipients are unique. +- `--recipient-conflict-rate`: Fraction `[0,1]` of each block's transactions paired onto shared recipients; `0` (the default) keeps recipients unique and `1` pairs all possible transactions. It cannot be combined with `--recipient`. +- `--same-sender`: Use one sender per transfer block with sequential transaction nonces. It is only supported with the `transfer` workload. + +These shaping flags expose the three executor OCC scenarios: unique senders and recipients (conflict-free), unique senders all crediting one `--recipient` (hot recipient), and a `--same-sender` nonce chain. + +### Pipeline and concurrency flags + +- `--blocks`: Number of blocks to prebuild and execute. Required and must be greater than `0`. +- `--txs-per-block`: Transactions generated per block (default `1000`). +- `--queue-size`: Buffered raw and prepared blocks (default `64`). +- `--builders`: Parallel block builders used to keep the input queue full. The default is `GOMAXPROCS`. +- `--prepare-workers`: Parallel stateless preparation workers for transaction decode and sender recovery. The default is `GOMAXPROCS`. +- `--parse-workers`: Parallel transaction decode/sender recovery workers inside each prepared block. The default `0` uses `1` when `--prepare-workers > 1`, otherwise `GOMAXPROCS`. +- `--workers`: Parallel executor workers (default `1`). +- `--executor-workers`: Parallel OCC workers inside each executor. The default is `min(12, GOMAXPROCS)`. + +### Result sink and persistence flags + +- `--result-sink`: Executor output sink, either `discard` or `file` (default `discard`). The `discard` sink applies the executor state change set to a discard writer and drops receipts. +- `--result-pool-size`: Reusable executor result slots. The default `0` sizes the pool for in-flight executor and async sink results; a negative value disables result pooling. +- `--persist-dir`: Directory used by `--result-sink=file` for temporary append-only `changesets.rlp` and `receipts.rlp` files. Required when `--result-sink=file`. The files are removed on shutdown or interrupt cleanup. +- `--persist-sync`: fsync persistent result files from the async sink writer. +- `--persist-buffer-size`: Buffered writer size in bytes for `--result-sink=file` (default `4194304`). +- `--persist-queue-size`: Async file-sink record queue size. The default `0` uses `2 * --queue-size`. + +### Observability and profiling flags + +- `--metrics-addr`: Prometheus listen address (default `127.0.0.1:9698`). Set it to empty to disable the HTTP metrics server. +- `--report-interval`: stdout rate reporting interval (default `5s`). `0` disables periodic reports. +- `--cpu-profile`: Write a Go CPU profile to this file; profiling starts after prebuild. +- `--heap-profile`: Write a Go heap profile to this file after execution. +- `--trace-profile`: Write a Go runtime trace to this file; tracing starts after prebuild. + +### Metrics server + +When `--metrics-addr` is set, the command starts an HTTP server exposing two endpoints: + +- `/metrics`: Prometheus metrics for the load test. +- `/healthz`: A liveness probe that returns `ok`. + +The server reports saturation signals including block input, preparation, and finishing throughput; prepared, finished, successful, and failed transactions per second; total gas consumed per second; OCC rerun attempts; queued and cumulative prepared blocks; result-sink records queued, written, bytes written, and enqueue wait; and result-pool capacity, available slots, and overflow allocations. The same rates are also printed to stdout at `--report-interval`. `evmonly_loadtest_result_sink_enqueue_wait_seconds_total` (`sink_enqueue_wait` in the stdout report) is the primary backpressure signal: a non-zero value means executor workers waited for async sink queue capacity. + + ## File locations Understanding the purpose and location of important files helps with maintenance From 04c5f8c04853483b352bbeb242015073a729eea0 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:46:57 +0000 Subject: [PATCH 03/30] docs: Pagination limits/offsets for node-local LCD/gRPC queries are no longer capped (MaxLimit now equals uint64 max, MaxOffset/scan-limit errors removed), while EVM precompile query paths retain the legacy v6.6 limits for consensus safety. (sei-protocol/sei-chain#3867) --- node/technical-reference.mdx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 1775676..c4eb044 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -609,6 +609,21 @@ A `historical_replay` binary is not safe for consensus. Do not use it to validat +## Query pagination limits + +Node-local LCD and gRPC queries no longer cap pagination limits, offsets, or store-scan length. Direct Cosmos queries served by `BaseApp.Query` now page through the full store, so large or sparse stores return complete results instead of errors. + +- **Limit:** `MaxLimit` is now the maximum value of a `uint64`, up from the previous `1000`. A `limit` of `0` still falls back to the default page size. +- **Offset:** There is no longer a maximum offset. The previous cap of `10000` has been removed. +- **Store scans:** `count_total` and sparse-filter queries scan the full store. The previous `scanned more than N entries` errors no longer occur for node-local queries. +- **Upper bound:** Pagination arithmetic is performed in signed `int` space, so `limit` or `offset` values above `math.MaxInt64` are still rejected as negative/invalid. + + + EVM precompile query paths keep the legacy v6.6 pagination behavior — the `1000` limit, `10000` offset, and `10000`-entry scan limit still apply there — because precompiles run during transaction execution, where relaxing these caps would change gas consumption and break AppHash/LastResultsHash determinism. This only affects queries invoked inside EVM execution; client-facing LCD/gRPC queries use the relaxed semantics described above. The modules covered include `authz`, `distribution`, `feegrant`, `gov`, `staking`, and `bank`. + + + + ## EVM-only executor load testing `evmonly-loadtest` is a standalone executable for feeding synthetic blocks to the EVM-only executor without Cosmos SDK state, mempool, RPC, or chain persistence. It generates workloads, runs them through the executor against mock state and receipt sinks, and reports throughput both on stdout and over a Prometheus endpoint. It is a developer and performance-tuning tool, not part of `seid`. From 62898fb7068c18d1a2111b0d14be4ddadb32ae52 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:49:34 +0000 Subject: [PATCH 04/30] docs: The Interchain Accounts (ICA) proto definitions and REST/gRPC query endpoints (including the ICA host and controller params queries) are being removed, meaning the ICA feature and its API endpoints are no longer available. (sei-protocol/sei-chain#3881) --- node/swagger.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/node/swagger.mdx b/node/swagger.mdx index 68b0d8c..1d167a7 100644 --- a/node/swagger.mdx +++ b/node/swagger.mdx @@ -20,4 +20,8 @@ swagger = true After you restart the node, the Swagger docs are available at `http://:/swagger/` (for example, `http://localhost:1317/swagger/`). + + The Interchain Accounts (ICS-27) query endpoints are no longer part of the API. The ICA host params endpoint (`/ibc/apps/interchain_accounts/host/v1/params`), the ICA controller params endpoint (`/ibc/apps/interchain_accounts/controller/v1/params`), and the interchain account lookup endpoint (`/ibc/apps/interchain_accounts/controller/v1/owners/{owner}/connections/{connection_id}`) have been removed and will no longer appear in the Swagger spec. + + The default API port is `1317`. Make sure that the API server is enabled: set `enable = true` in the `[api]` section of your `app.toml`. From 2a388163fd43f0878800dbdfc0f4b2477ce954b3 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:50:49 +0000 Subject: [PATCH 05/30] =?UTF-8?q?docs:=20The=20storage=20garbage=20collect?= =?UTF-8?q?or=20gains=20a=20new=20LookbackWindow=20config=20field=20and=20?= =?UTF-8?q?rewrites=20its=20pruning=20model=20(RollbackWindow=20+=20Lookba?= =?UTF-8?q?ckWindow),=20and=20the=20littblock=20BlockDB=20changes=20its=20?= =?UTF-8?q?default=20retention=20and=20refuses=20to=20open=20pre-rename=20?= =?UTF-8?q?on-disk=20tables=20=E2=80=94=20a=20node-operator=20migration=20?= =?UTF-8?q?concern.=20(sei-protocol/sei-chain#3868)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- node/technical-reference.mdx | 8 ++++++++ node/troubleshooting.mdx | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index c4eb044..2fc50d3 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -305,6 +305,14 @@ Two more flags tune the BlockDB. The command writes their values to the `block_d Both fields are optional. If you set a field, its value must be greater than zero. Autobahn ignores `block_db` when persistence is off. + + + + The LittDB BlockDB on-disk table was renamed from `ledger` to `blocks`. The block DB now refuses to open when a pre-rename `ledger` table directory is still present under one of its data roots, because the blocks and QCs stored under the old name would be neither served nor reclaimed, leaving the store looking healthy and empty while the history you wanted was silently unreachable. Startup fails with an error naming the `ledger` directory and instructing you to delete or move it aside. + + To recover, stop the node, delete (or move aside) the `ledger` directory under `/blockdb` for each affected data root, and restart. The node then starts from an empty BlockDB and refills it from its ingest path. The refusal happens before any new table is created, so a failed start leaves the directory exactly as it found it. + + The command reads these files from each node directory: - `validator_pubkey.txt`: The validator public key in `validator:` format. diff --git a/node/troubleshooting.mdx b/node/troubleshooting.mdx index 69ef919..ff82659 100644 --- a/node/troubleshooting.mdx +++ b/node/troubleshooting.mdx @@ -453,6 +453,42 @@ This means that you did not shut down the node properly. In that case, try to sh Then try the rollback steps again. + + +## BlockDB refuses to open on a pre-rename table + +On Autobahn nodes, the BlockDB stores blocks and QCs in a LittDB-backed table. The +on-disk table was renamed from `ledger` to `blocks`. On startup the block DB now +refuses to open if a pre-rename `ledger` table directory is still present under any +of its root paths (by default `/blockdb`). The old data cannot +be reached under the new name, so opening silently would leave the store looking +healthy and empty while the blocks and QCs it holds would be neither served nor +reclaimed. + +The node fails to start with an error like this: + +```text +block db: found a pre-rename "ledger" table at [/path/to/blockdb/ledger]; the table is now named "blocks", so those blocks and QCs would be neither served nor reclaimed. Delete or move the directory aside to start from an empty store +``` + +The refusal happens before anything is written, so the directory is left exactly as +found — nothing new is created beside the legacy table. + +### Recovery + +To start from an empty store, delete the legacy `ledger` directory or move it aside: + +```bash +# Stop the node first, then either delete the directory... +rm -rf /blockdb/ledger + +# ...or move it aside to keep it for inspection: +mv /blockdb/ledger /blockdb/ledger.bak +``` + +After the directory is gone, restart the node. The block DB opens fresh under the +`blocks` name and refills from its own ingest path. + ## HashVault app-hash equivocation panic Under Autobahn, HashVault halts a node that tries to commit a different app hash for a height it already finalized. For background, see [HashVault](/node/technical-reference#hashvault-app-hash-equivocation-guard). From 8ce9b5aa8692faac4fb3bfcc7835f5ffece82c75 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:51:24 +0000 Subject: [PATCH 06/30] docs: EVM RPC block endpoints (getBlockByHash, getBlockByNumber, GetBlockReceipts) now return a 'receipts have been pruned' error when the requested block's receipt data is no longer available. (sei-protocol/sei-chain#3909) --- evm/reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/evm/reference.mdx b/evm/reference.mdx index 49b295a..174b275 100644 --- a/evm/reference.mdx +++ b/evm/reference.mdx @@ -561,6 +561,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. +Like `eth_getBlockTransactionCountByNumber`, this method verifies that the requested block's receipts have not been pruned from the receipt store before returning. If they have, it returns a "receipts have been pruned" error instead of block data. Because the receipt store can be configured with a smaller `KeepRecent` than the block and state stores, the call can fail for older blocks even when the block data itself is still available. + **Parameters:** | # | Name | Type | Description | From e31f767bf34942250966e30dd943a8e4b19291a7 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:52:24 +0000 Subject: [PATCH 07/30] docs: The entire sei2_* JSON-RPC namespace (seven block methods that included bank transfers in block payloads) has been removed from Sei's EVM HTTP RPC, along with its config allowlist entries. (sei-protocol/sei-chain#3912) --- evm/reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/evm/reference.mdx b/evm/reference.mdx index 174b275..e9ad44e 100644 --- a/evm/reference.mdx +++ b/evm/reference.mdx @@ -18,7 +18,7 @@ By default, the explorer lists only the current methods that are available. Each - **Limited**: The method is callable, but it returns a static value or has a Sei-specific caveat (shown in the method's **Sei-specific behavior** note). For example, `eth_coinbase` returns the fee-collector address. - **Unavailable**: The method is not registered, returns an explicit error, or does not apply to Sei's architecture. This includes blob methods (`eth_blobBaseFee`), proof-of-work and uncle methods, and the `admin`, `miner`, `clique`, `engine`, `les`, and `personal` namespaces. -By default, the explorer hides the remaining deprecated `sei_*` extensions and the unavailable methods. To browse them, enable **Show deprecated & unavailable methods**. The deprecated extensions are also documented under [Sei custom endpoints](#sei-custom-endpoints). +By default, the explorer hides the deprecated `sei_*` extensions and the unavailable methods. To browse them, enable **Show deprecated & unavailable methods**. The deprecated extensions are also documented under [Sei custom endpoints](#sei-custom-endpoints). ## Overview From 8a48019fe63b492bf2f998a8348b85f075651119 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:34:00 +0000 Subject: [PATCH 08/30] docs: Adds authorization (authz) grant/execute/revoke methods to the distribution, gov, slashing, and staking EVM precompiles, letting callers delegate withdrawal, voting, proposal submission, unjailing, and staking actions to a grantee. (sei-protocol/sei-chain#3893) --- evm/precompiles/distribution.mdx | 74 +++++++++++++++++++++++++ evm/precompiles/governance.mdx | 42 +++++++++++++++ evm/precompiles/staking.mdx | 92 ++++++++++++++++++++++++++++++++ 3 files changed, 208 insertions(+) diff --git a/evm/precompiles/distribution.mdx b/evm/precompiles/distribution.mdx index 5678f77..077532d 100644 --- a/evm/precompiles/distribution.mdx +++ b/evm/precompiles/distribution.mdx @@ -37,6 +37,80 @@ interface IDistr { } ``` + +## Authorization (authz) methods + +The distribution precompile supports Cosmos authz grants, so a granter can authorize another account (the grantee) to withdraw its delegation rewards and validator commission on its behalf. `grantWithdrawAuthorization` creates native generic grants for both `MsgWithdrawDelegatorReward` and `MsgWithdrawValidatorCommission`, and `revokeWithdrawAuthorization` removes them as a group. + +```solidity +interface IDistr { + // Authorization methods + function grantWithdrawAuthorization(address grantee, int64 expiration) external returns (bool success); + function withdrawDelegationRewardsWithAuthorization(address delegator, string memory validator) external returns (bool success); + function withdrawValidatorCommissionWithAuthorization(address validatorOperator) external returns (bool success); + function revokeWithdrawAuthorization(address grantee) external returns (bool success); +} +``` + +### grantWithdrawAuthorization + +Authorizes `grantee` to withdraw the caller's delegation rewards and validator commission until `expiration`. + +```solidity +function grantWithdrawAuthorization(address grantee, int64 expiration) external returns (bool success); +``` + +**Parameters:** + +- `grantee`: The account receiving the withdrawal authorization +- `expiration`: Unix timestamp (seconds) after which the authorization is invalid + +The `expiration` must be after the current block time, otherwise the call reverts. The grant covers only `MsgWithdrawDelegatorReward` and `MsgWithdrawValidatorCommission`; it does not cover `setWithdrawAddress`. + +### withdrawDelegationRewardsWithAuthorization + +Withdraws `delegator`'s delegation rewards from a validator using an authorization previously granted by `delegator`. The caller must be the grantee. + +```solidity +function withdrawDelegationRewardsWithAuthorization(address delegator, string memory validator) external returns (bool success); +``` + +**Parameters:** + +- `delegator`: The account whose delegation rewards are withdrawn +- `validator`: The Sei validator address (for example, "seivaloper1...") + +Rewards are sent to the delegator's configured withdrawal address. A `DelegationRewardsWithdrawn` event is emitted with the delegator as the indexed address. + +### withdrawValidatorCommissionWithAuthorization + +Withdraws a validator's earned commission using an authorization previously granted by the validator operator. The caller must be the grantee. + +```solidity +function withdrawValidatorCommissionWithAuthorization(address validatorOperator) external returns (bool success); +``` + +**Parameters:** + +- `validatorOperator`: The validator operator whose commission is withdrawn + +Commission is sent to the operator's configured withdrawal address. A `ValidatorCommissionWithdrawn` event is emitted. + +### revokeWithdrawAuthorization + +Revokes a grantee's reward and commission withdrawal authorization previously granted by the caller. + +```solidity +function revokeWithdrawAuthorization(address grantee) external returns (bool success); +``` + +**Parameters:** + +- `grantee`: The account whose withdrawal authorization is revoked + +Both the granter (caller) and the grantee address arguments must be associated Sei addresses. These methods cannot be called from a `staticcall`. + + ## Setup Install ethers and the Sei EVM bindings, which include the precompile address and ABI: diff --git a/evm/precompiles/governance.mdx b/evm/precompiles/governance.mdx index a6387f1..173a698 100644 --- a/evm/precompiles/governance.mdx +++ b/evm/precompiles/governance.mdx @@ -138,6 +138,48 @@ function revokeVoteAuthorization( ) external returns (bool success); ``` + + +The precompile also supports delegated proposal submission through authz grants. A granter can authorize a grantee to submit proposals on their behalf. The caller supplies the initial deposit through `msg.value`. + +```solidity +/// Grant an account permission to submit proposals on behalf of the caller. +/// @param grantee The account receiving the proposal authorization. +/// @param expiration Unix timestamp (seconds) after which the authorization is invalid. +/// Must be after the current block time or the transaction reverts. +/// @return success Whether the authorization was successfully granted. +function grantProposalAuthorization( + address grantee, + int64 expiration +) external returns (bool success); + +/// Submit a proposal on behalf of a proposer using a MsgSubmitProposal +/// authorization previously granted by that proposer. The caller must be the +/// grantee and supplies the initial deposit through msg.value. +/// @param proposer The account on whose behalf the proposal is submitted. +/// @param proposalJSON JSON string containing the proposal details. +/// @return proposalID The ID of the created proposal. +function submitProposalWithAuthorization( + address proposer, + string calldata proposalJSON +) payable external returns (uint64 proposalID); + +/// Revoke a previously granted proposal authorization. +/// @param grantee The account whose proposal authorization is being revoked. +/// @return success Whether the authorization was successfully revoked. +function revokeProposalAuthorization( + address grantee +) external returns (bool success); +``` + + +**Grant proposal authorization only to a fully trusted account.** The native `MsgSubmitProposal` authorization can also be exercised through a Cosmos `MsgExec` with an arbitrary initial deposit debited from the granter's account. Because proposal deposits can be permanently lost (for example, if a proposal fails to meet the minimum deposit or receives more than 33.4% NoWithVeto votes), a malicious or careless grantee can cause the granter to lose funds. + + + +**Vote vs. proposal authorization scope:** A `grantVoteAuthorization` grant is limited to `MsgVote` and does **not** cover proposal submission or weighted votes. To delegate proposal submission, grant a separate `grantProposalAuthorization`. The two grants are independent: revoking one does not affect the other. + + **Authorization scope and expiration:** diff --git a/evm/precompiles/staking.mdx b/evm/precompiles/staking.mdx index ff85ce3..dd07618 100644 --- a/evm/precompiles/staking.mdx +++ b/evm/precompiles/staking.mdx @@ -219,6 +219,98 @@ function editValidator( ) external returns (bool success); ``` + +### Authorization functions + +The staking precompile also supports [authz](https://docs.cosmos.network/main/build/modules/authz)-style delegation, letting a granter authorize another account (the grantee) to delegate, redelegate, and undelegate on the granter's behalf within explicit validator and token limits. + +```solidity +/// @notice Authorize a grantee to delegate, redelegate, and undelegate within explicit validator and token limits +/// @param grantee The account receiving the staking authorization +/// @param allowedValidators Validators the grantee may target. For redelegation this limits destination validators +/// @param maxTokens Maximum cumulative base-denom amount for each of delegate, redelegate, and undelegate +/// @param expiration Unix timestamp after which the authorization is invalid +/// @dev Creates three native StakeAuthorizations with independent maxTokens budgets. They can be used through this precompile or native Cosmos MsgExec +/// @dev Native MsgExec delegation spends the granter's liquid balance, not the grantee's funds. Grant this permission only to a trusted account +function grantStakingAuthorization( + address grantee, + string[] memory allowedValidators, + uint256 maxTokens, + int64 expiration +) external returns (bool success); + +/// @notice Delegate using an authorization granted by delegator. For this EVM method only, the caller supplies msg.value. +function delegateWithAuthorization( + address delegator, + string memory valAddress +) external payable returns (bool success); + +/// @notice Redelegate using an authorization granted by delegator +/// @dev If a destination delegation exists, this first withdraws its accrued rewards to the delegator's configured withdraw address and resets its reward starting info +function redelegateWithAuthorization( + address delegator, + string memory srcAddress, + string memory dstAddress, + uint256 amount +) external returns (bool success); + +/// @notice Undelegate using an authorization granted by delegator. +function undelegateWithAuthorization( + address delegator, + string memory valAddress, + uint256 amount +) external returns (bool success); + +/// @notice Revoke a grantee's delegate, redelegate, and undelegate authorization. +function revokeStakingAuthorization( + address grantee +) external returns (bool success); +``` + +**How staking authorizations work:** + +- `grantStakingAuthorization` creates three independent native `StakeAuthorization` grants — one each for delegate, redelegate, and undelegate. Each grant has its own `maxTokens` budget, so the `maxTokens` value applies separately to each action type rather than as a shared pool. +- `allowedValidators` scopes which validators the grantee may target. For redelegation this limits the destination validators. At least one allowed validator is required, and `maxTokens` must be positive. +- `delegateWithAuthorization` is `payable`: the caller (grantee) supplies the delegated amount through `msg.value`, following the same 18-decimal wei convention as `delegate()`. `redelegateWithAuthorization` and `undelegateWithAuthorization` take their amounts as parameters in 6-decimal uSEI precision, like `redelegate()` and `undelegate()`. +- Each authorized action draws down the matching grant's `maxTokens` budget. Once a budget is exhausted, further actions of that type are rejected. An action whose amount exceeds the remaining budget is rejected with an insufficient-funds error, and an action whose denom does not match the authorization's `maxTokens` denom is rejected with an invalid-request error. +- `revokeStakingAuthorization` removes all three grants for the grantee at once. + + + +**Native MsgExec spends the granter's liquid balance.** These authorizations create native Cosmos `StakeAuthorization` grants, so the grantee can also exercise them through a Cosmos `MsgExec` outside this precompile. When a delegation is executed through native `MsgExec`, the delegated tokens are debited from the **granter's** liquid balance, not the grantee's. Grant staking authorizations only to a fully trusted account. + + + +#### Grant, use, and revoke a staking authorization + +```typescript +// As the granter (delegator): authorize a grantee to stake on your behalf +const grantee = '0xGranteeEvmAddress...'; +const allowedValidators = ['seivaloper1abc...', 'seivaloper1xyz...']; +const maxTokens = ethers.parseUnits('200', 6); // 200 SEI budget per action type (6 decimals / uSEI) +const expiration = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now (Unix seconds) + +let tx = await staking.grantStakingAuthorization(grantee, allowedValidators, maxTokens, expiration); +await tx.wait(); + +// As the grantee: delegate on behalf of the delegator (payable, 18-decimal wei) +const delegator = '0xDelegatorEvmAddress...'; +const delegateAmount = ethers.parseUnits('1', 18); +tx = await staking.delegateWithAuthorization(delegator, 'seivaloper1abc...', { value: delegateAmount }); +await tx.wait(); + +// As the grantee: redelegate and undelegate (amounts in 6-decimal uSEI) +tx = await staking.redelegateWithAuthorization(delegator, 'seivaloper1abc...', 'seivaloper1xyz...', ethers.parseUnits('0.5', 6)); +await tx.wait(); + +tx = await staking.undelegateWithAuthorization(delegator, 'seivaloper1abc...', ethers.parseUnits('0.5', 6)); +await tx.wait(); + +// As the granter: revoke all three staking authorizations +tx = await staking.revokeStakingAuthorization(grantee); +await tx.wait(); +``` + ### Query functions ```solidity From e4bf9395c95ae4d61890b80b966318ae9c03acfd Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:35:01 +0000 Subject: [PATCH 09/30] docs: The unsafe consensus timeout override config fields (unsafe-propose-timeout-override, unsafe-vote-timeout-override, unsafe-commit-timeout-override, unsafe-bypass-commit-timeout-override, etc.) have been removed from config.toml; consensus timeouts are now set via on-chain genesis consensus_params timeout fields instead. (sei-protocol/sei-chain#3934) --- node/technical-reference.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 2fc50d3..edfea4a 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -550,10 +550,11 @@ ttl-num-blocks = 10 # Consensus Configuration [consensus] wal-file = "data/tendermint/cs.wal/wal" -# Consensus timeouts are governed by on-chain ConsensusParams; the old -# timeout-* keys were removed and produce a startup error if present. -# Local overrides are only possible via the unsafe-*-timeout-override -# keys, which take effect only when unsafe-overrides-enabled = true. +# Consensus timeouts are governed entirely by on-chain genesis +# consensus_params.timeout fields (propose, vote, vote_delta, commit, and +# bypass_commit_timeout). The unsafe-*-timeout-override keys and +# unsafe-overrides-enabled no longer exist in config.toml and have no effect; +# set consensus timeouts in genesis.json instead. double-sign-check-height = 0 ``` From 4ac33e69cf6a2e024621999e9f7ba06553641ee3 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:43:41 +0000 Subject: [PATCH 10/30] docs: EVM trace RPC methods (debug_traceTransaction, debug_traceBlockByNumber/ByHash, debug_traceCall, and trace profile) now honor the caller's context deadline/cancellation during historical state reconstruction, returning the deadline/cancel error instead of a synthesized fake trace result. (sei-protocol/sei-chain#3940) --- evm/reference.mdx | 2 ++ evm/tracing/troubleshooting.mdx | 15 +++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/evm/reference.mdx b/evm/reference.mdx index e9ad44e..d6d9a81 100644 --- a/evm/reference.mdx +++ b/evm/reference.mdx @@ -1143,6 +1143,8 @@ A state override can include up to 100 accounts (`max_state_override_accounts`) The max block lookback guard (`max_trace_lookback_blocks`) applies. If a request's target block is older than the configured lookback, the request is rejected with an error of the form `block number X is beyond max lookback of Y`. Each such request increments the `evmrpc_historical_debug_trace_attempts_total` metric. This guard applies consistently across all `debug_trace*` endpoints. +**Caller deadline during state reconstruction.** When a trace replays a historical block, the caller's RPC/trace deadline (the context deadline, bounded by `trace_timeout`) is propagated into the state-store MVCC iteration used to reconstruct state. If the deadline expires or the call is cancelled while that iteration is running, the method aborts and returns the context deadline/cancellation error (`context.DeadlineExceeded` or `context.Canceled`). It no longer keeps running after the caller has given up, and it no longer returns a synthesized trace result (such as `{"error": "store access cancelled"}`); such a synthesized result is never returned to the caller or written to the trace cache. The same deadline handling applies to `debug_traceBlockByNumber`, `debug_traceBlockByHash`, and `debug_traceCall`. + **Parameters:** | # | Name | Type | Description | diff --git a/evm/tracing/troubleshooting.mdx b/evm/tracing/troubleshooting.mdx index 0e5f125..bbbb52f 100644 --- a/evm/tracing/troubleshooting.mdx +++ b/evm/tracing/troubleshooting.mdx @@ -30,6 +30,21 @@ This guide covers common issues with EVM transaction tracing on Sei and gives pr - Use built-in tracers when possible, because they are faster - Optimize JavaScript tracer code for performance + + +**Deadline and cancellation during historical traces**: + +When a debug trace method reconstructs historical state, the node propagates the RPC/trace deadline into the underlying state-store iteration. If the `trace_timeout` expires (or the caller cancels the request) while the node is still skipping MVCC versions to rebuild the requested block's state, the method aborts and returns the context deadline/cancellation error (`context deadline exceeded` or `context canceled`). + +This applies to `debug_traceTransaction`, `debug_traceBlockByNumber`, `debug_traceBlockByHash`, `debug_traceCall`, and the trace profile method. + +Previously an expired or cancelled trace could return a synthesized fake trace result — for example a result whose body contained `"error": "store access cancelled"` — or keep running after the caller had already given up. The deadline is now honored directly: no synthesized result is returned, and such results are never written to the trace cache. + +**What to do**: + +- Treat a `context deadline exceeded` response as a timeout, not as a valid trace. Increase `trace_timeout` (see below) or narrow the scope of the request (for example, trace a single transaction instead of a whole block). +- If you see this error consistently on older blocks, the historical state reconstruction is taking longer than the configured deadline; tracing a more recent block or raising the timeout usually resolves it. + ### 2. Memory limit errors **Error**: `out of memory` or `memory limit exceeded` From 89d77262c0f434b42ad3896e3b8fb13a0c75b2fd Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:45:38 +0000 Subject: [PATCH 11/30] docs: A new v6.7 upgrade version adds several new EVM precompiles (auth at 0x...100D, authz at 0x...100E, evidence at 0x...100F, feegrant at 0x...1010) and expands existing precompiles (bank, distribution, gov, addr) with new query and authorization methods that developers can call from smart contracts. (sei-protocol/sei-chain#3961) --- docs.json | 3 +- evm/precompiles/distribution.mdx | 132 +++++++++++++++++++++++++++ evm/precompiles/example-usage.mdx | 1 + evm/precompiles/feegrant.mdx | 143 ++++++++++++++++++++++++++++++ evm/precompiles/governance.mdx | 5 ++ 5 files changed, 283 insertions(+), 1 deletion(-) create mode 100644 evm/precompiles/feegrant.mdx diff --git a/docs.json b/docs.json index 8574242..0bc563a 100644 --- a/docs.json +++ b/docs.json @@ -204,7 +204,8 @@ "evm/precompiles/mint", "evm/precompiles/params", "evm/precompiles/slashing", - "evm/precompiles/upgrade" + "evm/precompiles/upgrade", + "evm/precompiles/feegrant" ] } ] diff --git a/evm/precompiles/distribution.mdx b/evm/precompiles/distribution.mdx index 077532d..f4279a0 100644 --- a/evm/precompiles/distribution.mdx +++ b/evm/precompiles/distribution.mdx @@ -338,6 +338,138 @@ Returns the reward information for a delegator across all validators. function rewards(address delegatorAddress) external view returns (Rewards rewards); ``` + + +Since v6.7.0 (#new precompile upgrade), the distribution precompile also exposes additional query methods that mirror the Cosmos SDK distribution module queries. All of these are `view` methods and do not change distribution state. + +```solidity +interface IDistr { + // Additional query methods + function params() external view returns (DistributionParams 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); + function communityPool() external view returns (Coin[] memory pool); +} + +struct DistributionParams { + string communityTax; + string baseProposerReward; + string bonusProposerReward; + bool withdrawAddrEnabled; +} + +struct Slash { + uint64 validatorPeriod; + string fraction; +} +``` + +#### params + +Returns the distribution module parameters. + +```solidity +function params() external view returns (DistributionParams params); +``` + +The returned `communityTax`, `baseProposerReward`, and `bonusProposerReward` are decimal strings, and `withdrawAddrEnabled` reports whether delegators can set a custom withdrawal address. + +#### validatorOutstandingRewards + +Returns the outstanding (not-yet-withdrawn) rewards accrued by a validator. + +```solidity +function validatorOutstandingRewards(string memory validatorAddress) external view returns (Coin[] memory rewards); +``` + +**Parameters:** + +- `validatorAddress`: The Sei validator address (for example, "seivaloper1...") + +Amounts use 18-decimal precision (`DecCoins`), like the `rewards()` query. + +#### validatorCommission + +Returns the commission currently accrued by a validator. + +```solidity +function validatorCommission(string memory validatorAddress) external view returns (Coin[] memory commission); +``` + +**Parameters:** + +- `validatorAddress`: The Sei validator address + +#### validatorSlashes + +Returns the slashing events for a validator within a height range, with pagination. + +```solidity +function validatorSlashes(string memory validatorAddress, uint64 startingHeight, uint64 endingHeight, bytes memory pageKey) external view returns (Slash[] memory slashes, bytes memory nextKey); +``` + +**Parameters:** + +- `validatorAddress`: The Sei validator address +- `startingHeight`: The first block height to include +- `endingHeight`: The last block height to include +- `pageKey`: The pagination key (pass empty bytes for the first page) + +Returns the matching `Slash` entries and the `nextKey` to pass in a subsequent call to fetch the next page. + +#### delegationRewards + +Returns the pending rewards for a specific delegator/validator pair. + +```solidity +function delegationRewards(address delegatorAddress, string memory validatorAddress) external view returns (Coin[] memory rewards); +``` + +**Parameters:** + +- `delegatorAddress`: The delegator's EVM address (must be associated) +- `validatorAddress`: The Sei validator address + +Amounts use 18-decimal precision (`DecCoins`). + +#### delegatorValidators + +Returns the list of validator addresses that a delegator currently delegates to. + +```solidity +function delegatorValidators(address delegatorAddress) external view returns (string[] memory validators); +``` + +**Parameters:** + +- `delegatorAddress`: The delegator's EVM address (must be associated) + +#### delegatorWithdrawAddress + +Returns the configured withdrawal address for a delegator, as a Sei address string. + +```solidity +function delegatorWithdrawAddress(address delegatorAddress) external view returns (string memory withdrawAddress); +``` + +**Parameters:** + +- `delegatorAddress`: The delegator's EVM address (must be associated) + +#### communityPool + +Returns the current community pool balance. + +```solidity +function communityPool() external view returns (Coin[] memory pool); +``` + +Amounts use 18-decimal precision (`DecCoins`). + Since v6.7.0, `rewards()` and the matching gRPC queries (`DelegationRewards` and `DelegationTotalRewards`) do not change distribution state. Repeated calls return the same result. Before v6.7.0, each call incremented the validator period. `debug_trace*` keeps the old behavior when it replays blocks from before v6.7.0. **Data structures:** diff --git a/evm/precompiles/example-usage.mdx b/evm/precompiles/example-usage.mdx index a2929d6..256ada1 100644 --- a/evm/precompiles/example-usage.mdx +++ b/evm/precompiles/example-usage.mdx @@ -25,6 +25,7 @@ Sei precompiles are special smart contracts deployed at fixed addresses. They ex | Auth | `0x000000000000000000000000000000000000100D` | Query accounts, auth parameters, and the next account number | | Authz | `0x000000000000000000000000000000000000100E` | Query authz grants | | Evidence | `0x000000000000000000000000000000000000100F` | Query evidence of validator misbehavior | +| Feegrant | `0x0000000000000000000000000000000000001010` | Query fee allowances by grantee and granter | | P256 | `0x0000000000000000000000000000000000001011` | Verify P-256 elliptic curve signatures | | Mint | `0x0000000000000000000000000000000000001012` | Query mint parameters and the minter state | | Params | `0x0000000000000000000000000000000000001013` | Query module parameters by subspace and key | diff --git a/evm/precompiles/feegrant.mdx b/evm/precompiles/feegrant.mdx new file mode 100644 index 0000000..04dbb3f --- /dev/null +++ b/evm/precompiles/feegrant.mdx @@ -0,0 +1,143 @@ +--- +title: Feegrant Precompile +description: Query fee allowances granted between accounts from EVM smart contracts on Sei. +--- + +The feegrant precompile exposes the Cosmos `feegrant` module's query methods to EVM smart contracts, letting Solidity code read the fee allowances that one account (the granter) has granted another account (the grantee) to pay fees on its behalf. It was added in the v6.7 upgrade (#3618). + +## Address + +The feegrant precompile is available at the fixed address: + +``` +0x0000000000000000000000000000000000001010 +``` + +All methods are `view` functions; the precompile exposes no state-mutating operations. + +## Interface + +```solidity +interface IFeegrant { + struct Grant { + string granter; + string grantee; + bytes allowance; + } + + struct AllowancesResponse { + Grant[] allowances; + bytes nextKey; + } + + function allowance( + address granter, + address grantee + ) external view returns (Grant memory grant); + + function allowances( + address grantee, + bytes memory pageKey + ) external view returns (AllowancesResponse memory response); + + function allowancesByGranter( + address granter, + bytes memory pageKey + ) external view returns (AllowancesResponse memory response); +} +``` + +### Types + +#### Grant + +| Field | Type | Description | +| ----------- | -------- | --------------------------------------------------------------------------- | +| `granter` | `string` | Bech32 address of the account that granted the allowance. | +| `grantee` | `string` | Bech32 address of the account that may spend fees against the allowance. | +| `allowance` | `bytes` | The fee allowance encoded as JSON. | + +#### AllowancesResponse + +| Field | Type | Description | +| ------------ | --------- | ---------------------------------------------------------------------------------------- | +| `allowances` | `Grant[]` | The page of grants returned by the query. | +| `nextKey` | `bytes` | Pagination key for the next page. Pass it back as `pageKey` to continue; empty when done. | + +## Methods + +### allowance + +Returns the fee allowance that `granter` has granted to `grantee`, if one exists. + +```solidity +function allowance( + address granter, + address grantee +) external view returns (Grant memory grant); +``` + +| Parameter | Type | Description | +| --------- | --------- | -------------------------------------------------- | +| `granter` | `address` | EVM address of the account that granted the fees. | +| `grantee` | `address` | EVM address of the account allowed to spend them. | + +Both addresses must be associated with Sei accounts. The call reverts if no allowance exists between the two accounts. + +### allowances + +Returns all fee allowances granted to a given grantee, with pagination. + +```solidity +function allowances( + address grantee, + bytes memory pageKey +) external view returns (AllowancesResponse memory response); +``` + +| Parameter | Type | Description | +| --------- | --------- | --------------------------------------------------------------------- | +| `grantee` | `address` | EVM address of the grantee whose incoming allowances to list. | +| `pageKey` | `bytes` | Pagination key; pass empty bytes for the first page. | + +### allowancesByGranter + +Returns all fee allowances issued by a given granter, with pagination. + +```solidity +function allowancesByGranter( + address granter, + bytes memory pageKey +) external view returns (AllowancesResponse memory response); +``` + +| Parameter | Type | Description | +| --------- | --------- | --------------------------------------------------------------------- | +| `granter` | `address` | EVM address of the granter whose issued allowances to list. | +| `pageKey` | `bytes` | Pagination key; pass empty bytes for the first page. | + +## Usage + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +IFeegrant constant FEEGRANT = IFeegrant(0x0000000000000000000000000000000000001010); + +contract FeegrantReader { + function getAllowance( + address granter, + address grantee + ) external view returns (IFeegrant.Grant memory) { + return FEEGRANT.allowance(granter, grantee); + } + + function getAllowancesByGranter( + address granter + ) external view returns (IFeegrant.Grant[] memory) { + return FEEGRANT.allowancesByGranter(granter, "").allowances; + } +} +``` + +The `allowance` field in each `Grant` is returned as JSON-encoded bytes describing the underlying fee allowance; decode it off-chain to inspect the allowance type and its spend limits or expiration. diff --git a/evm/precompiles/governance.mdx b/evm/precompiles/governance.mdx index 173a698..037103c 100644 --- a/evm/precompiles/governance.mdx +++ b/evm/precompiles/governance.mdx @@ -296,6 +296,11 @@ function tallyResult( ) external view returns (TallyResultData memory tallyResult); ``` + + +**Query methods available as of v6.7:** The `proposal`, `proposals`, `getVote`, `votes`, `params`, `getDeposit`, `deposits`, and `tallyResult` read-only methods let contracts inspect governance state directly from the precompile. They run on a branched context and never mutate chain state, so a `tallyResult` call does not consume votes even though the underlying tally logic deletes votes as it counts. + + ## Using the contract ### Setup From 4548320c0341dd09ace5f489a201aff8d284ac7b Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:47:01 +0000 Subject: [PATCH 12/30] docs: Bank, gov, and staking modules now enforce recipient deliverability checks (CanSendTo/BlockedAddr) so that undelegation, deposit refunds, and unbonding to invalid/blocked recipients are retained rather than sent, changing on-chain behavior for node operators and developers. (sei-protocol/sei-chain#3956) --- evm/precompiles/governance.mdx | 5 +++++ evm/precompiles/staking.mdx | 8 ++++++++ node/validators.mdx | 11 +++++++++++ 3 files changed, 24 insertions(+) diff --git a/evm/precompiles/governance.mdx b/evm/precompiles/governance.mdx index 037103c..920e339 100644 --- a/evm/precompiles/governance.mdx +++ b/evm/precompiles/governance.mdx @@ -37,6 +37,11 @@ Sei governance follows a structured timeline with specific parameters: To learn more about the governance process on Sei, read the [governance explainer](/learn/general-governance). + + +**Deposit refunds skip undeliverable depositors.** When a proposal's deposits are refunded, any deposit whose depositor is a blocked address or cannot currently receive funds is skipped rather than returned. Such deposits remain recorded against the proposal and stay backed by the governance module balance. Recovering a permanently undeliverable deposit requires a chain migration; it is not returned automatically. + + **Critical Sei Mainnet considerations:** diff --git a/evm/precompiles/staking.mdx b/evm/precompiles/staking.mdx index dd07618..678a623 100644 --- a/evm/precompiles/staking.mdx +++ b/evm/precompiles/staking.mdx @@ -825,6 +825,14 @@ function undelegateFromValidator( Undelegated tokens have a **21-day unbonding period**. During this period, you cannot transfer them, and they do not earn rewards. + + + +**Undelegation to an unreceivable address is retained, not returned.** When a matured unbonding delegation completes, the staking module now checks whether the delegator address can receive funds. If the address is blocked or cannot receive funds, the matured unbonding delegation is retained rather than completed: the unbonding record and the pool balance are kept intact, and the tokens are not transferred back to the delegator at the end of the unbonding period. Because the record is retained, such entries may continue to appear in `delegatorUnbondingDelegations()`, `validatorUnbondingDelegations()`, and `unbondingDelegation()` queries after their `completionTime` has passed. Recovering funds for a permanently unreceivable recipient requires a chain migration. + + + + ### Redelegate tokens diff --git a/node/validators.mdx b/node/validators.mdx index 8472bb9..870a530 100644 --- a/node/validators.mdx +++ b/node/validators.mdx @@ -200,6 +200,17 @@ Another critical role for validators is to review proposed software upgrades to Anyone who pays the mandatory (refundable) deposit may submit a governance proposal. Any network user can vote on a proposal. Only votes from accounts that delegate $SEI at the end of a proposal's voting period are given weight. + +### Recipient deliverability for refunds and payouts + +The bank, gov, and staking modules enforce a recipient deliverability check before moving funds to delegators and depositors. When a recipient address cannot receive funds (fails the `CanSendTo` check) or is a blocked address (`BlockedAddr`), the transfer is retained rather than completed. This is an on-chain behavior change that affects validators and their delegators: + +- **Undelegation:** `UndelegateCoins` now returns `ErrInvalidRecipient` if the delegator address cannot receive funds. The operation is atomic — no balances are moved when the check fails. +- **Governance deposit refunds:** `RefundDeposits` skips refunding deposits whose depositor is a blocked address or cannot receive funds. Such deposits remain recorded and stay backed by the governance module balance. Recovering a permanently unreceivable deposit requires a migration. +- **Matured unbonding:** The staking `EndBlocker` retains an unbonding delegation whose recipient cannot receive funds, keeping the unbonding record and pool balance intact instead of completing the transfer. + +If a delegator or depositor is using an address that cannot receive funds, their undelegations, deposit refunds, and matured unbondings will not settle until the address becomes deliverable. + You can query the proposals that are currently on chain at any time: ```bash From 23ad5f6975634985211e49e5a4d706b99110022d Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:47:43 +0000 Subject: [PATCH 13/30] docs: The oracle module is now deprecated (all its messages and queries, plus the CLI/precompile paths, return an 'oracle module is deprecated' error), gasless transactions are removed (oracle votes and MsgAssociate now require fees and count toward block gas), and the native MsgAssociate handler is deprecated. (sei-protocol/sei-chain#3944) --- evm/precompiles/oracle.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/evm/precompiles/oracle.mdx b/evm/precompiles/oracle.mdx index fe03d9e..a6390f2 100644 --- a/evm/precompiles/oracle.mdx +++ b/evm/precompiles/oracle.mdx @@ -8,4 +8,6 @@ keywords: ['oracle precompile', 'retired', 'oracle migration', 'chainlink', 'pyt **Retired as of v6.4.0:** Migrate to a third-party oracle provider, such as [Chainlink](/evm/oracles/chainlink), [Pyth](/evm/oracles/pyth-network), [RedStone](/evm/oracles/redstone), or [API3](/evm/oracles/api3). The native Sei Oracle precompile is retired, and on-chain oracle data queries are disabled. A call to `getExchangeRates` or `getOracleTwaps` reverts with the error `oracle precompile is retired; oracle data queries are disabled`. +The underlying oracle module is now deprecated as well. All oracle module messages and queries fail with the error `oracle module is deprecated` (`ErrOracleDeprecated`), including CLI queries such as `seid q oracle params` and `seid q oracle twaps`, CLI transactions such as `seid tx oracle aggregate-vote` and `seid tx oracle set-feeder`, and the CosmWasm oracle bindings (`OracleExchangeRates`, `OracleTwaps`). + To read a current SEI/USD price instead, follow the [Read a price feed](/evm/cookbook/read-a-price-feed) recipe. From 21c6f226ba07cc5774a4b9832e3fc7fa26868426 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:49:22 +0000 Subject: [PATCH 14/30] docs: The feegrant module is removed from Sei: feegrant execution, module APIs, REST endpoints, and the unreleased feegrant EVM precompile are gone, and transactions with a fee granter different from the payer are now rejected. (sei-protocol/sei-chain#3958) --- evm/precompiles/example-usage.mdx | 1 - evm/precompiles/feegrant.mdx | 6 +++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/evm/precompiles/example-usage.mdx b/evm/precompiles/example-usage.mdx index 256ada1..a2929d6 100644 --- a/evm/precompiles/example-usage.mdx +++ b/evm/precompiles/example-usage.mdx @@ -25,7 +25,6 @@ Sei precompiles are special smart contracts deployed at fixed addresses. They ex | Auth | `0x000000000000000000000000000000000000100D` | Query accounts, auth parameters, and the next account number | | Authz | `0x000000000000000000000000000000000000100E` | Query authz grants | | Evidence | `0x000000000000000000000000000000000000100F` | Query evidence of validator misbehavior | -| Feegrant | `0x0000000000000000000000000000000000001010` | Query fee allowances by grantee and granter | | P256 | `0x0000000000000000000000000000000000001011` | Verify P-256 elliptic curve signatures | | Mint | `0x0000000000000000000000000000000000001012` | Query mint parameters and the minter state | | Params | `0x0000000000000000000000000000000000001013` | Query module parameters by subspace and key | diff --git a/evm/precompiles/feegrant.mdx b/evm/precompiles/feegrant.mdx index 04dbb3f..d478fb7 100644 --- a/evm/precompiles/feegrant.mdx +++ b/evm/precompiles/feegrant.mdx @@ -3,7 +3,11 @@ title: Feegrant Precompile description: Query fee allowances granted between accounts from EVM smart contracts on Sei. --- -The feegrant precompile exposes the Cosmos `feegrant` module's query methods to EVM smart contracts, letting Solidity code read the fee allowances that one account (the granter) has granted another account (the grantee) to pay fees on its behalf. It was added in the v6.7 upgrade (#3618). + + The feegrant EVM precompile has been removed along with the rest of the feegrant module (#3958). It was never released on a live network. The precompile keepers no longer register `FeegrantQuerier`, so this precompile is not available at any address. Transactions that specify a fee granter different from the fee payer are now rejected, and fees are always deducted from the fee payer. The feegrant store remains mounted for historical state access only. This page is retained for historical reference; the interface described below is no longer callable. + + +The feegrant precompile previously exposed the Cosmos `feegrant` module's query methods to EVM smart contracts, letting Solidity code read the fee allowances that one account (the granter) had granted another account (the grantee) to pay fees on its behalf. ## Address From d918d188739822d5d2b154ee99759dadb71a9253 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:50:06 +0000 Subject: [PATCH 15/30] docs: The state store (SS) can now roll back to a target version alongside the commit store during RollbackToVersion, with new behavior around snapshot requirements, changelog retention, and crash recovery, plus a warning when the state store cannot follow the rollback. (sei-protocol/sei-chain#3967) --- node/troubleshooting.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/node/troubleshooting.mdx b/node/troubleshooting.mdx index ff82659..347cb5c 100644 --- a/node/troubleshooting.mdx +++ b/node/troubleshooting.mdx @@ -441,6 +441,20 @@ Next, roll back the node: seid rollback ``` +This rewinds the commit store and Tendermint to the target version. It now also rolls back the state store (SS) to that version when possible, so SS no longer silently stays ahead of the commit store after a rollback. + +The state store can only follow the rollback when it has a snapshot at or below the target. State store rollback requires the `pebbledb` backend and does not support `evm-ss-split`. Because snapshots are off under the default configuration, the state store cannot be rolled back on a default node and will stay ahead of the commit store. + +When the state store cannot follow — it has no rollback support, no snapshot at or below the target, or `evm-ss-split` is enabled — the rollback of the commit store and Tendermint still proceeds, and the command prints a warning like this: + +```text +WARNING: state store rollback skipped: ... +WARNING: the commit store and Tendermint roll back to version [TARGET] while the state store stays at version [SS_VERSION] +WARNING: rebuild the state store from state sync unless the chain replays the same blocks above version [TARGET] +``` + +If you see this warning, rebuild the state store from [state sync](/node/statesync) unless the chain replays the same blocks above the target — re-execution rewrites the keys the replayed blocks write, but keys written only by the discarded blocks keep their old values. To enable state store rollback going forward, run with the `pebbledb` backend, state store snapshots enabled, and `evm-ss-split` disabled. + Then, restart the node. If you see this error when you try to roll back: From 8556c03a44556a17ec03c9c15e134df6dd429838 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 12:36:45 +0000 Subject: [PATCH 16/30] docs: IBC transfer (ICS-20) support is removed in v6.7, including CLI commands, REST/gRPC transfer query endpoints, CosmWasm transfer messages, and the IBC EVM precompile's transfer/client/connection/channel keeper injection; pre-v6.7 transfer history must be served by v6.6 freeze nodes. (sei-protocol/sei-chain#3981) --- node/frozen-nodes.mdx | 2 ++ node/swagger.mdx | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/node/frozen-nodes.mdx b/node/frozen-nodes.mdx index 7fcd07a..da14a12 100644 --- a/node/frozen-nodes.mdx +++ b/node/frozen-nodes.mdx @@ -11,6 +11,8 @@ A frozen node is a full node that stops one block before an upgrade height. It r An upgrade can remove modules and stores that earlier heights depend on. After the upgrade, queries for those heights can fail on the new release or give different results. A node that still runs the outgoing release answers them the way the chain did at the time. +The v6.7 upgrade is a concrete example. It removes IBC transfer (ICS-20) execution, the transfer REST and gRPC query endpoints, the transfer CLI commands, and the IBC EVM precompile's transfer, client, connection, and channel keeper injection. v6.7 nodes no longer serve transfer queries, decode historical transfer transactions, or trace pre-v6.7 IBC precompile calls. If you need any of these, serve them from a v6.6 freeze node, which still runs the outgoing release that supported them. + Freeze mode runs such a node. You set `freeze-height` to the upgrade height. The node executes every block below that height and stops before the upgrade block. It does not halt or exit at the boundary. It keeps serving queries from the state at `freeze-height - 1`, which is also its latest block. From startup, freeze mode changes the node like this: diff --git a/node/swagger.mdx b/node/swagger.mdx index 1d167a7..4ee6ffc 100644 --- a/node/swagger.mdx +++ b/node/swagger.mdx @@ -24,4 +24,8 @@ After you restart the node, the Swagger docs are available at `http://: The Interchain Accounts (ICS-27) query endpoints are no longer part of the API. The ICA host params endpoint (`/ibc/apps/interchain_accounts/host/v1/params`), the ICA controller params endpoint (`/ibc/apps/interchain_accounts/controller/v1/params`), and the interchain account lookup endpoint (`/ibc/apps/interchain_accounts/controller/v1/owners/{owner}/connections/{connection_id}`) have been removed and will no longer appear in the Swagger spec. + + Starting with v6.7, IBC transfer (ICS-20) support has been removed, and the transfer query endpoints are no longer part of the API. The escrow address endpoint (`/ibc/apps/transfer/v1/channels/{channel_id}/ports/{port_id}/escrow_address`), the denom hash endpoint (`/ibc/apps/transfer/v1/denom_hashes/{trace}`), the denom traces endpoints (`/ibc/apps/transfer/v1/denom_traces` and `/ibc/apps/transfer/v1/denom_traces/{hash}`), and the transfer params endpoint (`/ibc/apps/transfer/v1/params`) have been removed and will no longer appear in the Swagger spec. To query pre-v6.7 transfer history, run a v6.6 freeze node. + + The default API port is `1317`. Make sure that the API server is enabled: set `enable = true` in the `[api]` section of your `app.toml`. From 51e026d0587c314cd839f3fef6278276dbbf2d46 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 12:39:23 +0000 Subject: [PATCH 17/30] docs: Sei v6.7 removes all IBC query APIs (gRPC, REST, Protobuf, raw ABCI store, and native CosmWasm queries) along with IBC CLI query commands; retired IBC/transfer/capability store queries now return an ErrIBCDeprecated error and must be served by v6.6 freeze nodes. (sei-protocol/sei-chain#4002) --- node/frozen-nodes.mdx | 2 +- node/swagger.mdx | 6 ++++++ node/technical-reference.mdx | 14 ++++++++++++++ 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/node/frozen-nodes.mdx b/node/frozen-nodes.mdx index da14a12..d92c0be 100644 --- a/node/frozen-nodes.mdx +++ b/node/frozen-nodes.mdx @@ -11,7 +11,7 @@ A frozen node is a full node that stops one block before an upgrade height. It r An upgrade can remove modules and stores that earlier heights depend on. After the upgrade, queries for those heights can fail on the new release or give different results. A node that still runs the outgoing release answers them the way the chain did at the time. -The v6.7 upgrade is a concrete example. It removes IBC transfer (ICS-20) execution, the transfer REST and gRPC query endpoints, the transfer CLI commands, and the IBC EVM precompile's transfer, client, connection, and channel keeper injection. v6.7 nodes no longer serve transfer queries, decode historical transfer transactions, or trace pre-v6.7 IBC precompile calls. If you need any of these, serve them from a v6.6 freeze node, which still runs the outgoing release that supported them. +The v6.7 upgrade is a concrete example. It removes IBC transfer (ICS-20) execution, the transfer REST and gRPC query endpoints, the transfer CLI commands, and the IBC EVM precompile's transfer, client, connection, and channel keeper injection. It also removes the IBC core query APIs — gRPC, REST, Protobuf, raw ABCI store, and native CosmWasm queries — along with the IBC CLI query commands. The removed IBC REST and gRPC endpoints include paths such as `/ibc/core/channel/v1/channels`, `/ibc/core/client/v1/client_states`, and `/ibc/core/connection/v1/connections`. Raw ABCI store queries against the retired IBC-related stores (`/store/ibc/key`, `/store/transfer/key`, `/store/capability/key`, and their `/subspace` variants) now return an `ErrIBCDeprecated` error. v6.7 nodes no longer serve IBC or transfer queries, decode historical transfer transactions, or trace pre-v6.7 IBC precompile calls. If you need any of these, serve them from a v6.6 freeze node, which still runs the outgoing release that supported them. Freeze mode runs such a node. You set `freeze-height` to the upgrade height. The node executes every block below that height and stops before the upgrade block. It does not halt or exit at the boundary. It keeps serving queries from the state at `freeze-height - 1`, which is also its latest block. diff --git a/node/swagger.mdx b/node/swagger.mdx index 4ee6ffc..3745251 100644 --- a/node/swagger.mdx +++ b/node/swagger.mdx @@ -28,4 +28,10 @@ After you restart the node, the Swagger docs are available at `http://: Starting with v6.7, IBC transfer (ICS-20) support has been removed, and the transfer query endpoints are no longer part of the API. The escrow address endpoint (`/ibc/apps/transfer/v1/channels/{channel_id}/ports/{port_id}/escrow_address`), the denom hash endpoint (`/ibc/apps/transfer/v1/denom_hashes/{trace}`), the denom traces endpoints (`/ibc/apps/transfer/v1/denom_traces` and `/ibc/apps/transfer/v1/denom_traces/{hash}`), and the transfer params endpoint (`/ibc/apps/transfer/v1/params`) have been removed and will no longer appear in the Swagger spec. To query pre-v6.7 transfer history, run a v6.6 freeze node. + + + + Starting with v6.7, the IBC core query APIs have been removed, so the IBC channel, client, and connection query endpoints are no longer part of the API. Paths such as `/ibc/core/channel/v1/channels`, `/ibc/core/client/v1/client_states`, and `/ibc/core/connection/v1/connections` (along with the rest of the IBC core channel, client, and connection query paths) have been removed and will no longer appear in the Swagger spec. The remaining non-IBC query endpoints (epoch, evm, mint, oracle, tokenfactory) stay available. To query pre-v6.7 IBC history, run a v6.6 freeze node. + + The default API port is `1317`. Make sure that the API server is enabled: set `enable = true` in the `[api]` section of your `app.toml`. diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index edfea4a..7309e31 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -627,6 +627,20 @@ Node-local LCD and gRPC queries no longer cap pagination limits, offsets, or sto - **Store scans:** `count_total` and sparse-filter queries scan the full store. The previous `scanned more than N entries` errors no longer occur for node-local queries. - **Upper bound:** Pagination arithmetic is performed in signed `int` space, so `limit` or `offset` values above `math.MaxInt64` are still rejected as negative/invalid. + + +## Retired IBC store queries + +Starting with v6.7, the IBC core query APIs are removed from v6.7 nodes, including raw ABCI store queries against the retired IBC-related stores. Querying any of the following store paths now returns an `ibccoretypes.ErrIBCDeprecated` error instead of store data: + +- `/store/ibc/key` and `/store/ibc/subspace` +- `/store/transfer/key` and `/store/transfer/subspace` +- `/store/capability/key` and `/store/capability/subspace` + +The `ibc`, `transfer`, and `capability` stores remain mounted for historical state access in freeze mode, but direct ABCI store queries against them are intercepted and rejected on v6.7 nodes. Queries against other stores (for example, `/store/bank/key`) are unaffected. + +To serve pre-v6.7 IBC query history, run a [v6.6 freeze node](/node/frozen-nodes). + EVM precompile query paths keep the legacy v6.6 pagination behavior — the `1000` limit, `10000` offset, and `10000`-entry scan limit still apply there — because precompiles run during transaction execution, where relaxing these caps would change gas consumption and break AppHash/LastResultsHash determinism. This only affects queries invoked inside EVM execution; client-facing LCD/gRPC queries use the relaxed semantics described above. The modules covered include `authz`, `distribution`, `feegrant`, `gov`, `staking`, and `bank`. From 0027fb1e3738479cf4cb788f3447d12b45227e13 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 12:40:54 +0000 Subject: [PATCH 18/30] =?UTF-8?q?docs:=20IBC=20messages=20are=20now=20depr?= =?UTF-8?q?ecated/retired=20on=20Sei=20=E2=80=94=20any=20transaction=20con?= =?UTF-8?q?taining=20an=20IBC=20message=20(prefixed=20with=20/ibc.)=20is?= =?UTF-8?q?=20rejected=20at=20the=20ante=20handler=20with=20an=20ErrIBCDep?= =?UTF-8?q?recated=20error.=20(sei-protocol/sei-chain#4010)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cosmos-sdk/index.mdx | 2 ++ node/technical-reference.mdx | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/cosmos-sdk/index.mdx b/cosmos-sdk/index.mdx index ffac824..e514527 100644 --- a/cosmos-sdk/index.mdx +++ b/cosmos-sdk/index.mdx @@ -16,6 +16,8 @@ In addition, [Proposal 115](https://seistream.app/proposals/115) disables CosmWa **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. +IBC messaging is now retired at the protocol level: any transaction containing a message whose type URL begins with `/ibc.` is rejected outright with an `ErrIBCDeprecated` error. The IBC ante decorator rejects such transactions before they enter the mempool, and the message service router returns the same error if one is routed, so IBC messages are no longer processed or executed. + ## Tokenfactory is not supported diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 7309e31..e5dfd14 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -641,6 +641,14 @@ The `ibc`, `transfer`, and `capability` stores remain mounted for historical sta To serve pre-v6.7 IBC query history, run a [v6.6 freeze node](/node/frozen-nodes). + + +### Retired IBC messages + +Along with the removal of IBC store queries, IBC messaging is retired on-chain. Any transaction that carries a message whose type URL begins with the `/ibc.` prefix is now rejected. The IBC ante decorator checks every transaction's messages and returns an `ErrIBCDeprecated` error as soon as it finds an IBC message, so these transactions are turned away at the ante handler (including during `CheckTx`, before they can enter the mempool). The `MsgServiceRouter` handler for IBC messages returns the same `ErrIBCDeprecated` error, so no IBC message is routed or executed on v6.7 nodes. + +Previously, the IBC ante decorator only performed redundancy checks on packet messages (`RecvPacket`, `Acknowledgement`, `Timeout`, and `UpdateClient`) and rejected fully redundant relayer transactions with `ErrRedundantTx`. That redundancy logic is gone; all IBC messages are now rejected outright. + EVM precompile query paths keep the legacy v6.6 pagination behavior — the `1000` limit, `10000` offset, and `10000`-entry scan limit still apply there — because precompiles run during transaction execution, where relaxing these caps would change gas consumption and break AppHash/LastResultsHash determinism. This only affects queries invoked inside EVM execution; client-facing LCD/gRPC queries use the relaxed semantics described above. The modules covered include `authz`, `distribution`, `feegrant`, `gov`, `staking`, and `bank`. From a3b3ec6c4bb119efea229f226f8a83d1bd16617c Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 12:41:45 +0000 Subject: [PATCH 19/30] docs: A new internal config registry feature adds mode-aware resolution of Cosmos server config keys, refuses unknown node modes, and reports environment variables that cannot supply certain keys (e.g. telemetry.global-labels), affecting how config defaults resolve per node mode. (sei-protocol/sei-chain#3977) --- node/node-operators.mdx | 23 +++++++++++++++++++++++ node/technical-reference.mdx | 9 +++++++++ 2 files changed, 32 insertions(+) diff --git a/node/node-operators.mdx b/node/node-operators.mdx index 052cba2..159461c 100644 --- a/node/node-operators.mdx +++ b/node/node-operators.mdx @@ -956,6 +956,29 @@ The generated comments above do not describe two behaviors. First, everything. Second, when `evm-ss-db-directory` is unset, nodes with an existing `/data/evm_ss` directory keep using that legacy path. New nodes default to `/data/state_store/evm/{backend}`. + + + +The values above for `api.enable`, `grpc.enable`, and `min-retain-blocks` are +not uniform across node types. These keys resolve per node mode: + +- `api.enable` and `grpc.enable` are **on** for full and archive nodes, and + **off** for validator and seed nodes. Serving queries is what full and + archive nodes are for, while validator and seed nodes are meant to expose as + little as possible. (The upstream default of on for every kind is overridden.) +- `min-retain-blocks` is `100000` for full nodes and `0` (keep everything) for + validator, seed, and archive nodes. + +Only the four declared modes — `validator`, `full`, `seed`, and `archive` — are +accepted; an unrecognized mode is refused with an error naming the declared +modes rather than silently resolving as a full node. + +Separately, a few keys whose value shape cannot be carried by a single string — +notably `telemetry.global-labels` — cannot be set through an environment +variable. If a variable is set for such a key it is read but ignored (the file +value applies instead) and the key is reported as ignored. Plain values and +comma-separated lists of single words are still supported through the +environment. diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index e5dfd14..687a05c 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -48,6 +48,15 @@ The experimental `SEI_CONFIG_MANAGER` environment variable selects how `seid` lo SEI_CONFIG_MANAGER=v2 seid start ``` + +##### Mode-aware config resolution + +When the experimental config manager resolves configuration defaults, it now takes the node mode into account and is stricter about what it accepts. + +- **Unrecognized node modes are rejected.** Resolution accepts only the declared modes — `validator`, `full`, `seed`, and `archive`. An unrecognized value (including an empty string, a capitalized name, or one with a trailing space) no longer silently falls back to full-node defaults. Instead, resolution returns an error naming the modes the binary declares defaults for. This matters because mode-dependent defaults differ: `api.enable` and `grpc.enable` are on for `full` and `archive` nodes and off for `validator` and `seed`, and `min-retain-blocks` is `100000` for a full node. A mode that was quietly treated as a full node would have opened the interfaces a full node serves onto whatever asked. +- **Some keys cannot be supplied by an environment variable.** An environment variable holds a single string — a value for anything read as a single word or number, and by convention a comma-separated list of those. A key whose value shape is something else (for example `telemetry.global-labels`, which is a list of structured rows) cannot be carried this way. When a variable is set for such a key, it is read but ignored: the file value applies instead, and the key is reported as ignored so the operator can see that the variable did nothing. Plain values and comma-separated lists of words are still accepted from the environment as before. + + #### Freeze mode (`--freeze-height`) As of v6.6.3, you can put a full node into read-only freeze mode at a specified block height. Use the `--freeze-height` start flag or the corresponding `freeze-height` field in `app.toml`. Freeze mode exists for historical RPC nodes. A node frozen at an upgrade height keeps running the pre-upgrade binary and keeps serving the state that binary produced. It does not shut down at the boundary or execute the upgrade block with code that no longer matches that state. For setup steps and the freeze heights of each network, see [Run frozen nodes](/node/frozen-nodes). From 160271b61351a803c57b9844d28601134e80336a Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:23:59 +0000 Subject: [PATCH 20/30] docs: The IBC module has been fully retired/deprecated: IBC wiring, keeper, ante decorator, begin-blocker, metrics, and CosmWasm IBC entry points are removed, and queries to retired IBC stores now return an 'ibc module is deprecated' error. (sei-protocol/sei-chain#4014) --- cosmos-sdk/index.mdx | 2 +- evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx | 2 ++ node/technical-reference.mdx | 12 +++++++----- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/cosmos-sdk/index.mdx b/cosmos-sdk/index.mdx index e514527..73e6367 100644 --- a/cosmos-sdk/index.mdx +++ b/cosmos-sdk/index.mdx @@ -16,7 +16,7 @@ In addition, [Proposal 115](https://seistream.app/proposals/115) disables CosmWa **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. -IBC messaging is now retired at the protocol level: any transaction containing a message whose type URL begins with `/ibc.` is rejected outright with an `ErrIBCDeprecated` error. The IBC ante decorator rejects such transactions before they enter the mempool, and the message service router returns the same error if one is routed, so IBC messages are no longer processed or executed. +IBC messaging is now retired at the protocol level: the IBC module is no longer wired into the application at all, so IBC message types (those whose type URL begins with `/ibc.`) are no longer registered. Such messages can no longer be routed or executed, and queries against the retired IBC stores return an `ibc module is deprecated` error. diff --git a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx index 41ce914..3e6d7e5 100644 --- a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx +++ b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx @@ -13,6 +13,8 @@ keywords: ['cosmwasm precompile', 'ethers.js', 'wasm execution', 'cross-chain co 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. + CosmWasm IBC support has been removed. Contracts can no longer open, connect, or close IBC channels or send, receive, acknowledge, or time out IBC packets. An IBC `SendPacket` message from a contract is rejected as unsupported, and the IBC channel and list-channels queries return `unsupported request: IBC` — only the contract's own `PortID` query remains. + For new smart contract development, use the EVM directly. See [Deploy a Smart Contract](/evm/evm-general). diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 687a05c..fcdd5b9 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -640,23 +640,25 @@ Node-local LCD and gRPC queries no longer cap pagination limits, offsets, or sto ## Retired IBC store queries -Starting with v6.7, the IBC core query APIs are removed from v6.7 nodes, including raw ABCI store queries against the retired IBC-related stores. Querying any of the following store paths now returns an `ibccoretypes.ErrIBCDeprecated` error instead of store data: +The IBC module is fully unwired from the node: there is no IBC keeper, no IBC `AppModule`, no IBC ante decorator, and no IBC begin-blocker. This includes raw ABCI store queries against the retired IBC-related stores. Querying any of the following store paths now returns a deprecation error instead of store data: - `/store/ibc/key` and `/store/ibc/subspace` - `/store/transfer/key` and `/store/transfer/subspace` - `/store/capability/key` and `/store/capability/subspace` -The `ibc`, `transfer`, and `capability` stores remain mounted for historical state access in freeze mode, but direct ABCI store queries against them are intercepted and rejected on v6.7 nodes. Queries against other stores (for example, `/store/bank/key`) are unaffected. +Each of these queries returns Codespace `ibc`, Code `103`, and Log `ibc module is deprecated`. -To serve pre-v6.7 IBC query history, run a [v6.6 freeze node](/node/frozen-nodes). +The `ibc`, `transfer`, and `capability` stores remain mounted for historical state access in freeze mode, but direct ABCI store queries against them are intercepted and rejected. Queries against other stores (for example, `/store/bank/key`) are unaffected. + +To serve pre-retirement IBC query history, run a [v6.6 freeze node](/node/frozen-nodes). ### Retired IBC messages -Along with the removal of IBC store queries, IBC messaging is retired on-chain. Any transaction that carries a message whose type URL begins with the `/ibc.` prefix is now rejected. The IBC ante decorator checks every transaction's messages and returns an `ErrIBCDeprecated` error as soon as it finds an IBC message, so these transactions are turned away at the ante handler (including during `CheckTx`, before they can enter the mempool). The `MsgServiceRouter` handler for IBC messages returns the same `ErrIBCDeprecated` error, so no IBC message is routed or executed on v6.7 nodes. +Along with the removal of IBC store queries, IBC messaging is retired on-chain. IBC message types are no longer registered with the application, so no message whose type URL begins with the `/ibc.` prefix can be constructed, routed, or executed. Because the IBC ante decorator has been removed entirely and the `MsgServiceRouter` has no IBC handlers, there is no longer a separate `ErrIBCDeprecated` rejection path — IBC messages simply cannot reach `CheckTx` or execution. -Previously, the IBC ante decorator only performed redundancy checks on packet messages (`RecvPacket`, `Acknowledgement`, `Timeout`, and `UpdateClient`) and rejected fully redundant relayer transactions with `ErrRedundantTx`. That redundancy logic is gone; all IBC messages are now rejected outright. +Earlier releases wired the IBC module and rejected IBC messages at runtime (for example, the ante decorator returned `ErrIBCDeprecated`, and before that it performed redundancy checks on packet messages such as `RecvPacket`, `Acknowledgement`, `Timeout`, and `UpdateClient`). That wiring is gone; IBC is no longer part of the application at all. EVM precompile query paths keep the legacy v6.6 pagination behavior — the `1000` limit, `10000` offset, and `10000`-entry scan limit still apply there — because precompiles run during transaction execution, where relaxing these caps would change gas consumption and break AppHash/LastResultsHash determinism. This only affects queries invoked inside EVM execution; client-facing LCD/gRPC queries use the relaxed semantics described above. The modules covered include `authz`, `distribution`, `feegrant`, `gov`, `staking`, and `bank`. From ac8527d147c1808430a9d99b0c9aac16fc326472 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:25:31 +0000 Subject: [PATCH 21/30] docs: Adds a new frozen-rpc-router binary/command that routes EVM JSON-RPC requests to live or frozen-height nodes, with new CLI flags and build targets, and introduces a seid start --freeze-height flag. (sei-protocol/sei-chain#3989) --- node/technical-reference.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index fcdd5b9..b30dbf8 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -102,6 +102,12 @@ git checkout # v6.6.3 or later make build-frozen-rpc-router ``` +For local testing, the repository also ships a Docker topology that runs a live chain alongside archival nodes frozen at different heights, with the router in front of them. These Makefile targets drive it: + +- `make docker-frozen-rpc-cluster-start`: Start the frozen-router Docker cluster (two live validators, two archival nodes frozen before preset heights, and `frozen-rpc-router` published on a host port). +- `make docker-frozen-rpc-cluster-stop`: Stop the cluster and remove its containers. +- `make frozen-rpc-router-integration-test`: Run the complete start-test-stop flow, bringing the cluster up, running the frozen-RPC-router integration tests, and tearing the cluster down afterward. + ```bash # Route between a live node and two frozen nodes. The router takes the default EVM # HTTP RPC port (8545), so the live node and the frozen node that share this host From 0c67cad6776f2751fe94ed079b51ff67a54e03d6 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:27:00 +0000 Subject: [PATCH 22/30] docs: The release build now produces statically-linked seid binaries for both linux/amd64 and linux/arm64, so Sei users can download a prebuilt arm64 binary in addition to amd64. (sei-protocol/sei-chain#4047) --- evm/installing-seid-cli.mdx | 17 +++++++++++------ node/index.mdx | 9 +++++---- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/evm/installing-seid-cli.mdx b/evm/installing-seid-cli.mdx index f30f135..d560651 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 a statically linked `seid` build with no runtime + dependencies for both `linux/amd64` and `linux/arm64`: ```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): + 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 @@ -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, and a statically-linked + `linux/arm64` (aarch64) binary is attached alongside the `linux/amd64` one. For + earlier versions, build from source. The binaries omit hardware Ledger support, + so if you sign with a Ledger device, build from source. On architectures other + than `linux/amd64` or `linux/arm64`, build from source. diff --git a/node/index.mdx b/node/index.mdx index 9c42cb4..ac7ef8d 100644 --- a/node/index.mdx +++ b/node/index.mdx @@ -137,10 +137,11 @@ 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. + Prebuilt binaries are attached from `v6.6.1` onward. Statically-linked builds are + now attached for both `linux/amd64` and `linux/arm64`; pick the asset matching your + architecture (`linux_x86_64` for amd64, `linux_aarch64` for arm64). For earlier + versions, build from source or use Docker. Prebuilt binaries do not include hardware + Ledger support. If you sign with a Ledger device, build from source or use Docker. From 6ecc46f44879461002aeb62e5ce5de5c26ef3592 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:28:05 +0000 Subject: [PATCH 23/30] docs: The wasmd precompile's execute_batch method has been disabled and now returns an error, removing the ability to batch-execute multiple CosmWasm contract calls via the EVM precompile. (sei-protocol/sei-chain#4074) --- evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx | 2 +- evm/precompiles/example-usage.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx index 3e6d7e5..be6c8da 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. Only calls to `execute()` and `query()` against pre-existing CosmWasm contracts still work. The `execute_batch()` function is **disabled** and reverts with `wasmd execute_batch is disabled` for all callers — batch execution of multiple CosmWasm contract calls through this precompile is no longer supported. Use a separate `execute()` call per message instead. 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. diff --git a/evm/precompiles/example-usage.mdx b/evm/precompiles/example-usage.mdx index a2929d6..2d462d8 100644 --- a/evm/precompiles/example-usage.mdx +++ b/evm/precompiles/example-usage.mdx @@ -13,7 +13,7 @@ Sei precompiles are special smart contracts deployed at fixed addresses. They ex | Precompile | Address | Description | | --- | --- | --- | | Bank | `0x0000000000000000000000000000000000001001` | Query the native SEI bank balance | -| CosmWasm | `0x0000000000000000000000000000000000001002` | Query or execute existing CosmWasm contracts. `instantiate()` reverts (Proposal 115). | +| CosmWasm | `0x0000000000000000000000000000000000001002` | Query or execute existing CosmWasm contracts. `instantiate()` reverts (Proposal 115), and `execute_batch()` is disabled and reverts with `wasmd execute_batch is disabled`. | | JSON | `0x0000000000000000000000000000000000001003` | Parse JSON data within contracts | | Address | `0x0000000000000000000000000000000000001004` | Convert and associate EVM and Sei addresses | | Staking | `0x0000000000000000000000000000000000001005` | Delegation and staking operations | From 9edb349a9276a6ecbd0bd7d170732ba7b179e939 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:29:38 +0000 Subject: [PATCH 24/30] docs: The v6.7 changelog introduces numerous developer-facing changes including removal of legacy sei_* and sei2_* JSON-RPC APIs, eth_getProof removal, origin-aware ABCI pagination caps with new config fields, EVM RPC admission/rate-limiting config, new precompile authorization features, a freeze mode for historical EVM RPC, and new CLI commands for address association. (sei-protocol/sei-chain#4113) --- evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx index be6c8da..d8b74e6 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()` and `query()` against pre-existing CosmWasm contracts still work. The `execute_batch()` function is **disabled** and reverts with `wasmd execute_batch is disabled` for all callers — batch execution of multiple CosmWasm contract calls through this precompile is no longer supported. Use a separate `execute()` call per message instead. 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. Only calls to `execute()` and `query()` against pre-existing CosmWasm contracts still work. The `execute_batch()` function is **disabled** and reverts with `wasmd execute_batch is disabled` for all callers — batch execution of multiple CosmWasm contract calls through this precompile is no longer supported. Use a separate `execute()` call per message instead. The batch-related code and examples on this page are retained for reference only; `execute_batch()` calls fail on-chain. 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. From f7aa8b1a3b5fe3d3b746c5c60993e9635d711953 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:32:47 +0000 Subject: [PATCH 25/30] docs: The seidb evm-logical-digest tool adds a --json flag for machine-readable output (narration redirected to stderr), extends --inspect-bucket to support the composite backend and the replay open mode, and documents SEI_LOG_OUTPUT=stderr for clean JSON reports. (sei-protocol/sei-chain#4255) --- node/technical-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index b30dbf8..0195e87 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -215,8 +215,8 @@ The command accepts these flags: - `--height`: The target version. FlatKV WAL-replays to it, and memIAVL resolves `snapshot-/evm` (`0` selects the `current` symlink). - `--memiavl-open-mode`: How the command reads memIAVL. `snapshot` (the default) scans the snapshot file at `--height`. It is the fastest mode, but it needs a snapshot at that height, or `--height 0`. `changelog` reads the nearest snapshot at or below `--height` and adds the changelog's EVM writes up to `--height`. `replay` opens the database, replays the changelog to `--height`, and walks the tree. It is about 10 times slower than `snapshot`. `changelog` and `replay` return the same rows. Use one of them when no snapshot exists at `--height`. - `--memiavl-normalization`: The memIAVL normalization mode. Use `semantic` or `independent` for the raw EVM key-value decoder, or `translator` for the current migration mapping. The default is `semantic`. -- `--json`: Print the digest or inspect report as one JSON object on stdout, and the progress messages on stderr. -- `--inspect-bucket`: Inspect one normalized bucket (`account`, `code`, `storage`, or `misc`), not the global digest. Inspect mode with `--memiavl-normalization translator`, or with `--details` on the `storage` bucket, requires `--memiavl-open-mode snapshot`. +- `--json`: Print the digest or inspect report as one JSON object on stdout, and the narration (start banner, scan progress, and text report) on stderr. In this mode the storage-layer logging is quieted to error level so it leaves stdout. One error-level log line can still reach stdout, so for unattended callers also set `SEI_LOG_OUTPUT=stderr` to move that line off stdout and keep the JSON report clean; the command prints a warning when `SEI_LOG_OUTPUT` is unset. The JSON digest report adds a `zero_census` object (with the `zero_accounts`, `zero_codehash_rows`, `live_accounts_with_zero_codehash_row`, `live_accounts_without_codehash_row`, `empty_code_values`, and `zero_storage_slots` counters) on the memIAVL paths that take a zero-value census, and a `marker_adjustments` list naming the FlatKV-only `MigrationStore` rows XORed back out of the misc bucket, which distinguishes a mid-migration reading from a completed one. The object is absent on backends that take no census, matching the omitted census block in the text report. +- `--inspect-bucket`: Inspect one normalized bucket (`account`, `code`, `storage`, or `misc`), not the global digest. It works with the `flatkv`, `memiavl`, and `composite` backends, and with both `snapshot` and `replay` open modes. With `--backend composite` you must set both `--flatkv-dir` and `--memiavl-dir`. Inspect mode with `--memiavl-normalization translator`, or with `--details` on the `storage` bucket, still requires `--memiavl-open-mode snapshot`. - `--inspect-plan` (inspect mode): A JSON file that lists several inspect reports to produce from one scan. It replaces the single-report inspect flags. - `--key-offset` (inspect mode): The byte offset into the physical key, applied before `--key-prefix` or sharding. - `--key-prefix` (inspect mode): A hex prefix, relative to `--key-offset`, that filters physical keys. From fd9138d1c7190b9c7c015ee0a48d59c56c1b2a4d Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:33:28 +0000 Subject: [PATCH 26/30] docs: A seidb CLI command gained JSON output support and new inspection capability, plus internal changelog/migration fixes. (sei-protocol/sei-chain#4294) --- node/technical-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 0195e87..27dedb4 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -216,7 +216,7 @@ The command accepts these flags: - `--memiavl-open-mode`: How the command reads memIAVL. `snapshot` (the default) scans the snapshot file at `--height`. It is the fastest mode, but it needs a snapshot at that height, or `--height 0`. `changelog` reads the nearest snapshot at or below `--height` and adds the changelog's EVM writes up to `--height`. `replay` opens the database, replays the changelog to `--height`, and walks the tree. It is about 10 times slower than `snapshot`. `changelog` and `replay` return the same rows. Use one of them when no snapshot exists at `--height`. - `--memiavl-normalization`: The memIAVL normalization mode. Use `semantic` or `independent` for the raw EVM key-value decoder, or `translator` for the current migration mapping. The default is `semantic`. - `--json`: Print the digest or inspect report as one JSON object on stdout, and the narration (start banner, scan progress, and text report) on stderr. In this mode the storage-layer logging is quieted to error level so it leaves stdout. One error-level log line can still reach stdout, so for unattended callers also set `SEI_LOG_OUTPUT=stderr` to move that line off stdout and keep the JSON report clean; the command prints a warning when `SEI_LOG_OUTPUT` is unset. The JSON digest report adds a `zero_census` object (with the `zero_accounts`, `zero_codehash_rows`, `live_accounts_with_zero_codehash_row`, `live_accounts_without_codehash_row`, `empty_code_values`, and `zero_storage_slots` counters) on the memIAVL paths that take a zero-value census, and a `marker_adjustments` list naming the FlatKV-only `MigrationStore` rows XORed back out of the misc bucket, which distinguishes a mid-migration reading from a completed one. The object is absent on backends that take no census, matching the omitted census block in the text report. -- `--inspect-bucket`: Inspect one normalized bucket (`account`, `code`, `storage`, or `misc`), not the global digest. It works with the `flatkv`, `memiavl`, and `composite` backends, and with both `snapshot` and `replay` open modes. With `--backend composite` you must set both `--flatkv-dir` and `--memiavl-dir`. Inspect mode with `--memiavl-normalization translator`, or with `--details` on the `storage` bucket, still requires `--memiavl-open-mode snapshot`. +- `--inspect-bucket`: Inspect one normalized bucket (`account`, `code`, `storage`, or `misc`), not the global digest. It works with the `flatkv`, `memiavl`, and `composite` backends, and with both `snapshot` and `replay` open modes. With `--backend composite` you must set both `--flatkv-dir` and `--memiavl-dir`. Inspect mode with `--memiavl-normalization translator`, or with `--details` on the `storage` bucket, still requires `--memiavl-open-mode snapshot`. Together with `--json`, inspect mode can examine a FlatKV migration that is still in flight: point it at a node mid-migration (for example with `--backend composite`) to inspect the buckets and migration state as they currently stand, rather than only a completed migration. - `--inspect-plan` (inspect mode): A JSON file that lists several inspect reports to produce from one scan. It replaces the single-report inspect flags. - `--key-offset` (inspect mode): The byte offset into the physical key, applied before `--key-prefix` or sharding. - `--key-prefix` (inspect mode): A hex prefix, relative to `--key-offset`, that filters physical keys. From a7e5ff6d4cef31a01cc76331da1528380f87bf5c Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:34:29 +0000 Subject: [PATCH 27/30] docs: Dynamic-gas precompiles now convert an executor's out-of-gas (gas-meter) panic into a reverted/failed EVM call frame with vm.ErrOutOfGas and zero remaining gas, instead of propagating the panic and failing the entire transaction at the Cosmos layer. (sei-protocol/sei-chain#4334) --- evm/evm-parity/gas-and-fees.mdx | 4 +++- evm/precompiles/p256-precompile.mdx | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/evm/evm-parity/gas-and-fees.mdx b/evm/evm-parity/gas-and-fees.mdx index ae89c51..ccf35d4 100644 --- a/evm/evm-parity/gas-and-fees.mdx +++ b/evm/evm-parity/gas-and-fees.mdx @@ -99,7 +99,9 @@ Sei precompiles charge gas based on the work that each call does: - Before a precompile decodes its arguments, it charges gas for the calldata. The charge grows with the calldata length and with the size of any `string` arguments. A call that cannot pay this charge reverts before the precompile runs. - The JSON precompile also charges 100 gas per byte of JSON input. - 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. +- 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 as out-of-gas. + +When a dynamic-gas precompile runs out of gas mid-execution, the out-of-gas condition fails only that call frame with `vm.ErrOutOfGas` and zero remaining gas, just like an ordinary EVM out-of-gas. The surrounding transaction completes as a normal failed EVM execution: it produces a failed receipt that charges exactly the gas used at the effective gas price, and an enclosing call frame can continue afterward. The out-of-gas no longer escapes the EVM to fail the whole transaction at the Cosmos layer with a zero-gas receipt. 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. diff --git a/evm/precompiles/p256-precompile.mdx b/evm/precompiles/p256-precompile.mdx index b39b8c1..fb890c9 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 as out-of-gas (`vm.ErrOutOfGas`) with zero remaining gas, consuming the gas supplied to the frame; only that call frame fails rather than the whole transaction. ## Real-world use cases From 655182f9d9fdf7c8caccea407b2c515528b21ee3 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:35:42 +0000 Subject: [PATCH 28/30] docs: Adds a 'pause-state-migration' hard fork handler that sets the state migration rate (NumKeysToMigratePerBlock) to zero at a target height, which node operators should be aware of during upgrades. (sei-protocol/sei-chain#4409) --- node/giga-storage-migration.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/node/giga-storage-migration.mdx b/node/giga-storage-migration.mdx index 06760e2..4206467 100644 --- a/node/giga-storage-migration.mdx +++ b/node/giga-storage-migration.mdx @@ -220,6 +220,25 @@ 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. + + +### Pausing the migration network-wide + +A `pause-state-migration` hard fork handler can halt the migration rate across +the network at a configured target height. When the handler runs, it sets +`NumKeysToMigratePerBlock` in the `migration` params subspace back to `0`, so no +further keys move per block from that height onward. The handler runs only on +the chain whose ID matches its target, and it takes effect at the target height +without a node restart. + +Pausing this way does not revert in-progress work: the in-flight write mode is +preserved. A node that has already switched from `memiavl_only` to +`migrate_evm` stays in `migrate_evm` after the pause; only the per-block +migration rate drops to zero. To resume, a `ParameterChangeProposal` can raise +`NumKeysToMigratePerBlock` above `0` again. Node operators should be aware of +this hard fork during upgrades, since it changes the effective migration rate at +the target height even though no `app.toml` change is required. + During the migration, the node reads and iterates over both backends. The migration deletes a key from memiavl when it copies the key to FlatKV. If both backends report a key, the node uses the memiavl value. The migration boundary From b25f110e1dafa7cbb345e572280c849b663a9473 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:36:56 +0000 Subject: [PATCH 29/30] docs: Adds a new `seidb kvrepair-export` CLI command for generating KV repair files from evm-logical-digest reports, a new embedded kvrepair hard-fork mechanism that applies reviewed key/value fixes at a target height, and new flags/guidance (`--key-offset`) for the evm-logical-digest inspect workflow. (sei-protocol/sei-chain#4410) --- node/giga-storage-migration.mdx | 81 +++++++++++++++++++++++++++++++++ node/technical-reference.mdx | 45 ++++++++++++++++++ 2 files changed, 126 insertions(+) diff --git a/node/giga-storage-migration.mdx b/node/giga-storage-migration.mdx index 4206467..71043a1 100644 --- a/node/giga-storage-migration.mdx +++ b/node/giga-storage-migration.mdx @@ -325,6 +325,87 @@ In the default `auto` write mode, the node does not use a FlatKV store that this command creates. The store has no migration metadata, so the node starts in `memiavl_only`. + + +## KV repair hard forks + +The FlatKV EVM migration can surface rare key/value divergences between a +memiavl reserve and a production FlatKV node. The `kvrepair` mechanism applies a +reviewed set of corrections to module stores as a hard fork, so every node +commits the same changeset at the same height. + +Each repair is a JSON file under `app/upgrades/kvrepair/repairs/` that is +compiled into the binary. At the start of a block, a repair runs only on the +chain whose ID matches its `chain_id` and only at its `target_repair_height`. +No `app.toml` change or restart is required: the repair ships inside the binary +and applies automatically on the matching chain and height. + +### Repair file fields + +| Field | Meaning | +| --- | --- | +| `name` | Unique repair name across all repair files. Becomes the hard fork handler name `kvrepair-`. | +| `chain_id` | The chain the repair runs on. | +| `target_repair_height` | The block whose start applies the repair. | +| `state_height` | The height whose committed state the `new` values come from. Must be below `target_repair_height`. | +| `source` | Free text for reviewers. It has no effect on execution. | +| `entries` | The list of key/value writes to apply. | + +Each entry names a `store` and a hex `key`, with or without a `0x` prefix: + +- `new` is the correct value. A `null` `new` deletes the key. +- `old` is the incorrect value the key holds before the repair. +- `old_absent: true` states that the key must not exist before the repair. An + entry may set `old` or `old_absent`, but not both. +- An entry that already holds its `new` value skips the `old` check, so a + correct node and a repaired node commit the same changeset. If an entry finds + neither `new` nor `old`, the node halts at `target_repair_height`. + +When `state_height` is not `target_repair_height - 1`, every entry must state an +`old` value, because a key can change between the two heights. + +### EVM absence semantics + +In the `evm` store, repairs compare values with absence semantics: an all-zero +storage slot, nonce, or code hash, and an empty code value, read as equal to an +absent key. Every other value, and every value in another store, compares +exactly, so an empty value (`""`) differs from an absent key. This affects how +an entry's `old` value and `old_absent` flag are matched, and whether a `new` +value is written or the key is deleted. + +### Generating a repair file + +Stop the chain at height `H`. For each bucket and key prefix the EVM logical +digest reports as different, list the keys on a memiavl reserve and on a +production node at `H`. Physical keys start with `evm/`, so `--key-offset 4` +makes `--key-prefix` apply to the EVM key. Run both sides with the same bucket, +`--key-offset`, `--key-prefix`, and `--list-limit 0`: + +```bash copy +seidb evm-logical-digest --backend memiavl --memiavl-open-mode replay \ + -d --height H --inspect-bucket storage \ + --key-offset 4 --key-prefix 03AB --list --list-limit 0 --json > reserve.json +seidb evm-logical-digest --backend composite --memiavl-open-mode replay \ + --flatkv-dir --memiavl-dir --height H \ + --inspect-bucket storage --key-offset 4 --key-prefix 03AB \ + --list --list-limit 0 --json > prod.json +seidb kvrepair-export --reserve reserve.json --prod prod.json \ + --chain-id --name -evm- --target-repair-height \ + -o app/upgrades/kvrepair/repairs/-evm-.json +``` + +The `seidb kvrepair-export` subcommand writes one entry per differing key, +setting the reserve value as `new` and the production value as `old`. It refuses +two reports that differ in height, bucket, offset, or prefix, a list that +`--list-limit` cut off, a reserve read with `--memiavl-normalization translator`, +and an account whose balance differs, because the `evm` store has no balance +key. It also checks that a node can load the file it writes. Do not edit the +values by hand. + +A repair name may be used only once, and no two files may repair the +same store key at the same height. A node validates every embedded repair at +startup and panics on an invalid repair file. + ## FAQ ### Where do the data files live after migrating? diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index 27dedb4..f19c8eb 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -226,6 +226,51 @@ The command accepts these flags: - `--details` (inspect list mode): Include backend-specific version metadata. - `--find-hash`: An optional 32-byte hex per-entry hash to search for. When two `bucket_digest` values differ by exactly one entry, their XOR is the hash of that entry. This flag prints every matching entry, so you can locate a single diverging row. + + + Physical keys in a FlatKV or memIAVL store begin with the module prefix `evm/`. To make `--key-prefix` apply to the EVM key itself, skip past that prefix with `--key-offset 4`. For example, `--inspect-bucket storage --key-offset 4 --key-prefix 03 --shard-next-bytes 2` filters storage rows by the EVM key byte `03`. + + +```bash +# List every storage row under a key prefix at one height, from a memiavl +# reserve and from a production node. Use the same bucket, --key-offset, +# --key-prefix, and --list-limit 0 on both runs. Physical keys start with +# "evm/", so --key-offset 4 makes --key-prefix apply to the EVM key. +seidb evm-logical-digest --backend memiavl --memiavl-open-mode replay \ + -d --height H --inspect-bucket storage \ + --key-offset 4 --key-prefix 03AB --list --list-limit 0 --json > reserve.json +seidb evm-logical-digest --backend composite --memiavl-open-mode replay \ + --flatkv-dir --memiavl-dir --height H \ + --inspect-bucket storage --key-offset 4 --key-prefix 03AB \ + --list --list-limit 0 --json > prod.json +``` + +#### Generating KV repair files + +The `kvrepair-export` subcommand writes a KV repair file from two `evm-logical-digest` inspect list reports taken at the same height: one from a memIAVL reserve and one from a production node. Each entry it produces sets a key to the reserve value and records the production value as the key's old value, so the repair makes production match the reserve for every key the two reports list. A repair file is a reviewed set of key/value fixes that the node applies, as an embedded hard-fork handler, at the start of one target block on one chain. + +First, stop the chain at height `H` and produce a reserve report and a production report for each bucket and key prefix the digest flags as different, as shown above. Then export the repair file: + +```bash +seidb kvrepair-export --reserve reserve.json --prod prod.json \ + --chain-id pacific-1 --name pacific-1-evm- --target-repair-height \ + -o app/upgrades/kvrepair/repairs/pacific-1-evm-.json +``` + +The command accepts these flags: + +- `--reserve`: An inspect list report (`--list --json`) from a memIAVL reserve. Required. +- `--prod`: An inspect list report (`--list --json`) from a production node, taken at the same height, bucket, offset, and prefix. Required. +- `--chain-id`: The chain ID the repair runs on. Required. +- `--name`: The repair name, which must be unique across the repair files. Required. +- `--target-repair-height`: The height whose block start applies the repair. It must be above the report height. Required. +- `--source`: Free text for reviewers; it has no effect on execution. Defaults to a description of the two report sources. +- `--output` (`-o`): The output file. The command writes to stdout when this is empty. + +`kvrepair-export` refuses two reports that differ in height, bucket, offset, or prefix, a reserve report that is not a semantic memIAVL read (a `translator`-normalized report shares the migration mapping and is rejected), a list that `--list-limit` cut off, and an account whose balance differs, because the EVM store has no balance key. Before it writes, it checks that a node would parse and validate the resulting file. Do not edit the exported values by hand. + +Each repair file names one chain (`chain_id`), the block whose start applies the repair (`target_repair_height`), the committed height the values come from (`state_height`, which must be below `target_repair_height`), an optional free-text `source`, and the `entries` to apply. Each entry names a `store` and `key`, the correct `new` value (a `null` new deletes the key), and the incorrect value the key holds before the repair as `old`, or `"old_absent": true` when the key must not exist beforehand. In the `evm` store, an all-zero storage slot, nonce, or code hash and an empty code value compare as equal to an absent key; every other value, and every value in another store, compares exactly. On a matching chain and height, the handler applies the file at block start, writing or deleting each entry and reading it back; an entry that holds neither its new nor its old value halts the node. + #### Dumping FlatKV state and verifying its lattice hash `dump-flatkv` writes every physical key-value pair of a FlatKV store to one file per bucket. The format matches `dump-iavl`, so the same diff tools work on both. The command can also compute the lattice hash (LtHash) of each bucket and of the whole store. Then it compares the total with the committed value in the snapshot metadata. From 31c251500b84e905bec6cb735522438e6f1c2b65 Mon Sep 17 00:00:00 2001 From: "seidroid[bot]" <257742136+seidroid[bot]@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:42:27 +0000 Subject: [PATCH 30/30] docs: The seidb evm-logical-digest command gains a new `changelog` memiavl open mode and a new `--inspect-plan` flag for taking multiple inspect reports from one scan. (sei-protocol/sei-chain#4439) --- node/giga-storage-migration.mdx | 9 +++++++-- node/technical-reference.mdx | 4 ++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/node/giga-storage-migration.mdx b/node/giga-storage-migration.mdx index 71043a1..9c2b887 100644 --- a/node/giga-storage-migration.mdx +++ b/node/giga-storage-migration.mdx @@ -381,11 +381,16 @@ production node at `H`. Physical keys start with `evm/`, so `--key-offset 4` makes `--key-prefix` apply to the EVM key. Run both sides with the same bucket, `--key-offset`, `--key-prefix`, and `--list-limit 0`: +The `changelog` open mode scans the snapshot at or below `--height` merged +with the EVM changelog writes above it; it reads the same rows as `replay` +more quickly. The `replay` open mode is still supported and reads the same +rows, more slowly. + ```bash copy -seidb evm-logical-digest --backend memiavl --memiavl-open-mode replay \ +seidb evm-logical-digest --backend memiavl --memiavl-open-mode changelog \ -d --height H --inspect-bucket storage \ --key-offset 4 --key-prefix 03AB --list --list-limit 0 --json > reserve.json -seidb evm-logical-digest --backend composite --memiavl-open-mode replay \ +seidb evm-logical-digest --backend composite --memiavl-open-mode changelog \ --flatkv-dir --memiavl-dir --height H \ --inspect-bucket storage --key-offset 4 --key-prefix 03AB \ --list --list-limit 0 --json > prod.json diff --git a/node/technical-reference.mdx b/node/technical-reference.mdx index f19c8eb..472246e 100644 --- a/node/technical-reference.mdx +++ b/node/technical-reference.mdx @@ -216,8 +216,8 @@ The command accepts these flags: - `--memiavl-open-mode`: How the command reads memIAVL. `snapshot` (the default) scans the snapshot file at `--height`. It is the fastest mode, but it needs a snapshot at that height, or `--height 0`. `changelog` reads the nearest snapshot at or below `--height` and adds the changelog's EVM writes up to `--height`. `replay` opens the database, replays the changelog to `--height`, and walks the tree. It is about 10 times slower than `snapshot`. `changelog` and `replay` return the same rows. Use one of them when no snapshot exists at `--height`. - `--memiavl-normalization`: The memIAVL normalization mode. Use `semantic` or `independent` for the raw EVM key-value decoder, or `translator` for the current migration mapping. The default is `semantic`. - `--json`: Print the digest or inspect report as one JSON object on stdout, and the narration (start banner, scan progress, and text report) on stderr. In this mode the storage-layer logging is quieted to error level so it leaves stdout. One error-level log line can still reach stdout, so for unattended callers also set `SEI_LOG_OUTPUT=stderr` to move that line off stdout and keep the JSON report clean; the command prints a warning when `SEI_LOG_OUTPUT` is unset. The JSON digest report adds a `zero_census` object (with the `zero_accounts`, `zero_codehash_rows`, `live_accounts_with_zero_codehash_row`, `live_accounts_without_codehash_row`, `empty_code_values`, and `zero_storage_slots` counters) on the memIAVL paths that take a zero-value census, and a `marker_adjustments` list naming the FlatKV-only `MigrationStore` rows XORed back out of the misc bucket, which distinguishes a mid-migration reading from a completed one. The object is absent on backends that take no census, matching the omitted census block in the text report. -- `--inspect-bucket`: Inspect one normalized bucket (`account`, `code`, `storage`, or `misc`), not the global digest. It works with the `flatkv`, `memiavl`, and `composite` backends, and with both `snapshot` and `replay` open modes. With `--backend composite` you must set both `--flatkv-dir` and `--memiavl-dir`. Inspect mode with `--memiavl-normalization translator`, or with `--details` on the `storage` bucket, still requires `--memiavl-open-mode snapshot`. Together with `--json`, inspect mode can examine a FlatKV migration that is still in flight: point it at a node mid-migration (for example with `--backend composite`) to inspect the buckets and migration state as they currently stand, rather than only a completed migration. -- `--inspect-plan` (inspect mode): A JSON file that lists several inspect reports to produce from one scan. It replaces the single-report inspect flags. +- `--inspect-bucket`: Inspect one normalized bucket (`account`, `code`, `storage`, or `misc`), not the global digest. It works with the `flatkv`, `memiavl`, and `composite` backends, and with the `snapshot`, `replay`, and `changelog` open modes. With `--backend composite` you must set both `--flatkv-dir` and `--memiavl-dir`. Inspect mode with `--memiavl-normalization translator`, or with `--details` on the `storage` bucket, still requires `--memiavl-open-mode snapshot`. Together with `--json`, inspect mode can examine a FlatKV migration that is still in flight: point it at a node mid-migration (for example with `--backend composite`) to inspect the buckets and migration state as they currently stand, rather than only a completed migration. +- `--inspect-plan` (inspect mode): A JSON file that holds a list of inspect reports to take from one scan, so you can produce many reports without rescanning. Each item is an object with `inspect_bucket`, `key_offset`, `key_prefix` (hex), `shard_next_bytes`, `list`, `list_limit`, and `out` (the file its JSON report is written to). An item without `list_limit` lists every match. For example, `[{"inspect_bucket":"storage","key_offset":4,"list":true,"out":"storage.json"},{"inspect_bucket":"account","key_offset":4,"list":true,"out":"account.json"}]`. This flag replaces the single-report inspect flags (`--inspect-bucket`, `--key-offset`, `--key-prefix`, `--shard-next-bytes`, `--list`, `--list-limit`, and `--details`) and cannot be combined with them. - `--key-offset` (inspect mode): The byte offset into the physical key, applied before `--key-prefix` or sharding. - `--key-prefix` (inspect mode): A hex prefix, relative to `--key-offset`, that filters physical keys. - `--shard-next-bytes` (inspect mode): Group matching keys by this many bytes after `--key-prefix`.