|
| 1 | +# Upgrade Guide: v0.4.0 |
| 2 | + |
| 3 | +This guide covers the configuration changes required to upgrade ev-reth to v0.4.0. For a full list of changes, see the [CHANGELOG](../CHANGELOG.md). |
| 4 | + |
| 5 | +> **Note:** v0.3.0 was never released. Operators running a v0.3.0-beta build should follow "Upgrading from v0.2.x" below. |
| 6 | +
|
| 7 | +## Upgrading from v0.2.x |
| 8 | + |
| 9 | +No configuration changes required. Rebuild and deploy the new binary. |
| 10 | + |
| 11 | +**What changes automatically:** |
| 12 | + |
| 13 | +- Reth v2.0.0 engine (same config, new internals) |
| 14 | +- New nodes use Storage V2 by default. Existing V1 data directories continue working as-is |
| 15 | +- Txpool fallback (pulling pending transactions when Engine API attributes are empty) is now only enabled in `--dev` mode |
| 16 | +- EIP-2718 payload decode fix takes effect immediately |
| 17 | + |
| 18 | +**Build system:** If you have scripts referencing `make`, update them to use `just`. |
| 19 | + |
| 20 | +**Storage V2 notes:** |
| 21 | + |
| 22 | +- V1 and V2 are not interchangeable. Once a node starts with V2, it cannot go back |
| 23 | +- No automatic migration. Switching to V2 requires a full resync |
| 24 | +- V1 is deprecated upstream. Plan your migration before support is removed |
| 25 | +- If using MDBX backup scripts (e.g. `mdbx_copy`), V2 nodes also use RocksDB for indices, so backup tooling may need updating |
| 26 | + |
| 27 | +**Custom code:** If you import from `reth-primitives`, update imports to `alloy_consensus` or `reth_ethereum_primitives` (the crate was removed upstream). |
| 28 | + |
| 29 | +### Osaka / EOF hardfork |
| 30 | + |
| 31 | +The Osaka hardfork (EVM Object Format, EOFv1) is available but not activated by default. If your chainspec does not already set `osakaTime`, the chain stays on Cancun rules and no action is required. |
| 32 | + |
| 33 | +To schedule activation, add `osakaTime` to your chainspec `config` section with a future Unix timestamp (use `0` on new testnets to activate from genesis): |
| 34 | + |
| 35 | +```json |
| 36 | +{ |
| 37 | + "config": { |
| 38 | + "osakaTime": 1893456000 |
| 39 | + } |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +Osaka introduces EOFv1 contracts and related EIPs. See the [v0.2.0 upgrade guide](UPGRADE-v0.2.0.md) for the original `osakaTime` rollout notes and the [Ethereum EOF meta EIP (EIP-7692)](https://eips.ethereum.org/EIPS/eip-7692) for the full list of included changes. |
| 44 | + |
| 45 | +## Upgrading from v0.1.x |
| 46 | + |
| 47 | +First follow [UPGRADE-v0.2.0.md](UPGRADE-v0.2.0.md) and [UPGRADE-v0.2.2.md](UPGRADE-v0.2.2.md) to reach v0.2.x, then apply "Upgrading from v0.2.x" above. Those guides cover the required `osakaTime`, base fee redirect, native token minting precompile, contract size limit, deploy allowlist, and EIP-1559 parameter chainspec changes. |
| 48 | + |
| 49 | +## Complete Chainspec Reference |
| 50 | + |
| 51 | +All `config.evolve` fields available in v0.4.0: |
| 52 | + |
| 53 | +| Field | Type | Default | Since | Description | |
| 54 | +|-------|------|---------|-------|-------------| |
| 55 | +| `baseFeeSink` | `address` | -- | v0.2.0 | Receives redirected base fees | |
| 56 | +| `baseFeeRedirectActivationHeight` | `u64` | `0` | v0.2.0 | Block height when redirect activates | |
| 57 | +| `mintAdmin` | `address` | -- | v0.2.0 | Admin for mint/burn precompile | |
| 58 | +| `mintPrecompileActivationHeight` | `u64` | `0` | v0.2.0 | Block height when precompile activates | |
| 59 | +| `contractSizeLimit` | `usize` | `24576` | v0.2.0 | Max contract code size in bytes | |
| 60 | +| `contractSizeLimitActivationHeight` | `u64` | `0` | v0.2.0 | Block height when custom limit activates | |
| 61 | +| `deployAllowlist` | `address[]` | `[]` | v0.2.2 | Addresses allowed to deploy contracts (max 1024) | |
| 62 | +| `deployAllowlistActivationHeight` | `u64` | `0` | v0.2.2 | Block height when allowlist activates | |
| 63 | +| `baseFeeMaxChangeDenominator` | `u64` | `8` | v0.2.2 | Max base fee change per block | |
| 64 | +| `baseFeeElasticityMultiplier` | `u64` | `2` | v0.2.2 | Gas target multiplier | |
| 65 | +| `initialBaseFeePerGas` | `u64` | `1000000000` | v0.2.2 | Initial base fee in wei | |
| 66 | + |
| 67 | +Top-level `config` fields: |
| 68 | + |
| 69 | +| Field | Type | Default | Since | Description | |
| 70 | +|-------|------|---------|-------|-------------| |
| 71 | +| `osakaTime` | `u64` | -- | v0.2.0 | Unix timestamp to activate Osaka/EOF hardfork | |
| 72 | + |
| 73 | +## Complete Chainspec Example |
| 74 | + |
| 75 | +```json |
| 76 | +{ |
| 77 | + "config": { |
| 78 | + "chainId": 12345, |
| 79 | + "homesteadBlock": 0, |
| 80 | + "eip150Block": 0, |
| 81 | + "eip155Block": 0, |
| 82 | + "eip158Block": 0, |
| 83 | + "byzantiumBlock": 0, |
| 84 | + "constantinopleBlock": 0, |
| 85 | + "petersburgBlock": 0, |
| 86 | + "istanbulBlock": 0, |
| 87 | + "berlinBlock": 0, |
| 88 | + "londonBlock": 0, |
| 89 | + "parisBlock": 0, |
| 90 | + "shanghaiTime": 0, |
| 91 | + "cancunTime": 0, |
| 92 | + "osakaTime": 1893456000, |
| 93 | + "terminalTotalDifficulty": 0, |
| 94 | + "terminalTotalDifficultyPassed": true, |
| 95 | + "evolve": { |
| 96 | + "baseFeeSink": "0x00000000000000000000000000000000000000fe", |
| 97 | + "baseFeeRedirectActivationHeight": 0, |
| 98 | + "baseFeeMaxChangeDenominator": 5000, |
| 99 | + "baseFeeElasticityMultiplier": 10, |
| 100 | + "initialBaseFeePerGas": 100000000000000000, |
| 101 | + "mintAdmin": "0x000000000000000000000000000000000000Ad00", |
| 102 | + "mintPrecompileActivationHeight": 0, |
| 103 | + "contractSizeLimit": 131072, |
| 104 | + "contractSizeLimitActivationHeight": 0, |
| 105 | + "deployAllowlist": [ |
| 106 | + "0xYourDeployerAddress" |
| 107 | + ], |
| 108 | + "deployAllowlistActivationHeight": 0 |
| 109 | + } |
| 110 | + }, |
| 111 | + "difficulty": "0x1", |
| 112 | + "gasLimit": "0x2faf080", |
| 113 | + "baseFeePerGas": "0x16345785d8a0000", |
| 114 | + "alloc": {} |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +## Related Documentation |
| 119 | + |
| 120 | +- [EIP-1559 Configuration](eip1559-configuration.md) -- tuning base fee parameters |
| 121 | +- [Permissioned EVM Guide](guide/permissioned-evm.md) -- deploy allowlist details |
| 122 | +- [Fee System Guide](guide/fee-systems.md) -- base fee redirect and FeeVault |
| 123 | +- [ADR 003: Typed Transactions](adr/ADR-0003-typed-transactions-sponsorship.md) -- EvNode 0x76 spec |
| 124 | + |
| 125 | +## Questions? |
| 126 | + |
| 127 | +For issues or questions about the upgrade, please open an issue at <https://github.com/evstack/ev-reth/issues> |
0 commit comments