EVM Migration Helper Scripts Guide

Audience: Terminal users running lumerad: regular account holders, validator operators, supernode operators, and multisig coordinators.

Start Here

Use the script that matches the account you are migrating:

Situation	Script	What it does
Regular single-key account	`scripts/migrate-account.sh`	Migrates a legacy coin-type 118 `secp256k1` account to a coin-type 60 `eth_secp256k1` account.
Single-key validator operator	`scripts/migrate-validator.sh`	Migrates the validator operator account and re-keys validator-related state. The validator node must be stopped before broadcast.
Multisig account or multisig validator operator	`scripts/migrate-multisig.sh`	Runs a 4-step coordinator/co-signer ceremony: `generate`, `sign`, `combine`, `submit`.

Most users should do this first:

./scripts/migrate-account.sh <legacy-key> <new-evm-key> --dry-run

If the dry-run succeeds, remove --dry-run and run the same command to broadcast.

Important rules:

The legacy key is the old Lumera key: coin type 118, secp256k1.
The new key is the EVM-compatible key: coin type 60, eth_secp256k1.
The keys may use the same mnemonic or different mnemonics. There is no mnemonic relationship requirement. The destination key must use coin type 60 and key type eth_secp256k1.
The destination address must be fresh. It must not already exist on-chain, must not have bank balance, and must not appear in any migration record.
Run --dry-run first. It performs the same safety checks and stops before broadcast.
Do not use migrate-account.sh for validators. Use migrate-validator.sh.
Do not use the single-key scripts for multisig. They will detect multisig accounts and point you to migrate-multisig.sh.

During pre-flight, the scripts now print the important successful checks explicitly:

INFO  check OK: no migration record found for legacy address lumera1...
INFO  check OK: destination address lumera1... has no migration record as a legacy address
INFO  check OK: no migration record found by new address lumera1...
INFO  check OK: destination address lumera1... does not exist on-chain

If any of these checks fails, stop and read the error. Reusing an already-used destination address is unsafe and the chain will reject it.

The scripts also announce every stage before doing work. Single-key account and validator runs use seven numbered stages. The multisig ceremony labels each generate, sign, combine, and submit stage separately, explains whether a step can broadcast, warns before keyring passphrase prompts or potentially slow gas simulation, and ends with the exact next action. A passphrase is never echoed while typing.