diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d72825..63db763 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,18 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- `EV_TRACE_LEVEL` env var to control OTLP span export verbosity independently from `RUST_LOG` stdout log level ([#156](https://github.com/evstack/ev-reth/issues/156)) +- `ev-deployer` CLI (`bin/ev-deployer`) for generating genesis alloc entries with embedded contract bytecodes ([#167](https://github.com/evstack/ev-reth/pull/167)) - `ev-dev` binary (`bin/ev-dev`): one-command local development chain with pre-funded Hardhat accounts, similar to Anvil or Hardhat Node - Transaction sponsor service (`bin/sponsor-service`) for signing EvNode transactions on behalf of users via JSON-RPC proxy ([#141](https://github.com/evstack/ev-reth/pull/141)) +- Granular tracing instrumentation spans across payload building, transaction validation, and EVM execution +- `EV_TRACE_LEVEL` env var to control OTLP span export verbosity independently from `RUST_LOG` stdout log level ([#156](https://github.com/evstack/ev-reth/issues/156)) ### Changed +- Upgraded Reth from v1.11.x to v2.0.0 with Storage V2 support, revm 36.0.0, and alloy-evm 0.30.0 ([#207](https://github.com/evstack/ev-reth/pull/207)) +- `reth-primitives` imports migrated to `alloy_consensus` and `reth_ethereum_primitives` (upstream crate removed) +- Txpool fallback (pulling pending transactions when Engine API attributes are empty) restricted to `--dev` mode only +- Migrated build system from Makefile to Justfile - Removed unused `thiserror` dependency from `ev-precompiles` crate ### Fixed +- Payload builder now uses `decode_2718_exact` instead of `network_decode` for Engine API payloads, fixing silent drops of valid type 0x76 and EIP-1559/EIP-2930 transactions ([#219](https://github.com/evstack/ev-reth/pull/219)) - Payload builder now pulls pending transactions from the txpool in `--dev` mode, fixing `cast send` and other RPC-submitted transactions not being included in blocks - Txpool now uses sponsor balance for pending/queued ordering in sponsored EvNode transactions, and validates executor balance separately for call value transfers ([#141](https://github.com/evstack/ev-reth/pull/141)) +- Additional test coverage for deploy allowlist edge cases across all transaction types ## [0.3.0] - 2026-02-23 diff --git a/docs/UPGRADE-v0.3.0.md b/docs/UPGRADE-v0.3.0.md deleted file mode 100644 index 192eb90..0000000 --- a/docs/UPGRADE-v0.3.0.md +++ /dev/null @@ -1,212 +0,0 @@ -# Upgrade Guide: v0.3.0 - -This guide covers the new features and changes in ev-reth v0.3.0. - -## Breaking Changes - -### Reth Upgraded to v1.11.0 (Osaka / EOF Support) - -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. - -**Osaka hardfork highlights:** - -- **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. -- **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. - -**How to activate Osaka on your network:** - -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`. - -If you do not set `osakaTime`, Osaka remains inactive and the chain continues under Cancun rules. - -**Action Required:** Rebuild from source. If you want Osaka active, add or verify `osakaTime` in your chainspec. - -### Default Features Disabled for SP1 Compatibility - -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. - -## New Features - -### EvNode Transaction Type (0x76) - -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. - -**Key capabilities:** - -- **Batch Calls:** Multiple operations execute atomically within a single transaction. All calls succeed or the entire transaction reverts. -- **Fee-Payer Sponsorship:** An optional sponsor signature allows a separate account to pay gas on behalf of the executor without changing `tx.origin`. -- **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. - -**Transaction structure:** - -``` -Type: 0x76 -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]) -``` - -| Field | Type | Description | -|-------|------|-------------| -| `chain_id` | `u64` | Chain identifier | -| `nonce` | `u64` | Executor nonce | -| `max_priority_fee_per_gas` | `u128` | EIP-1559 priority fee | -| `max_fee_per_gas` | `u128` | EIP-1559 max fee | -| `gas_limit` | `u64` | Gas limit for entire batch | -| `calls` | `Vec` | Batch of operations (to, value, input) | -| `access_list` | `AccessList` | State access hints | -| `fee_payer_signature` | `Option` | Optional sponsor authorization | - -**Validation rules:** - -- At least one call is required -- Only the first call may be a CREATE; subsequent calls must be CALL -- Executor signature must be valid for domain `0x76` -- Sponsor signature (if present) must be valid for domain `0x78` - -**Signature domains:** - -| Domain | Byte | Signer | Purpose | -|--------|------|--------|---------| -| Executor | `0x76` | Transaction sender | Authorizes the intent | -| Sponsor | `0x78` | Fee payer | Authorizes gas payment for a specific executor intent | - -**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. - -See [ADR 003](adr/ADR-0003-typed-transactions-sponsorship.md) for the full specification. - -### Viem Client Library (`@evstack/evnode-viem`) - -A TypeScript/JavaScript client library is now available in `clients/` for creating and managing EvNode transactions using [Viem](https://viem.sh). - -**Package:** `@evstack/evnode-viem` (requires `viem ^2.0.0` as peer dependency) - -**Supported flows:** - -1. **Basic transaction** -- executor pays gas, single or batch calls -2. **Sponsored transaction** -- sponsor pays gas on behalf of executor -3. **Intent-based sponsorship** -- executor signs intent off-chain, sponsor picks it up and signs separately -4. **Contract deployment** -- CREATE call as first operation in a batch - -**Example usage:** - -```typescript -import { createEvnodeClient } from '@evstack/evnode-viem' - -// Create client with executor wallet -const client = createEvnodeClient({ - rpcUrl: 'http://localhost:8545', - executor: executorAccount, -}) - -// Send a basic transaction -await client.send({ - calls: [{ to: '0x...', value: 0n, data: '0x...' }], - gasLimit: 100000n, - maxFeePerGas: 1000000000n, - maxPriorityFeePerGas: 1000000n, -}) - -// Create a sponsorable intent -const intent = await client.createIntent({ calls, gasLimit, maxFeePerGas, maxPriorityFeePerGas }) - -// Sponsor and send (from sponsor side) -await sponsorClient.sponsorAndSend(intent) -``` - -**RPC extensions:** - -- `eth_getTransactionByHash` responses include a `feePayer` field (address) when the transaction is sponsored -- `eth_getTransactionReceipt` indicates the effective gas payer - -### Permissioned EVM: Gas Validation Fix - -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: - -- Deploy allowlist validation applies uniformly to both standard Ethereum and EvNode transactions -- Transaction pool admission validates deploy permissions upfront to prevent DoS -- For sponsored EvNode transactions, the sponsor's balance is validated against `max_fee_per_gas * gas_limit` - -**No chainspec changes required.** This is a correctness fix for the existing `deployAllowlist` feature from v0.2.2. - -### Container: Tini Init Process - -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). - -**No action required.** This is automatic when using the official Docker image. - -## Complete Chainspec Example - -The chainspec format is unchanged from v0.2.2. Here is a complete example for reference: - -```json -{ - "config": { - "chainId": 12345, - "homesteadBlock": 0, - "eip150Block": 0, - "eip155Block": 0, - "eip158Block": 0, - "byzantiumBlock": 0, - "constantinopleBlock": 0, - "petersburgBlock": 0, - "istanbulBlock": 0, - "berlinBlock": 0, - "londonBlock": 0, - "parisBlock": 0, - "shanghaiTime": 0, - "cancunTime": 0, - "osakaTime": 1893456000, - "terminalTotalDifficulty": 0, - "terminalTotalDifficultyPassed": true, - "evolve": { - "baseFeeSink": "0x00000000000000000000000000000000000000fe", - "baseFeeRedirectActivationHeight": 0, - "mintAdmin": "0x000000000000000000000000000000000000Ad00", - "mintPrecompileActivationHeight": 0, - "contractSizeLimit": 131072, - "contractSizeLimitActivationHeight": 0, - "deployAllowlist": [ - "0xYourDeployerAddress" - ], - "deployAllowlistActivationHeight": 0, - "baseFeeMaxChangeDenominator": 8, - "baseFeeElasticityMultiplier": 2, - "initialBaseFeePerGas": 1000000000 - } - }, - "difficulty": "0x1", - "gasLimit": "0x1c9c380", - "alloc": {} -} -``` - -## Upgrade for Existing Networks - -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. - -1. The EvNode transaction type (0x76) is automatically available once the binary is upgraded -2. The permissioned EVM gas fix takes effect immediately -3. Existing configuration (deploy allowlist, EIP-1559 params, mint precompile) continues to work unchanged -4. **Osaka activation is opt-in:** add `"osakaTime": ` to your chainspec `config` to schedule the hardfork. Without it, the chain stays on Cancun rules and EOF is not enabled - -## Migration Checklist - -- [ ] Decide whether to activate Osaka on your network and set `osakaTime` in chainspec accordingly -- [ ] Review the new EvNode transaction type and decide if your application will use it -- [ ] If using sponsorship: integrate the `@evstack/evnode-viem` client library -- [ ] If running custom Docker images: verify tini is included or use the official image -- [ ] Test the upgrade on a local/testnet deployment -- [ ] Coordinate upgrade timing with network validators/operators -- [ ] Deploy new ev-reth binary -- [ ] Verify node starts and syncs correctly -- [ ] Verify existing transactions and block production continue working - -## Related Documentation - -- [ADR 003: Typed Transactions for Sponsorship and Batch Calls](adr/ADR-0003-typed-transactions-sponsorship.md) -- [Permissioned EVM Guide](guide/permissioned-evm.md) -- [Fee System Guide](guide/fee-systems.md) -- [AdminProxy Documentation](contracts/admin_proxy.md) - -## Questions? - -For issues or questions about the upgrade, please open an issue at diff --git a/docs/UPGRADE-v0.4.0.md b/docs/UPGRADE-v0.4.0.md new file mode 100644 index 0000000..eccacd5 --- /dev/null +++ b/docs/UPGRADE-v0.4.0.md @@ -0,0 +1,227 @@ +# Upgrade Guide: v0.4.0 + +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). + +## Upgrading from v0.3.0 + +No configuration changes required. Rebuild and deploy the new binary. + +**What changes automatically:** + +- Reth v2.0.0 engine (same config, new internals) +- New nodes use Storage V2 by default. Existing V1 data directories continue working as-is +- Txpool fallback (pulling pending transactions when Engine API attributes are empty) is now only enabled in `--dev` mode +- EIP-2718 payload decode fix takes effect immediately + +**Build system:** If you have scripts referencing `make`, update them to use `just`. + +**Storage V2 notes:** + +- V1 and V2 are not interchangeable. Once a node starts with V2, it cannot go back +- No automatic migration. Switching to V2 requires a full resync +- V1 is deprecated upstream. Plan your migration before support is removed +- If using MDBX backup scripts (e.g. `mdbx_copy`), V2 nodes also use RocksDB for indices, so backup tooling may need updating + +**Custom code:** If you import from `reth-primitives`, update imports to `alloy_consensus` or `reth_ethereum_primitives` (the crate was removed upstream). + +## Upgrading from v0.2.2 + +Everything in "Upgrading from v0.3.0" above, plus the following chainspec change: + +### Osaka Hardfork (optional) + +Add `osakaTime` to your chainspec `config` section to activate the Osaka hardfork (EOF support). Without it, the chain stays on Cancun rules. + +```json +{ + "config": { + "osakaTime": 1893456000 + } +} +``` + +Choose a timestamp far enough in the future to coordinate the upgrade across all nodes. Set to `0` on testnets to activate immediately. + +No other configuration changes are required. The EvNode transaction type (0x76) is available automatically once the binary is upgraded. + +## Upgrading from v0.2.0 + +Everything in "Upgrading from v0.2.2" above, plus the following chainspec changes inside `config.evolve`: + +### Deploy Allowlist (optional) + +Restrict top-level contract creation to approved addresses. + +```json +{ + "config": { + "evolve": { + "deployAllowlist": ["0xYourDeployerAddress"], + "deployAllowlistActivationHeight": 0 + } + } +} +``` + +For existing networks, set `deployAllowlistActivationHeight` to a future block height. + +### EIP-1559 Parameters (optional, new networks only) + +Customize base fee behavior. These apply from genesis with no activation height, so only configure for new networks. + +```json +{ + "config": { + "evolve": { + "baseFeeMaxChangeDenominator": 5000, + "baseFeeElasticityMultiplier": 10, + "initialBaseFeePerGas": 100000000000000000 + } + } +} +``` + +| Field | Default | Description | +|-------|---------|-------------| +| `baseFeeMaxChangeDenominator` | `8` | Max base fee change per block. Higher = slower changes | +| `baseFeeElasticityMultiplier` | `2` | Gas target multiplier | +| `initialBaseFeePerGas` | `1000000000` | Initial base fee in wei | + +See [EIP-1559 Configuration](eip1559-configuration.md) for tuning recommendations. + +## Upgrading from v0.1.x + +Everything in "Upgrading from v0.2.0" above, plus the following chainspec changes: + +### Osaka Timestamp (required) + +You **must** set `osakaTime` to a future timestamp. If omitted or set to `0`, the Osaka fork activates at genesis, which may cause unexpected behavior on existing networks. + +### Base Fee Redirect + +Redirect burned base fees to a sink address instead of burning them. + +```json +{ + "config": { + "evolve": { + "baseFeeSink": "0x00000000000000000000000000000000000000fe", + "baseFeeRedirectActivationHeight": 0 + } + } +} +``` + +For existing networks, set `baseFeeRedirectActivationHeight` to a future block height. + +### Native Token Minting Precompile + +Enable minting and burning of the native token by authorized addresses. + +```json +{ + "config": { + "evolve": { + "mintAdmin": "0x000000000000000000000000000000000000Ad00", + "mintPrecompileActivationHeight": 0 + } + } +} +``` + +Set `mintAdmin` to the zero address to disable. For existing networks, set `mintPrecompileActivationHeight` to a future block height. + +### Contract Size Limit + +Override the default 24KB EIP-170 contract size limit. + +```json +{ + "config": { + "evolve": { + "contractSizeLimit": 131072, + "contractSizeLimitActivationHeight": 0 + } + } +} +``` + +## Complete Chainspec Reference + +All `config.evolve` fields available in v0.4.0: + +| Field | Type | Default | Since | Description | +|-------|------|---------|-------|-------------| +| `baseFeeSink` | `address` | -- | v0.2.0 | Receives redirected base fees | +| `baseFeeRedirectActivationHeight` | `u64` | `0` | v0.2.0 | Block height when redirect activates | +| `mintAdmin` | `address` | -- | v0.2.0 | Admin for mint/burn precompile | +| `mintPrecompileActivationHeight` | `u64` | `0` | v0.2.0 | Block height when precompile activates | +| `contractSizeLimit` | `usize` | `24576` | v0.2.0 | Max contract code size in bytes | +| `contractSizeLimitActivationHeight` | `u64` | `0` | v0.2.0 | Block height when custom limit activates | +| `deployAllowlist` | `address[]` | `[]` | v0.2.2 | Addresses allowed to deploy contracts (max 1024) | +| `deployAllowlistActivationHeight` | `u64` | `0` | v0.2.2 | Block height when allowlist activates | +| `baseFeeMaxChangeDenominator` | `u64` | `8` | v0.2.2 | Max base fee change per block | +| `baseFeeElasticityMultiplier` | `u64` | `2` | v0.2.2 | Gas target multiplier | +| `initialBaseFeePerGas` | `u64` | `1000000000` | v0.2.2 | Initial base fee in wei | + +Top-level `config` fields: + +| Field | Type | Default | Since | Description | +|-------|------|---------|-------|-------------| +| `osakaTime` | `u64` | -- | v0.3.0 | Unix timestamp to activate Osaka/EOF hardfork | + +## Complete Chainspec Example + +```json +{ + "config": { + "chainId": 12345, + "homesteadBlock": 0, + "eip150Block": 0, + "eip155Block": 0, + "eip158Block": 0, + "byzantiumBlock": 0, + "constantinopleBlock": 0, + "petersburgBlock": 0, + "istanbulBlock": 0, + "berlinBlock": 0, + "londonBlock": 0, + "parisBlock": 0, + "shanghaiTime": 0, + "cancunTime": 0, + "osakaTime": 1893456000, + "terminalTotalDifficulty": 0, + "terminalTotalDifficultyPassed": true, + "evolve": { + "baseFeeSink": "0x00000000000000000000000000000000000000fe", + "baseFeeRedirectActivationHeight": 0, + "baseFeeMaxChangeDenominator": 5000, + "baseFeeElasticityMultiplier": 10, + "initialBaseFeePerGas": 100000000000000000, + "mintAdmin": "0x000000000000000000000000000000000000Ad00", + "mintPrecompileActivationHeight": 0, + "contractSizeLimit": 131072, + "contractSizeLimitActivationHeight": 0, + "deployAllowlist": [ + "0xYourDeployerAddress" + ], + "deployAllowlistActivationHeight": 0 + } + }, + "difficulty": "0x1", + "gasLimit": "0x2faf080", + "baseFeePerGas": "0x16345785d8a0000", + "alloc": {} +} +``` + +## Related Documentation + +- [EIP-1559 Configuration](eip1559-configuration.md) -- tuning base fee parameters +- [Permissioned EVM Guide](guide/permissioned-evm.md) -- deploy allowlist details +- [Fee System Guide](guide/fee-systems.md) -- base fee redirect and FeeVault +- [ADR 003: Typed Transactions](adr/ADR-0003-typed-transactions-sponsorship.md) -- EvNode 0x76 spec + +## Questions? + +For issues or questions about the upgrade, please open an issue at