diff --git a/docs/evm-integration/architecture/rollout.md b/docs/evm-integration/architecture/rollout.md index c757fbb0..8dc2d714 100644 --- a/docs/evm-integration/architecture/rollout.md +++ b/docs/evm-integration/architecture/rollout.md @@ -106,8 +106,7 @@ Before tagging the `v1.20.0` EVM release, the release owner must fill this table The current code seeds most of these from `config/evm.go`, `app/evm/genesis.go`, and `app/upgrades/v1_20_0/upgrade.go`. That makes them easy to overlook: they may not require a governance parameter proposal, but they still become live network behavior at upgrade height. #### Parameters That Actually Require a Decision - -Most of the detailed tables in the following subsections are **confirm-and-verify only**: their values are hardcoded in `config/evm.go` or seeded deterministically by the `v1_20_0` upgrade handler, so they cannot drift unless the code changes. The EVM chain ID (`76857769`), gas denom (`ulume`), extended denom (`alume`), EVM coin info, the fee-market constants, `block.max_gas`, the ERC20 toggles, and the precompile set all fall into this group — for mainnet they only need a final on-chain check against the values below, not a fresh decision. +Most of the detailed tables in the following subsections are **confirm-and-verify only**: their values are hardcoded in `config/evm.go` or seeded deterministically by the `v1_20_0` upgrade handler, so they cannot drift unless the code changes. The EVM chain ID (`76857769`), gas denom (`ulume`), extended denom (`alume`), EVM coin info, the fee-market constants, the ERC20 toggles, and the precompile set all fall into this group — for mainnet they only need a final on-chain check against the values below, not a fresh decision. (`block.max_gas` is the exception: it is **not** touched by the in-place upgrade — see the note in the Fee Market and Block Capacity table below.) The short list that genuinely needs a value chosen before tagging is the `x/evmigration` policy. The recommendations below were tuned against the live `lumera-mainnet-1` chain (height `5,462,371`, queried `2026-06-10`) using `scripts/chain-helper.sh`: **160,021** accounts, **50** bonded validators (cap 50) out of **83** total (9 jailed), a worst-case validator **migration-object count of 1,632** (the largest validator's 1,593 delegations + 29 unbonding delegations + redelegations — exactly what the cap bounds), a 21-day unbonding period, and a 7-day governance voting period. Re-run `scripts/chain-helper.sh max-validator-delegations` and `scripts/chain-helper.sh stats` close to tag time, since these counts grow with the chain. @@ -124,7 +123,7 @@ The short list that genuinely needs a value chosen before tagging is the `x/evmi | Parameter / decision | Current code default | Required decision before tag | Why it matters | Verification | | --- | --- | --- | --- | --- | | Cosmos chain ID | network-specific, e.g. `lumera-mainnet-1` | confirm the target network chain ID in release notes, scripts, Portal config, wallets, explorers, and migration proof payload docs | migration proofs include the Cosmos chain ID; a mismatch makes valid-looking proofs fail | run the RC against the target network config and record `status.node_info.network` | -| EVM chain ID | `76857769` | confirm this is final for mainnet and is not reused by another EVM network | wallets, replay protection, JSON-RPC, explorers, and migration proof payloads depend on it | `eth_chainId` must return `0x494b329`; migration proof payloads must include `76857769` | +| EVM chain ID | `76857769` | confirm this is final for mainnet and is not reused by another EVM network | wallets, replay protection, JSON-RPC, explorers, and migration proof payloads depend on it | `eth_chainId` must return `0x494c1a9`; migration proof payloads must include `76857769` | | EVM native denom / gas fee denom | `ulume` | confirm the gas token denom stays `ulume` | a wrong denom breaks EVM fees, bank metadata, fee checking, and user balances | `lumerad q evm params` shows `evm_denom=ulume`; bank metadata contains `ulume` | | EVM extended denom | `alume` | confirm the 18-decimal internal denom stays `alume` | precisebank and EVM 18-decimal accounting depend on this mapping | `lumerad q evm params` shows `extended_denom_options.extended_denom=alume`; bank metadata contains `alume` | | EVM coin info initialization | seeded by upgrade handler after skipping upstream EVM `InitGenesis` | confirm the upgrade handler writes Lumera coin info, not upstream `aatom` defaults | stale upstream coin info can make the chain start with wrong EVM accounting even if params later look correct | first post-upgrade smoke test must query VM params and execute a funded EVM transfer using `ulume` | @@ -138,7 +137,7 @@ The short list that genuinely needs a value chosen before tagging is the `x/evmi | `feemarket.base_fee` | `0.0025` `ulume` per gas, equivalent to `2.5 gwei` in 18-decimal EVM units | confirm launch base fee is acceptable for mainnet UX and spam resistance | too low invites spam; too high breaks ordinary wallet and contract tests | record base fee from `lumerad q feemarket params` and `eth_gasPrice` after upgrade | | `feemarket.min_gas_price` | `0.0005` `ulume` per gas, equivalent to `0.5 gwei` | confirm the floor is acceptable during low traffic | prevents base fee decay to zero; too high can make quiet-chain transactions unexpectedly expensive | drive low-traffic blocks on RC/devnet and confirm base fee floors at the intended value | | `feemarket.base_fee_change_denominator` | `16` | confirm the responsiveness target | lower values make base fee more volatile; higher values react more slowly to congestion | run the mixed-workload load test and record base-fee movement over sustained congestion | -| Consensus `block.max_gas` | `25,000,000` | confirm this is the intended first EVM block gas limit | finite max gas is required for meaningful EIP-1559 target-gas behavior and migration capacity planning | query consensus params after upgrade and compare to `25,000,000` | +| Consensus `block.max_gas` | `25,000,000` for **freshly initialized** genesis only (`ChainDefaultConsensusMaxGas` in `config/evm.go`, applied by `lumerad init`/`testnet`). The **in-place `v1.20.0` upgrade does not change it** — `EnsurePresent` only seeds consensus params when they are missing, otherwise preserving the chain's existing value. On live `lumera-mainnet-1` (and the running EVM devnet) that value is `-1` (unlimited). | decide whether mainnet should adopt a finite limit; if so it requires a separate governance `MsgUpdateParams` (consensus params), since the upgrade will **not** set `25,000,000` on an existing chain | a finite max gas gives EIP-1559 a gas target to adjust against; `-1` leaves base-fee adjustment effectively without a target | query consensus params after upgrade: expect the pre-upgrade value (`-1` on current mainnet/devnet), **not** `25,000,000`, unless changed by a separate proposal | | Validator local minimum gas prices | operator config, not chain state | publish the recommended `minimum-gas-prices` for `ulume` and ensure it does not conflict with feemarket expectations | inconsistent validator floors can cause confusing CheckTx behavior or local rejection | include the exact value in validator release notes and test node restart with the generated `app.toml` | #### ERC20, IBC, and Precompile Policy diff --git a/docs/evm-integration/user-guides/main.md b/docs/evm-integration/user-guides/main.md index 0276d859..4265a57c 100644 --- a/docs/evm-integration/user-guides/main.md +++ b/docs/evm-integration/user-guides/main.md @@ -29,7 +29,7 @@ Reference for the bundled `scripts/migrate-account.sh`, `scripts/migrate-validat ### [validator-migration.md](validator-migration.md) — Validator Operator Migration -The validator-specific procedure: maintenance window planning against `downtime_jail_duration` (1 hour on mainnet), the `max_validator_delegations` cap (default 2000), the `unjail` recovery flow if pre-flight reports the validator is jailed or unbonded, and the consensus-key safety guarantee (`priv_validator_key.json` is **not** affected — only the operator key changes from `secp256k1` to `eth_secp256k1`). Includes the multisig validator operator path. +The validator-specific procedure: maintenance window planning against `downtime_jail_duration` (1 hour on mainnet), the `max_validator_delegations` cap (default 2500), the `unjail` recovery flow if pre-flight reports the validator is jailed or unbonded, and the consensus-key safety guarantee (`priv_validator_key.json` is **not** affected — only the operator key changes from `secp256k1` to `eth_secp256k1`). Includes the multisig validator operator path. ### [supernode-migration.md](supernode-migration.md) — Supernode Operator Migration diff --git a/docs/evm-integration/user-guides/supernode-migration.md b/docs/evm-integration/user-guides/supernode-migration.md index 6d0e6d86..9fc422e6 100644 --- a/docs/evm-integration/user-guides/supernode-migration.md +++ b/docs/evm-integration/user-guides/supernode-migration.md @@ -22,8 +22,8 @@ Migration is idempotent end-to-end: if anything fails mid-flight, restart the da Both paths land in the same final state (new EVM key registered as supernode, legacy key deleted, `config.yml` updated). The operator steps are identical — what differs is whether the daemon initiates the on-chain migration or just finalizes one you already submitted. -- **Path A — Supernode daemon migrates for you (recommended default).** You recover a new EVM key into the supernode keyring, add`evm_key_name` to`config.yml`, and restart. The daemon detects the legacy key, dual-signs with both keys, and broadcasts`MsgClaimLegacyAccount` itself. This is the flow the rest of this guide documents in steps 1–4. -- **Path B — Migrate via Keplr + Portal first, then let the supernode finalize.** You use the Portal's standard[end-user migration](migration.md#method-1-portal--keplr-recommended) (browser + Keplr) to submit the migration transaction yourself. Then on the supernode host, you recover the same EVM key into the supernode's keyring, update`config.yml`, and restart. On startup the daemon sees the on-chain migration record, matches it against your configured`evm_key_name`, skips the broadcast, and performs only local cleanup. +- **Path A — Supernode daemon migrates for you (recommended default).** You recover a new EVM key into the supernode keyring, add `evm_key_name` to `config.yml`, and restart. The daemon detects the legacy key, dual-signs with both keys, and broadcasts `MsgClaimLegacyAccount` itself. This is the flow the rest of this guide documents in steps 1–4. +- **Path B — Migrate via Keplr + Portal first, then let the supernode finalize.** You use the Portal's standard [end-user migration](migration.md#method-1-portal--keplr-recommended) (browser + Keplr) to submit the migration transaction yourself. Then on the supernode host, you recover the same EVM key into the supernode's keyring, update `config.yml`, and restart. On startup the daemon sees the on-chain migration record, matches it against your configured `evm_key_name`, skips the broadcast, and performs only local cleanup. Path B is useful when you want to use Keplr's UX to see each step (the Portal shows balances, delegations, and a pre-migration checklist), when you need to migrate the account's balance urgently for non-supernode reasons, or when your node ops team and your wallet custody team are different people. @@ -46,9 +46,9 @@ If you chose Path B, the steps below are the same but in Step 3 the logs will sh Before starting: -- Lumera chain is**EVM-enabled**. The supernode daemon verifies this at boot via`x/upgrade.ModuleVersions(evm)`. If the chain hasn't upgraded yet the daemon fatals with`connected Lumera chain does not have EVM support` — wait for the chain upgrade. -- You hold the**mnemonic (seed phrase)** for the legacy supernode key. -- You have access to the host running the supernode daemon and can edit`config.yml`. +- Lumera chain is **EVM-enabled**. The supernode daemon verifies this at boot via `x/upgrade.ModuleVersions(evm)`. If the chain hasn't upgraded yet the daemon fatals with `connected Lumera chain does not have EVM support` — wait for the chain upgrade. +- You hold the **mnemonic (seed phrase)** for the legacy supernode key. +- You have access to the host running the supernode daemon and can edit `config.yml`. --- @@ -104,10 +104,10 @@ INFO EVM migration complete — legacy key removed, config updated On success, the daemon has: -- Broadcast`MsgClaimLegacyAccount` (or`MsgMigrateValidator` if you're also a validator operator) with both signatures embedded. +- Broadcast `MsgClaimLegacyAccount` (or `MsgMigrateValidator` if you're also a validator operator) with both signatures embedded. - Waited for block inclusion. - Deleted the old legacy key from the keyring. -- Rewritten`config.yml`:`key_name: supernode-evm`,`identity: lumera1...newEVMaddr`,`evm_key_name` removed. +- Rewritten `config.yml`: `key_name: supernode-evm`, `identity: lumera1...newEVMaddr`, `evm_key_name` removed. From here on, the supernode runs on the EVM key with no further intervention. @@ -262,7 +262,7 @@ The chain hasn't run the EVM upgrade yet. This supernode binary is post-EVM-only Someone completed migration with a different EVM key than the one now in your `evm_key_name` config. Either: - Use the EVM key that actually signed the original migration (re-recover it with the mnemonic that was used), or -- Investigate whether the on-chain`new_address` is correct — it's the authoritative record. +- Investigate whether the on-chain `new_address` is correct — it's the authoritative record. --- @@ -506,6 +506,6 @@ Regenerate `proof.json` with the correct `--chain-id`, have the affected signer - [migration.md](migration.md) — chain-level end-user migration guide (Portal + Keplr, shell scripts, raw CLI) - [migration-scripts.md](migration-scripts.md) — reference for the bundled `migrate-account.sh` / `migrate-validator.sh` shell helpers (flags, exit codes, troubleshooting) -- [validator-migration.md](validator-migration.md) — validator operator migration guide (maintenance window,`max_validator_delegations` check, consensus key handling) -- [legacy-migration.md](../evmigration/legacy-migration.md) —`x/evmigration` module architecture, proto shapes, keeper logic, and the full reference for the offline proof flow -- [node-evm-config-guide.md](node-evm-config-guide.md) — post-upgrade`app.toml` / RPC configuration for full nodes and validators +- [validator-migration.md](validator-migration.md) — validator operator migration guide (maintenance window, `max_validator_delegations` check, consensus key handling) +- [legacy-migration.md](../evmigration/legacy-migration.md) — `x/evmigration` module architecture, proto shapes, keeper logic, and the full reference for the offline proof flow +- [node-evm-config-guide.md](node-evm-config-guide.md) — post-upgrade `app.toml` / RPC configuration for full nodes and validators diff --git a/docs/evm-integration/user-guides/tune-guide.md b/docs/evm-integration/user-guides/tune-guide.md index a66627a2..7b827770 100644 --- a/docs/evm-integration/user-guides/tune-guide.md +++ b/docs/evm-integration/user-guides/tune-guide.md @@ -491,12 +491,12 @@ Priority levels: **CRITICAL** = must review before mainnet, **HIGH** = should re | **CRITICAL** | `min_gas_price` | 0.0005 ulume/gas | Ensure non-zero cost at launch price | | **CRITICAL** | `allow-unprotected-txs` | `false` | Verify remains `false` in all configs | | **CRITICAL** | `migration_end_time` | `0` (none) | **Set a mainnet deadline** | -| **CRITICAL** | `minimum_stake` (supernode) | TBD | Price-sensitive — review at launch price | +| **CRITICAL** | `minimum_stake` (supernode) | `0 ulume` (code default) | Price-sensitive — review at launch price | | **HIGH** | `base_fee_change_denominator` | 16 | Decide: stability (16) vs responsiveness (8) | | **HIGH** | `consensus_max_gas` | 25,000,000 | Confirm validator hardware supports it | | **HIGH** | ERC20 registration policy | configurable | **Set to "allowlist" for mainnet** | -| **HIGH** | `base_action_fee` / `fee_per_kbyte` | TBD | Economic modeling needed | -| **HIGH** | `supernode_fee_share` | TBD | Incentive alignment review | +| **HIGH** | `base_action_fee` / `fee_per_kbyte` | `0.01 LUME` / `0.00001 LUME/kB` (code defaults) | Economic modeling needed | +| **HIGH** | `supernode_fee_share` | `1.0` (100%, code default) | Incentive alignment review | | **HIGH** | Rate limiter | `disabled` | **Enable on public RPC nodes** | | **MEDIUM** | `gas-cap` (JSON-RPC) | 25,000,000 | Lower to 10M for public nodes | | **MEDIUM** | `logs-cap` / `block-range-cap` | 10,000 | Lower to 2,000 for public nodes |