Skip to content

Commit 8dc991d

Browse files
tac0turtletac0turtle
authored
changelog and guide (#107)
1 parent c3a6036 commit 8dc991d

File tree

3 files changed

+207
-5
lines changed

3 files changed

+207
-5
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10-
### Fixed
11-
- Add missing payload attribute extraction in `EvolvePayloadBuilder` to properly handle transactions submitted via Engine API ([#33](https://github.com/evstack/ev-reth/pull/33))
12-
- Remove unused configuration parameters to clean up codebase ([#32](https://github.com/evstack/ev-reth/pull/32))
10+
### Added
1311

14-
### Changed
15-
- Use `best_transactions` instead of `pending_transactions` queue for improved transaction selection logic ([#29](https://github.com/evstack/ev-reth/pull/29))
12+
- Permissioned EVM support allowing configurable address-based access control ([#100](https://github.com/evstack/ev-reth/pull/100))
13+
- EIP-1559 settings to chain configuration for customizing base fee parameters ([#99](https://github.com/evstack/ev-reth/pull/99))
14+
- AdminProxy contract for administrative operations ([#97](https://github.com/evstack/ev-reth/pull/97))
15+
- ADR 003: typed sponsorship transactions and batch execution documentation ([#96](https://github.com/evstack/ev-reth/pull/96))
16+
- Fee system guide documentation ([#101](https://github.com/evstack/ev-reth/pull/101))

‎crates/node/src/chainspec.rs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,20 @@ mod tests {
194194
.contains("initialBaseFeePerGas requires londonBlock set to 0"));
195195
}
196196

197+
#[test]
198+
fn test_no_overrides_preserves_defaults() {
199+
let mut genesis = Genesis::default();
200+
genesis.config.chain_id = 1;
201+
genesis.config.london_block = Some(0);
202+
// No evolve config at all
203+
204+
let chain_spec = apply_overrides(&genesis).unwrap();
205+
let params = chain_spec.base_fee_params_at_timestamp(chain_spec.genesis.timestamp);
206+
// Should be Ethereum mainnet defaults
207+
assert_eq!(params.max_change_denominator, 8);
208+
assert_eq!(params.elasticity_multiplier, 2);
209+
}
210+
197211
#[test]
198212
fn test_base_fee_denominator_must_be_positive() {
199213
let mut genesis = Genesis::default();

‎docs/UPGRADE-v0.2.2.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Upgrade Guide: v0.2.2
2+
3+
This guide covers the new features and configuration changes in ev-reth v0.2.2.
4+
5+
## New Features
6+
7+
### Permissioned EVM: Deploy Allowlist
8+
9+
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.
10+
11+
**Key characteristics:**
12+
13+
- Only top-level contract creation transactions are checked
14+
- Contract-to-contract `CREATE/CREATE2` is still allowed
15+
- An empty or missing allowlist means unrestricted deployment (disabled)
16+
- Maximum 1024 addresses allowed
17+
18+
**Chainspec configuration** (inside `config.evolve`):
19+
20+
```json
21+
"evolve": {
22+
"deployAllowlist": [
23+
"0xYourDeployerAddressHere",
24+
"0xAnotherDeployerAddressHere"
25+
],
26+
"deployAllowlistActivationHeight": 0
27+
}
28+
```
29+
30+
| Field | Type | Description |
31+
|-----------------------------------|-------------|--------------------------------------------------------------------|
32+
| `deployAllowlist` | `address[]` | List of EOAs allowed to deploy contracts |
33+
| `deployAllowlistActivationHeight` | `number` | Block height at which the allowlist becomes active (defaults to 0) |
34+
35+
**Important:** This does not create a fully permissioned chain. Non-allowlisted EOAs can still deploy via existing factory contracts if those factories allow it.
36+
37+
See [Permissioned EVM Guide](guide/permissioned-evm.md) for full details.
38+
39+
### EIP-1559 Configuration
40+
41+
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.
42+
43+
**Chainspec configuration** (inside `config.evolve`):
44+
45+
```json
46+
"evolve": {
47+
"baseFeeMaxChangeDenominator": 8,
48+
"baseFeeElasticityMultiplier": 2,
49+
"initialBaseFeePerGas": 1000000000
50+
}
51+
```
52+
53+
| Field | Type | Default | Description |
54+
|-------------------------------|----------|------------|------------------------------------------------------------------|
55+
| `baseFeeMaxChangeDenominator` | `number` | 8 | Controls max base fee change per block (higher = slower changes) |
56+
| `baseFeeElasticityMultiplier` | `number` | 2 | Gas target multiplier for elasticity |
57+
| `initialBaseFeePerGas` | `number` | 1000000000 | Initial base fee in wei (1 gwei default) |
58+
59+
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.
60+
61+
**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.
62+
63+
### AdminProxy Contract
64+
65+
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.
66+
67+
**Use cases:**
68+
69+
- Pre-deploy an admin contract when the final multisig address is unknown at genesis
70+
- Manage mint precompile allowlists
71+
- Manage FeeVault configuration
72+
73+
**Genesis deployment:**
74+
75+
```json
76+
{
77+
"alloc": {
78+
"000000000000000000000000000000000000Ad00": {
79+
"balance": "0x0",
80+
"code": "0x<ADMIN_PROXY_BYTECODE>",
81+
"storage": {
82+
"0x0": "0x000000000000000000000000<OWNER_ADDRESS_WITHOUT_0x>"
83+
}
84+
}
85+
}
86+
}
87+
```
88+
89+
Generate the alloc entry using the helper script:
90+
91+
```bash
92+
cd contracts
93+
OWNER=0xYourEOAAddress forge script script/GenerateAdminProxyAlloc.s.sol -vvv
94+
```
95+
96+
See [AdminProxy Documentation](contracts/admin_proxy.md) for full details including ownership transfer and usage examples.
97+
98+
## Complete Chainspec Example
99+
100+
Here's a complete chainspec for v0.2.2 with all new configuration options:
101+
102+
```json
103+
{
104+
"config": {
105+
"chainId": 12345,
106+
"homesteadBlock": 0,
107+
"eip150Block": 0,
108+
"eip155Block": 0,
109+
"eip158Block": 0,
110+
"byzantiumBlock": 0,
111+
"constantinopleBlock": 0,
112+
"petersburgBlock": 0,
113+
"istanbulBlock": 0,
114+
"berlinBlock": 0,
115+
"londonBlock": 0,
116+
"parisBlock": 0,
117+
"shanghaiTime": 0,
118+
"cancunTime": 0,
119+
"osakaTime": 1893456000,
120+
"terminalTotalDifficulty": 0,
121+
"terminalTotalDifficultyPassed": true,
122+
"evolve": {
123+
"baseFeeSink": "0x00000000000000000000000000000000000000fe",
124+
"baseFeeRedirectActivationHeight": 0,
125+
"mintAdmin": "0x000000000000000000000000000000000000Ad00",
126+
"mintPrecompileActivationHeight": 0,
127+
"contractSizeLimit": 131072,
128+
"contractSizeLimitActivationHeight": 0,
129+
"deployAllowlist": [
130+
"0xYourDeployerAddress"
131+
],
132+
"deployAllowlistActivationHeight": 0,
133+
"baseFeeMaxChangeDenominator": 8,
134+
"baseFeeElasticityMultiplier": 2,
135+
"initialBaseFeePerGas": 1000000000
136+
}
137+
},
138+
"difficulty": "0x1",
139+
"gasLimit": "0x1c9c380",
140+
"alloc": {
141+
"000000000000000000000000000000000000Ad00": {
142+
"balance": "0x0",
143+
"code": "0x<ADMIN_PROXY_BYTECODE>",
144+
"storage": {
145+
"0x0": "0x000000000000000000000000<OWNER_ADDRESS>"
146+
}
147+
}
148+
}
149+
}
150+
```
151+
152+
## Upgrade for Existing Networks
153+
154+
For networks already running v0.2.1, use activation heights to safely introduce the deploy allowlist:
155+
156+
```json
157+
"evolve": {
158+
"deployAllowlist": [
159+
"0xYourDeployerAddress"
160+
],
161+
"deployAllowlistActivationHeight": 25000000
162+
}
163+
```
164+
165+
**Note:** EIP-1559 parameter changes and AdminProxy deployment require genesis modification and cannot be safely introduced to existing networks without a coordinated hardfork.
166+
167+
## Migration Checklist
168+
169+
- [ ] Review new configuration options and decide which to enable
170+
- [ ] If using deploy allowlist: add `deployAllowlist` and `deployAllowlistActivationHeight`
171+
- [ ] If customizing EIP-1559: add base fee parameters (new networks only)
172+
- [ ] If using AdminProxy: generate and add alloc entry to genesis (new networks only)
173+
- [ ] Test chainspec changes on a local/testnet deployment
174+
- [ ] Coordinate upgrade timing with network validators/operators
175+
- [ ] Deploy new ev-reth binary
176+
- [ ] Verify node starts and syncs correctly
177+
178+
## Related Documentation
179+
180+
- [Permissioned EVM Guide](guide/permissioned-evm.md)
181+
- [AdminProxy Documentation](contracts/admin_proxy.md)
182+
- [Fee System Guide](guide/fee-system.md)
183+
- [ADR 003: Typed Sponsorship Transactions](adr/ADR-0003-typed-sponsorship-transactions.md)
184+
185+
## Questions?
186+
187+
For issues or questions about the upgrade, please open an issue at <https://github.com/evstack/ev-reth/issues>

0 commit comments

Comments
 (0)