Skip to content

Commit d82f13b

Browse files
tac0turtletac0turtle
authored
chore: upgrade guide to v0.2.0 (#81)
1 parent cac6f6d commit d82f13b

1 file changed

Lines changed: 149 additions & 0 deletions

File tree

‎docs/UPGRADE-v0.2.0.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Upgrade Guide: v0.2.0
2+
3+
This guide covers the required changes to upgrade ev-reth from v0.1.x to v0.2.0.
4+
5+
## Breaking Changes
6+
7+
### Fusaka Upgrade: `osakaTime` Configuration Required
8+
9+
v0.2.0 adds support for the Fusaka hard fork (based on Ethereum's Osaka upgrade). **You must set `osakaTime` in your chainspec to a future timestamp** to prevent the upgrade from activating immediately.
10+
11+
If `osakaTime` is not set or is set to `0`, the Osaka fork will activate at genesis, which may cause unexpected behavior on existing networks.
12+
13+
#### Action Required
14+
15+
Add `osakaTime` to your chainspec's `config` section with a future Unix timestamp:
16+
17+
```json
18+
{
19+
"config": {
20+
"chainId": 1,
21+
"homesteadBlock": 0,
22+
"eip150Block": 0,
23+
"eip155Block": 0,
24+
"eip158Block": 0,
25+
"byzantiumBlock": 0,
26+
"constantinopleBlock": 0,
27+
"petersburgBlock": 0,
28+
"istanbulBlock": 0,
29+
"berlinBlock": 0,
30+
"londonBlock": 0,
31+
"parisBlock": 0,
32+
"shanghaiTime": 0,
33+
"cancunTime": 0,
34+
"osakaTime": 1893456000,
35+
"terminalTotalDifficulty": 0,
36+
"terminalTotalDifficultyPassed": true,
37+
"evolve": {
38+
...
39+
}
40+
}
41+
}
42+
```
43+
44+
**Important:** Choose a timestamp far enough in the future to allow for coordinated network upgrades. The example above (`1893456000`) corresponds to January 1, 2030.
45+
46+
For testnet deployments where you want to test Osaka features immediately, you can set `osakaTime` to `0`.
47+
48+
## New Configuration Options
49+
50+
### Native Token Minting Precompile
51+
52+
v0.2.0 introduces a native token minting precompile that allows authorized addresses to mint and burn the native token. Add these fields to your chainspec's `evolve` section:
53+
54+
| Field | Type | Description |
55+
|-------|------|-------------|
56+
| `mintPrecompileAdmin` | `address` | Admin address that can manage the allowlist and mint/burn tokens |
57+
| `mintPrecompileActivationHeight` | `number` | Block height at which the precompile becomes active |
58+
59+
```json
60+
"evolve": {
61+
"mintPrecompileAdmin": "0xYourAdminAddressHere",
62+
"mintPrecompileActivationHeight": 0
63+
}
64+
```
65+
66+
Set `mintPrecompileAdmin` to `0x0000000000000000000000000000000000000000` to disable the minting precompile entirely.
67+
68+
For existing networks, set `mintPrecompileActivationHeight` to a future block to ensure archival nodes remain compatible with historical state.
69+
70+
See [ADR-0002: Native Token Minting Precompile](adr/ADR-0002-native-minting-precompile.md) for full details.
71+
72+
## Complete Chainspec Example
73+
74+
Here's a complete example chainspec for v0.2.0 with all new configuration options:
75+
76+
```json
77+
{
78+
"config": {
79+
"chainId": 12345,
80+
"homesteadBlock": 0,
81+
"eip150Block": 0,
82+
"eip155Block": 0,
83+
"eip158Block": 0,
84+
"byzantiumBlock": 0,
85+
"constantinopleBlock": 0,
86+
"petersburgBlock": 0,
87+
"istanbulBlock": 0,
88+
"berlinBlock": 0,
89+
"londonBlock": 0,
90+
"parisBlock": 0,
91+
"shanghaiTime": 0,
92+
"cancunTime": 0,
93+
"osakaTime": 1893456000,
94+
"terminalTotalDifficulty": 0,
95+
"terminalTotalDifficultyPassed": true,
96+
"evolve": {
97+
"baseFeeSink": "0x00000000000000000000000000000000000000fe",
98+
"baseFeeRedirectActivationHeight": 0,
99+
"mintPrecompileAdmin": "0xYourAdminAddressHere",
100+
"mintPrecompileActivationHeight": 0,
101+
"contractSizeLimit": 131072,
102+
"contractSizeLimitActivationHeight": 0
103+
}
104+
},
105+
"difficulty": "0x1",
106+
"gasLimit": "0x1c9c380",
107+
"alloc": {}
108+
}
109+
```
110+
111+
## Upgrade for Existing Networks
112+
113+
For networks already running v0.1.x, use activation heights to safely introduce new features:
114+
115+
```json
116+
"evolve": {
117+
"baseFeeSink": "0x00000000000000000000000000000000000000fe",
118+
"baseFeeRedirectActivationHeight": 20000000,
119+
"mintPrecompileAdmin": "0xYourAdminAddressHere",
120+
"mintPrecompileActivationHeight": 20000000,
121+
"contractSizeLimit": 131072,
122+
"contractSizeLimitActivationHeight": 20000000
123+
}
124+
```
125+
126+
This ensures:
127+
128+
1. Historical blocks remain valid and verifiable
129+
2. Archival nodes can sync from genesis without issues
130+
3. New features activate at a coordinated block height
131+
132+
## Migration Checklist
133+
134+
- [ ] Update chainspec with `osakaTime` set to a future timestamp
135+
- [ ] Add `mintPrecompileAdmin` if native token minting is needed
136+
- [ ] Add `mintPrecompileActivationHeight` (use future block for existing networks)
137+
- [ ] Review all activation heights for existing network compatibility
138+
- [ ] Test chainspec changes on a local/testnet deployment
139+
- [ ] Coordinate upgrade timing with network validators/operators
140+
- [ ] Deploy new ev-reth binary
141+
- [ ] Verify node starts and syncs correctly
142+
143+
## FeeVault Contract Updates
144+
145+
If using the FeeVault contract for base fee collection, the constructor now accepts additional deployment configuration parameters. See [contracts/README.md](../contracts/README.md) for updated deployment instructions.
146+
147+
## Questions?
148+
149+
For issues or questions about the upgrade, please open an issue at <https://github.com/evstack/ev-reth/issues>

0 commit comments

Comments
 (0)