You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/evm-migration.md
+85-51Lines changed: 85 additions & 51 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,8 @@ delegations, supernode registration, and optionally validator state — to a new
14
14
address derived from the same mnemonic under the EVM HD path.
15
15
16
16
The migration is:
17
-
-**One-time**: runs automatically at supernode startup when a legacy key is detected
17
+
18
+
-**One-time**: runs automatically at superno0de startup when a legacy key is detected
18
19
-**Rerunnable**: safe to retry if interrupted at any point
19
20
-**Self-authenticating**: uses dual signatures (legacy + new key) embedded in the
20
21
message, so no Cosmos-level tx signing is needed
@@ -24,57 +25,59 @@ The migration is:
24
25
### Prerequisites
25
26
26
27
1. Your supernode binary must be the EVM-compatible version.
27
-
2. The connected Lumera chain must have the`evm` module active.
28
-
3. You need the**mnemonic** used to create your original supernode key.
28
+
2. The connected Lumera chain must have the`evm` module active.
29
+
3. You need the**mnemonic** used to create your original supernode key.
29
30
30
31
### Migration Steps
31
32
32
33
1.**Derive your new EVM key** from the same mnemonic:
34
+
33
35
```bash
34
36
supernode keys recover --name evm-key --mnemonic "your twelve or twenty four words ..."
35
37
```
38
+
36
39
This creates an `eth_secp256k1` key under the name `evm-key` using HD path
37
40
`m/44'/60'/0'/0/0`. The resulting address will be different from your legacy
38
41
address — this is expected.
39
-
40
42
2.**Add `evm_key_name` to your config.yaml** under the `supernode` section:
43
+
41
44
```yaml
42
45
supernode:
43
46
key_name: mykey # your existing legacy key name
44
47
evm_key_name: evm-key # the name you used in step 1
45
48
identity: lumera1... # your current legacy address
46
49
```
47
-
48
50
3. **Restart the supernode**. On startup it will:
49
-
- Detect the legacy `secp256k1` key under `key_name`
50
-
- Validate that `evm_key_name` points to a valid `eth_secp256k1` key
51
+
52
+
- Detect the legacy`secp256k1` key under`key_name`
53
+
- Validate that`evm_key_name` points to a valid`eth_secp256k1` key
51
54
- Query the chain for an existing migration record (handles reruns)
52
-
- Run a pre-flight`MigrationEstimate` to check if the migration would succeed
55
+
- Run a pre-flight`MigrationEstimate` to check if the migration would succeed
53
56
- Sign the migration payload with both keys
54
-
- Broadcast`MsgClaimLegacyAccount` (or`MsgMigrateValidator` for validators)
57
+
- Broadcast`MsgClaimLegacyAccount` (or`MsgMigrateValidator` for validators)
55
58
- Wait for block confirmation (DeliverTx)
56
59
- Delete the legacy key from the keyring
57
-
- Update `config.yaml`: `key_name`-> `evm-key`, `identity` -> new address,
58
-
`evm_key_name`cleared
59
-
60
+
- Update`config.yaml`:`key_name` ->`evm-key`,`identity` -> new address,`evm_key_name` cleared
60
61
4. **After migration completes**, your config will look like:
62
+
61
63
```yaml
62
64
supernode:
63
65
key_name: evm-key
64
66
identity: lumera1<new-evm-address>
65
67
```
68
+
66
69
The `evm_key_name` field is automatically removed. No further action is needed.
67
70
68
71
### Troubleshooting
69
72
70
-
| Error | Cause | Fix |
71
-
| ----- | ----- | --- |
72
-
| `no evm_key_name configured` | Legacy key detected but config missing `evm_key_name` | Add `evm_key_name` to config and restart |
73
-
| `not an eth_secp256k1 key` | `evm_key_name` points to a secp256k1 key (wrong derivation) | Re-derive using `supernode keys recover` (uses coin type 60) |
74
-
| `new address mismatch` | On-chain migration record has a different destination address than your local EVM key | Your `evm_key_name` doesn't match the key originally used for migration; fix the config |
75
-
| `migration estimate indicates migration would fail` | Chain rejected the pre-flight check | Check `rejection_reason` in logs; migration may be disabled or account may not exist |
76
-
| `migration tx was not confirmed` | Tx was not included in a block within 60s | Restart to retry; the check is idempotent |
77
-
| `failed to save updated config` | Config file write error after successful migration | Manually update config as instructed in the error message |
| `no evm_key_name configured` | Legacy key detected but config missing `evm_key_name` | Add `evm_key_name` to config and restart |
76
+
| `not an eth_secp256k1 key` | `evm_key_name` points to a secp256k1 key (wrong derivation) | Re-derive using `supernode keys recover` (uses coin type 60) |
77
+
| `new address mismatch` | On-chain migration record has a different destination address than your local EVM key | Your `evm_key_name` doesn't match the key originally used for migration; fix the config |
78
+
| `migration estimate indicates migration would fail` | Chain rejected the pre-flight check | Check `rejection_reason` in logs; migration may be disabled or account may not exist |
79
+
| `migration tx was not confirmed` | Tx was not included in a block within 60s | Restart to retry; the check is idempotent |
80
+
| `failed to save updated config` | Config file write error after successful migration | Manually update config as instructed in the error message |
78
81
79
82
## Chain-Side Reference
80
83
@@ -106,12 +109,12 @@ validator operators with `ErrUseValidatorMigration`.
0 commit comments