|
| 1 | +# Upgrade Guide: v0.3.0 |
| 2 | + |
| 3 | +This guide covers the new features and changes in ev-reth v0.3.0. |
| 4 | + |
| 5 | +## Breaking Changes |
| 6 | + |
| 7 | +### Reth Upgraded to v1.11.0 (Osaka / EOF Support) |
| 8 | + |
| 9 | +The underlying Reth dependency has been upgraded from v1.8.4 to v1.11.0. This is a major version bump that includes full support for the **Osaka hardfork** and the **EVM Object Format (EOF)**, alongside changes to EVM handler architecture, payload builder interfaces, and execution primitives. |
| 10 | + |
| 11 | +**Osaka hardfork highlights:** |
| 12 | + |
| 13 | +- **EVM Object Format (EOF):** A new structured bytecode format for the EVM. EOF introduces code/data separation, static jumps, a dedicated `RETURNCONTRACT` flow, and removes legacy patterns like `JUMPDEST` analysis. This enables better static analysis, faster contract validation at deploy time, and opens the door to future EVM improvements. EOF contracts coexist with legacy contracts -- existing deployed contracts are unaffected. |
| 14 | +- **Per-transaction gas limit cap:** Osaka introduces `MAX_TX_GAS_LIMIT_OSAKA`, an upper bound on the gas limit any single transaction can specify. ev-reth enforces this cap automatically during block building, payload validation, and EVM configuration when Osaka is active. |
| 15 | + |
| 16 | +**How to activate Osaka on your network:** |
| 17 | + |
| 18 | +Set `osakaTime` in your chainspec to a future Unix timestamp. When the chain reaches that timestamp, the Osaka rules (including EOF validation and the transaction gas cap) take effect. See the [chainspec example](#complete-chainspec-example) below -- the sample already includes `"osakaTime": 1893456000`. |
| 19 | + |
| 20 | +If you do not set `osakaTime`, Osaka remains inactive and the chain continues under Cancun rules. |
| 21 | + |
| 22 | +**Action Required:** Rebuild from source. If you want Osaka active, add or verify `osakaTime` in your chainspec. |
| 23 | + |
| 24 | +### Default Features Disabled for SP1 Compatibility |
| 25 | + |
| 26 | +Several reth crate dependencies now use `default-features = false` to unblock SP1 proving work. The `c-kzg` dependency was also removed from `reth-ethereum-primitives`. This reduces binary size and compilation time for SP1 verification circuits but may affect downstream consumers who relied on default features being enabled. |
| 27 | + |
| 28 | +## New Features |
| 29 | + |
| 30 | +### EvNode Transaction Type (0x76) |
| 31 | + |
| 32 | +v0.3.0 introduces a new EIP-2718 typed transaction (`0x76`) that natively supports **gas sponsorship** and **atomic batch calls**. This is the headline feature of the release. |
| 33 | + |
| 34 | +**Key capabilities:** |
| 35 | + |
| 36 | +- **Batch Calls:** Multiple operations execute atomically within a single transaction. All calls succeed or the entire transaction reverts. |
| 37 | +- **Fee-Payer Sponsorship:** An optional sponsor signature allows a separate account to pay gas on behalf of the executor without changing `tx.origin`. |
| 38 | +- **Open Sponsorship Model:** The executor signs with an empty sponsor field, allowing any sponsor to pick up the signed intent and pay gas. This enables "Gas Station" style networks. |
| 39 | + |
| 40 | +**Transaction structure:** |
| 41 | + |
| 42 | +``` |
| 43 | +Type: 0x76 |
| 44 | +Envelope: 0x76 || rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, calls, access_list, fee_payer_signature, v, r, s]) |
| 45 | +``` |
| 46 | + |
| 47 | +| Field | Type | Description | |
| 48 | +|-------|------|-------------| |
| 49 | +| `chain_id` | `u64` | Chain identifier | |
| 50 | +| `nonce` | `u64` | Executor nonce | |
| 51 | +| `max_priority_fee_per_gas` | `u128` | EIP-1559 priority fee | |
| 52 | +| `max_fee_per_gas` | `u128` | EIP-1559 max fee | |
| 53 | +| `gas_limit` | `u64` | Gas limit for entire batch | |
| 54 | +| `calls` | `Vec<Call>` | Batch of operations (to, value, input) | |
| 55 | +| `access_list` | `AccessList` | State access hints | |
| 56 | +| `fee_payer_signature` | `Option<Signature>` | Optional sponsor authorization | |
| 57 | + |
| 58 | +**Validation rules:** |
| 59 | + |
| 60 | +- At least one call is required |
| 61 | +- Only the first call may be a CREATE; subsequent calls must be CALL |
| 62 | +- Executor signature must be valid for domain `0x76` |
| 63 | +- Sponsor signature (if present) must be valid for domain `0x78` |
| 64 | + |
| 65 | +**Signature domains:** |
| 66 | + |
| 67 | +| Domain | Byte | Signer | Purpose | |
| 68 | +|--------|------|--------|---------| |
| 69 | +| Executor | `0x76` | Transaction sender | Authorizes the intent | |
| 70 | +| Sponsor | `0x78` | Fee payer | Authorizes gas payment for a specific executor intent | |
| 71 | + |
| 72 | +**No chainspec changes required.** The 0x76 transaction type is protocol-level and does not require any configuration. It is available on all networks running v0.3.0. |
| 73 | + |
| 74 | +See [ADR 003](adr/ADR-0003-typed-transactions-sponsorship.md) for the full specification. |
| 75 | + |
| 76 | +### Viem Client Library (`@evstack/evnode-viem`) |
| 77 | + |
| 78 | +A TypeScript/JavaScript client library is now available in `clients/` for creating and managing EvNode transactions using [Viem](https://viem.sh). |
| 79 | + |
| 80 | +**Package:** `@evstack/evnode-viem` (requires `viem ^2.0.0` as peer dependency) |
| 81 | + |
| 82 | +**Supported flows:** |
| 83 | + |
| 84 | +1. **Basic transaction** -- executor pays gas, single or batch calls |
| 85 | +2. **Sponsored transaction** -- sponsor pays gas on behalf of executor |
| 86 | +3. **Intent-based sponsorship** -- executor signs intent off-chain, sponsor picks it up and signs separately |
| 87 | +4. **Contract deployment** -- CREATE call as first operation in a batch |
| 88 | + |
| 89 | +**Example usage:** |
| 90 | + |
| 91 | +```typescript |
| 92 | +import { createEvnodeClient } from '@evstack/evnode-viem' |
| 93 | + |
| 94 | +// Create client with executor wallet |
| 95 | +const client = createEvnodeClient({ |
| 96 | + rpcUrl: 'http://localhost:8545', |
| 97 | + executor: executorAccount, |
| 98 | +}) |
| 99 | + |
| 100 | +// Send a basic transaction |
| 101 | +await client.send({ |
| 102 | + calls: [{ to: '0x...', value: 0n, data: '0x...' }], |
| 103 | + gasLimit: 100000n, |
| 104 | + maxFeePerGas: 1000000000n, |
| 105 | + maxPriorityFeePerGas: 1000000n, |
| 106 | +}) |
| 107 | + |
| 108 | +// Create a sponsorable intent |
| 109 | +const intent = await client.createIntent({ calls, gasLimit, maxFeePerGas, maxPriorityFeePerGas }) |
| 110 | + |
| 111 | +// Sponsor and send (from sponsor side) |
| 112 | +await sponsorClient.sponsorAndSend(intent) |
| 113 | +``` |
| 114 | + |
| 115 | +**RPC extensions:** |
| 116 | + |
| 117 | +- `eth_getTransactionByHash` responses include a `feePayer` field (address) when the transaction is sponsored |
| 118 | +- `eth_getTransactionReceipt` indicates the effective gas payer |
| 119 | + |
| 120 | +### Permissioned EVM: Gas Validation Fix |
| 121 | + |
| 122 | +v0.3.0 fixes deploy allowlist enforcement when gas is explicitly specified. Previously, the deploy allowlist check could be bypassed in certain gas-specified scenarios. The fix ensures: |
| 123 | + |
| 124 | +- Deploy allowlist validation applies uniformly to both standard Ethereum and EvNode transactions |
| 125 | +- Transaction pool admission validates deploy permissions upfront to prevent DoS |
| 126 | +- For sponsored EvNode transactions, the sponsor's balance is validated against `max_fee_per_gas * gas_limit` |
| 127 | + |
| 128 | +**No chainspec changes required.** This is a correctness fix for the existing `deployAllowlist` feature from v0.2.2. |
| 129 | + |
| 130 | +### Container: Tini Init Process |
| 131 | + |
| 132 | +The Docker images now use [tini](https://github.com/krallin/tini) as PID 1 for proper signal forwarding. This ensures graceful shutdown when running in containerized environments (Kubernetes, Docker Compose). |
| 133 | + |
| 134 | +**No action required.** This is automatic when using the official Docker image. |
| 135 | + |
| 136 | +## Complete Chainspec Example |
| 137 | + |
| 138 | +The chainspec format is unchanged from v0.2.2. Here is a complete example for reference: |
| 139 | + |
| 140 | +```json |
| 141 | +{ |
| 142 | + "config": { |
| 143 | + "chainId": 12345, |
| 144 | + "homesteadBlock": 0, |
| 145 | + "eip150Block": 0, |
| 146 | + "eip155Block": 0, |
| 147 | + "eip158Block": 0, |
| 148 | + "byzantiumBlock": 0, |
| 149 | + "constantinopleBlock": 0, |
| 150 | + "petersburgBlock": 0, |
| 151 | + "istanbulBlock": 0, |
| 152 | + "berlinBlock": 0, |
| 153 | + "londonBlock": 0, |
| 154 | + "parisBlock": 0, |
| 155 | + "shanghaiTime": 0, |
| 156 | + "cancunTime": 0, |
| 157 | + "osakaTime": 1893456000, |
| 158 | + "terminalTotalDifficulty": 0, |
| 159 | + "terminalTotalDifficultyPassed": true, |
| 160 | + "evolve": { |
| 161 | + "baseFeeSink": "0x00000000000000000000000000000000000000fe", |
| 162 | + "baseFeeRedirectActivationHeight": 0, |
| 163 | + "mintAdmin": "0x000000000000000000000000000000000000Ad00", |
| 164 | + "mintPrecompileActivationHeight": 0, |
| 165 | + "contractSizeLimit": 131072, |
| 166 | + "contractSizeLimitActivationHeight": 0, |
| 167 | + "deployAllowlist": [ |
| 168 | + "0xYourDeployerAddress" |
| 169 | + ], |
| 170 | + "deployAllowlistActivationHeight": 0, |
| 171 | + "baseFeeMaxChangeDenominator": 8, |
| 172 | + "baseFeeElasticityMultiplier": 2, |
| 173 | + "initialBaseFeePerGas": 1000000000 |
| 174 | + } |
| 175 | + }, |
| 176 | + "difficulty": "0x1", |
| 177 | + "gasLimit": "0x1c9c380", |
| 178 | + "alloc": {} |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +## Upgrade for Existing Networks |
| 183 | + |
| 184 | +v0.3.0 is a drop-in replacement for v0.2.2. No chainspec modifications are required for the binary to run, but activating Osaka requires adding `osakaTime` to your chainspec. |
| 185 | + |
| 186 | +1. The EvNode transaction type (0x76) is automatically available once the binary is upgraded |
| 187 | +2. The permissioned EVM gas fix takes effect immediately |
| 188 | +3. Existing configuration (deploy allowlist, EIP-1559 params, mint precompile) continues to work unchanged |
| 189 | +4. **Osaka activation is opt-in:** add `"osakaTime": <unix_timestamp>` to your chainspec `config` to schedule the hardfork. Without it, the chain stays on Cancun rules and EOF is not enabled |
| 190 | + |
| 191 | +## Migration Checklist |
| 192 | + |
| 193 | +- [ ] Decide whether to activate Osaka on your network and set `osakaTime` in chainspec accordingly |
| 194 | +- [ ] Review the new EvNode transaction type and decide if your application will use it |
| 195 | +- [ ] If using sponsorship: integrate the `@evstack/evnode-viem` client library |
| 196 | +- [ ] If running custom Docker images: verify tini is included or use the official image |
| 197 | +- [ ] Test the upgrade on a local/testnet deployment |
| 198 | +- [ ] Coordinate upgrade timing with network validators/operators |
| 199 | +- [ ] Deploy new ev-reth binary |
| 200 | +- [ ] Verify node starts and syncs correctly |
| 201 | +- [ ] Verify existing transactions and block production continue working |
| 202 | + |
| 203 | +## Related Documentation |
| 204 | + |
| 205 | +- [ADR 003: Typed Transactions for Sponsorship and Batch Calls](adr/ADR-0003-typed-transactions-sponsorship.md) |
| 206 | +- [Permissioned EVM Guide](guide/permissioned-evm.md) |
| 207 | +- [Fee System Guide](guide/fee-systems.md) |
| 208 | +- [AdminProxy Documentation](contracts/admin_proxy.md) |
| 209 | + |
| 210 | +## Questions? |
| 211 | + |
| 212 | +For issues or questions about the upgrade, please open an issue at <https://github.com/evstack/ev-reth/issues> |
0 commit comments