From 4e1f75550c7294bb6f5ef1f8b58e5929b6f16692 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Thu, 22 Jan 2026 17:28:14 +0100 Subject: [PATCH] changelog and guide --- CHANGELOG.md | 11 ++- crates/node/src/chainspec.rs | 14 +++ docs/UPGRADE-v0.2.2.md | 187 +++++++++++++++++++++++++++++++++++ 3 files changed, 207 insertions(+), 5 deletions(-) create mode 100644 docs/UPGRADE-v0.2.2.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e2405b3..0273581 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Fixed -- Add missing payload attribute extraction in `EvolvePayloadBuilder` to properly handle transactions submitted via Engine API ([#33](https://github.com/evstack/ev-reth/pull/33)) -- Remove unused configuration parameters to clean up codebase ([#32](https://github.com/evstack/ev-reth/pull/32)) +### Added -### Changed -- Use `best_transactions` instead of `pending_transactions` queue for improved transaction selection logic ([#29](https://github.com/evstack/ev-reth/pull/29)) +- Permissioned EVM support allowing configurable address-based access control ([#100](https://github.com/evstack/ev-reth/pull/100)) +- EIP-1559 settings to chain configuration for customizing base fee parameters ([#99](https://github.com/evstack/ev-reth/pull/99)) +- AdminProxy contract for administrative operations ([#97](https://github.com/evstack/ev-reth/pull/97)) +- ADR 003: typed sponsorship transactions and batch execution documentation ([#96](https://github.com/evstack/ev-reth/pull/96)) +- Fee system guide documentation ([#101](https://github.com/evstack/ev-reth/pull/101)) diff --git a/crates/node/src/chainspec.rs b/crates/node/src/chainspec.rs index 1c7a2c8..6912fd4 100644 --- a/crates/node/src/chainspec.rs +++ b/crates/node/src/chainspec.rs @@ -194,6 +194,20 @@ mod tests { .contains("initialBaseFeePerGas requires londonBlock set to 0")); } + #[test] + fn test_no_overrides_preserves_defaults() { + let mut genesis = Genesis::default(); + genesis.config.chain_id = 1; + genesis.config.london_block = Some(0); + // No evolve config at all + + let chain_spec = apply_overrides(&genesis).unwrap(); + let params = chain_spec.base_fee_params_at_timestamp(chain_spec.genesis.timestamp); + // Should be Ethereum mainnet defaults + assert_eq!(params.max_change_denominator, 8); + assert_eq!(params.elasticity_multiplier, 2); + } + #[test] fn test_base_fee_denominator_must_be_positive() { let mut genesis = Genesis::default(); diff --git a/docs/UPGRADE-v0.2.2.md b/docs/UPGRADE-v0.2.2.md new file mode 100644 index 0000000..01d064b --- /dev/null +++ b/docs/UPGRADE-v0.2.2.md @@ -0,0 +1,187 @@ +# Upgrade Guide: v0.2.2 + +This guide covers the new features and configuration changes in ev-reth v0.2.2. + +## New Features + +### Permissioned EVM: Deploy Allowlist + +v0.2.2 introduces a deploy allowlist that restricts top-level contract creation to a set of approved EOAs. This is useful for permissioned chains where only authorized deployers should create contracts. + +**Key characteristics:** + +- Only top-level contract creation transactions are checked +- Contract-to-contract `CREATE/CREATE2` is still allowed +- An empty or missing allowlist means unrestricted deployment (disabled) +- Maximum 1024 addresses allowed + +**Chainspec configuration** (inside `config.evolve`): + +```json +"evolve": { + "deployAllowlist": [ + "0xYourDeployerAddressHere", + "0xAnotherDeployerAddressHere" + ], + "deployAllowlistActivationHeight": 0 +} +``` + +| Field | Type | Description | +|-----------------------------------|-------------|--------------------------------------------------------------------| +| `deployAllowlist` | `address[]` | List of EOAs allowed to deploy contracts | +| `deployAllowlistActivationHeight` | `number` | Block height at which the allowlist becomes active (defaults to 0) | + +**Important:** This does not create a fully permissioned chain. Non-allowlisted EOAs can still deploy via existing factory contracts if those factories allow it. + +See [Permissioned EVM Guide](guide/permissioned-evm.md) for full details. + +### EIP-1559 Configuration + +v0.2.2 adds support for customizing EIP-1559 base fee parameters in the chainspec. This allows tuning fee market behavior for your specific use case. + +**Chainspec configuration** (inside `config.evolve`): + +```json +"evolve": { + "baseFeeMaxChangeDenominator": 8, + "baseFeeElasticityMultiplier": 2, + "initialBaseFeePerGas": 1000000000 +} +``` + +| Field | Type | Default | Description | +|-------------------------------|----------|------------|------------------------------------------------------------------| +| `baseFeeMaxChangeDenominator` | `number` | 8 | Controls max base fee change per block (higher = slower changes) | +| `baseFeeElasticityMultiplier` | `number` | 2 | Gas target multiplier for elasticity | +| `initialBaseFeePerGas` | `number` | 1000000000 | Initial base fee in wei (1 gwei default) | + +All fields are optional and default to Ethereum mainnet values if omitted. Existing networks upgrading to v0.2.2 do not need to add these fields - behavior is unchanged unless explicitly configured. + +**Warning:** These parameters apply from genesis with no activation height. Only configure for new networks. Changing on an existing network would invalidate historical block validation. + +### AdminProxy Contract + +v0.2.2 introduces the AdminProxy contract to solve the bootstrap problem for admin addresses at genesis. It allows deploying an admin proxy at genesis with a known owner, then transferring ownership to a multisig post-genesis. + +**Use cases:** + +- Pre-deploy an admin contract when the final multisig address is unknown at genesis +- Manage mint precompile allowlists +- Manage FeeVault configuration + +**Genesis deployment:** + +```json +{ + "alloc": { + "000000000000000000000000000000000000Ad00": { + "balance": "0x0", + "code": "0x", + "storage": { + "0x0": "0x000000000000000000000000" + } + } + } +} +``` + +Generate the alloc entry using the helper script: + +```bash +cd contracts +OWNER=0xYourEOAAddress forge script script/GenerateAdminProxyAlloc.s.sol -vvv +``` + +See [AdminProxy Documentation](contracts/admin_proxy.md) for full details including ownership transfer and usage examples. + +## Complete Chainspec Example + +Here's a complete chainspec for v0.2.2 with all new configuration options: + +```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": { + "000000000000000000000000000000000000Ad00": { + "balance": "0x0", + "code": "0x", + "storage": { + "0x0": "0x000000000000000000000000" + } + } + } +} +``` + +## Upgrade for Existing Networks + +For networks already running v0.2.1, use activation heights to safely introduce the deploy allowlist: + +```json +"evolve": { + "deployAllowlist": [ + "0xYourDeployerAddress" + ], + "deployAllowlistActivationHeight": 25000000 +} +``` + +**Note:** EIP-1559 parameter changes and AdminProxy deployment require genesis modification and cannot be safely introduced to existing networks without a coordinated hardfork. + +## Migration Checklist + +- [ ] Review new configuration options and decide which to enable +- [ ] If using deploy allowlist: add `deployAllowlist` and `deployAllowlistActivationHeight` +- [ ] If customizing EIP-1559: add base fee parameters (new networks only) +- [ ] If using AdminProxy: generate and add alloc entry to genesis (new networks only) +- [ ] Test chainspec changes on a local/testnet deployment +- [ ] Coordinate upgrade timing with network validators/operators +- [ ] Deploy new ev-reth binary +- [ ] Verify node starts and syncs correctly + +## Related Documentation + +- [Permissioned EVM Guide](guide/permissioned-evm.md) +- [AdminProxy Documentation](contracts/admin_proxy.md) +- [Fee System Guide](guide/fee-system.md) +- [ADR 003: Typed Sponsorship Transactions](adr/ADR-0003-typed-sponsorship-transactions.md) + +## Questions? + +For issues or questions about the upgrade, please open an issue at