Skip to content

Commit f5e1c19

Browse files
randygrokrandygrok
committed
Merge remote-tracking branch 'origin/main' into randygrok/adr-phase2
2 parents 3c1af2b + 5d73978 commit f5e1c19

File tree

9 files changed

+1070
-1
lines changed

9 files changed

+1070
-1
lines changed

‎.claude/skills/contracts.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
description: This skill should be used when the user asks about "ev-reth contracts", "FeeVault", "AdminProxy", "fee bridging to Celestia", "Hyperlane integration", "Foundry deployment scripts", "genesis allocations", or wants to understand how base fees are redirected and bridged.
3+
---
4+
5+
# Contracts Onboarding
6+
7+
## Overview
8+
9+
The contracts live in `contracts/` and use Foundry for development. There are two main contracts:
10+
11+
1. **AdminProxy** (`src/AdminProxy.sol`) - Bootstrap contract for admin addresses at genesis
12+
2. **FeeVault** (`src/FeeVault.sol`) - Collects base fees, bridges to Celestia via Hyperlane (cross-chain messaging protocol)
13+
14+
## Key Files
15+
16+
### Contract Sources
17+
- `contracts/src/AdminProxy.sol` - Transparent proxy pattern for admin control
18+
- `contracts/src/FeeVault.sol` - Fee collection and bridging logic
19+
20+
### Deployment Scripts
21+
- `contracts/script/DeployFeeVault.s.sol` - FeeVault deployment with CREATE2
22+
- `contracts/script/GenerateAdminProxyAlloc.s.sol` - Admin proxy allocation for genesis
23+
- `contracts/script/GenerateFeeVaultAlloc.s.sol` - Fee vault allocation for genesis
24+
25+
### Tests
26+
- `contracts/test/AdminProxy.t.sol` - AdminProxy test suite
27+
- `contracts/test/FeeVault.t.sol` - FeeVault test suite
28+
29+
## Architecture
30+
31+
### AdminProxy
32+
The AdminProxy contract provides a bootstrap mechanism for setting admin addresses at genesis. It uses a transparent proxy pattern allowing upgrades.
33+
34+
### FeeVault
35+
The FeeVault serves as the destination for redirected base fees (instead of burning them). Key responsibilities:
36+
- Receive base fees from block production
37+
- Bridge accumulated fees to Celestia via Hyperlane
38+
- Manage withdrawal permissions
39+
40+
## Connection to Rust Code
41+
42+
The contracts integrate with ev-reth through:
43+
1. **Base Fee Redirect** - `crates/ev-revm/src/base_fee.rs` redirects fees to the configured sink address
44+
2. **Chainspec Config** - `crates/node/src/config.rs` defines `base_fee_sink` field for the fee recipient address
45+
3. **Genesis Allocation** - Scripts generate allocations included in chainspec
46+
47+
## Development Commands
48+
49+
```bash
50+
cd contracts
51+
52+
# Build contracts
53+
forge build
54+
55+
# Run tests
56+
forge test
57+
58+
# Run specific test
59+
forge test --match-test testFeeCollection
60+
61+
# Generate allocations
62+
forge script script/GenerateFeeVaultAlloc.s.sol
63+
```
64+
65+
## Exploration Starting Points
66+
67+
1. Read `contracts/src/FeeVault.sol` for fee handling logic
68+
2. Read `contracts/src/AdminProxy.sol` for admin patterns
69+
3. Check `contracts/script/` for deployment patterns
70+
4. See how `crates/ev-revm/src/base_fee.rs` interacts with the sink address

‎.claude/skills/ev-reth-core.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
description: This skill should be used when learning ev-reth core node architecture, understanding how payload building works, or getting started with the codebase. Use when the user asks "how does ev-reth work", "explain the architecture", "where is the payload builder", "how are transactions submitted", "what is EvolveNode", "show me the node composition", or wants to understand Engine API integration.
3+
---
4+
5+
# Core Node Architecture Onboarding
6+
7+
## Overview
8+
9+
The core node logic lives in `crates/node/` and `bin/ev-reth/`. This is where ev-reth extends Reth to work with Evolve's transaction submission model.
10+
11+
## Key Files
12+
13+
### Entry Point
14+
- `bin/ev-reth/src/main.rs` - Node binary, initializes tracing, extends RPC
15+
16+
### Node Composition
17+
- `crates/node/src/node.rs` - `EvolveNode` unit struct with trait implementations
18+
- `crates/node/src/lib.rs` - Public API exports
19+
20+
### Payload Building
21+
- `crates/node/src/builder.rs` - `EvolvePayloadBuilder` - executes transactions, builds blocks
22+
- `crates/node/src/payload_service.rs` - Integrates builder with Reth's payload service
23+
- `crates/node/src/attributes.rs` - `EvolveEnginePayloadBuilderAttributes`
24+
25+
### Validation
26+
- `crates/node/src/validator.rs` - `EvolveEngineValidator` - custom block validation
27+
28+
### Configuration
29+
- `crates/node/src/config.rs` - `EvolvePayloadBuilderConfig`, parses chainspec extras
30+
- `crates/node/src/chainspec.rs` - `EvolveChainSpecParser` with EIP-1559 config parsing
31+
- `crates/node/src/args.rs` - CLI argument handling
32+
- `crates/node/src/error.rs` - Error types
33+
34+
### Execution
35+
- `crates/node/src/executor.rs` - EVM config and executor wiring
36+
37+
## Architecture
38+
39+
### Transaction Flow (Key Innovation)
40+
41+
Unlike standard Ethereum, ev-reth accepts transactions directly through Engine API:
42+
43+
```
44+
engine_forkchoiceUpdatedV3 (with transactions in payload attributes)
45+
↓
46+
EvolveEnginePayloadBuilderAttributes (decodes transactions)
47+
↓
48+
EvolvePayloadBuilder.build_payload()
49+
↓
50+
Execute transactions against current state
51+
↓
52+
Sealed block returned via engine_getPayloadV3
53+
```
54+
55+
### Node Composition Pattern
56+
57+
`EvolveNode` is a unit struct that implements `NodeTypes` and `Node<N>` traits:
58+
59+
```rust
60+
pub struct EvolveNode;
61+
62+
impl NodeTypes for EvolveNode {
63+
type Primitives = EthPrimitives;
64+
type ChainSpec = ChainSpec;
65+
type StateCommitment = MerklePatriciaTrie;
66+
type Storage = EthStorage;
67+
type Payload = EthEngineTypes;
68+
}
69+
```
70+
71+
The composition happens via trait implementations, connecting:
72+
- `EvolveEngineTypes` for custom payload types
73+
- `EvolveEngineValidator` for relaxed validation
74+
- `EvolvePayloadBuilderBuilder` for custom block building
75+
- `EvolveConsensusBuilder` from `evolve_ev_reth::consensus`
76+
77+
### Validator Customizations
78+
79+
`EvolveEngineValidator` bypasses certain checks for Evolve compatibility:
80+
- Block hash validation bypassed (Evolve uses prev block's apphash)
81+
- Equal timestamp blocks allowed
82+
- Custom gas limits per payload supported
83+
84+
### Chainspec Extensions
85+
86+
The chainspec parser supports Evolve-specific extras via `EvolveEip1559Config`:
87+
- EIP-1559 custom parameters (base fee settings)
88+
- Additional fields parsed from `evolve` key in chainspec extras
89+
90+
## Key Design Decisions
91+
92+
1. **No Mempool** - Transactions submitted directly via Engine API
93+
2. **Relaxed Validation** - Block hashes not validated (Evolve-specific)
94+
3. **Configurable Gas Limits** - Per-payload gas limits supported
95+
4. **Modular Builder** - Separates concerns between general and Evolve-specific logic
96+
97+
## Development Commands
98+
99+
```bash
100+
make build # Release build
101+
make run-dev # Run with debug logs
102+
make test-node # Test node crate
103+
```
104+
105+
## Exploration Starting Points
106+
107+
1. Start with `bin/ev-reth/src/main.rs` for entry point
108+
2. Read `crates/node/src/node.rs` for component composition
109+
3. Read `crates/node/src/builder.rs` for payload building (this is the heart)
110+
4. Check `crates/node/src/validator.rs` for validation customizations
111+
5. See `crates/node/src/chainspec.rs` for config parsing

‎.claude/skills/ev-reth-evm.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
description: This skill should be used when the user asks about "EVM customizations", "base fee redirect", "fee sink", "mint precompile", "native token minting", "contract size limit", "EvEvmFactory", "EvHandler", or wants to understand how ev-reth modifies EVM execution behavior.
3+
---
4+
5+
# EVM Customizations Onboarding
6+
7+
## Overview
8+
9+
EVM customizations live in `crates/ev-revm/` and `crates/ev-precompiles/`. These modify how the EVM executes transactions.
10+
11+
## Key Files
12+
13+
### EVM Factory
14+
- `crates/ev-revm/src/factory.rs` - `EvEvmFactory` wraps `EthEvmFactory`
15+
- `crates/ev-revm/src/evm.rs` - `EvEvm`, `DefaultEvEvm` implementations
16+
- `crates/ev-revm/src/config.rs` - EVM configuration structs
17+
18+
### Handlers
19+
- `crates/ev-revm/src/handler.rs` - `EvHandler` for execution handling
20+
- `crates/ev-revm/src/base_fee.rs` - `BaseFeeRedirect` logic
21+
22+
### Precompiles
23+
- `crates/ev-precompiles/src/mint.rs` - `MintPrecompile` at address 0xF100
24+
25+
### Shared
26+
- `crates/common/src/constants.rs` - Shared constants
27+
28+
## Architecture
29+
30+
### EvEvmFactory
31+
32+
Wraps Reth's `EthEvmFactory` to inject custom behavior. See `crates/ev-revm/src/factory.rs:103-108`:
33+
34+
```rust
35+
pub struct EvEvmFactory<F> {
36+
inner: F,
37+
redirect: Option<BaseFeeRedirectSettings>,
38+
mint_precompile: Option<MintPrecompileSettings>,
39+
contract_size_limit: Option<ContractSizeLimitSettings>,
40+
}
41+
```
42+
43+
### Base Fee Redirect
44+
45+
Instead of burning base fees, redirects them to a configurable address. See `crates/ev-revm/src/factory.rs:27-49`:
46+
47+
```rust
48+
pub struct BaseFeeRedirectSettings {
49+
redirect: BaseFeeRedirect, // Contains fee_sink address
50+
activation_height: u64, // When redirect activates
51+
}
52+
```
53+
54+
The `EvHandler` overrides `reward_beneficiary` (in `handler.rs:126-141`) to credit the sink address with base fees before paying the standard tip to the block producer.
55+
56+
### Mint Precompile (0xF100)
57+
58+
Custom precompile for native token minting/burning at address `0xF100`. See `crates/ev-precompiles/src/mint.rs`.
59+
60+
**INativeToken Interface** (5 functions):
61+
```solidity
62+
interface INativeToken {
63+
function mint(address to, uint256 amount) external;
64+
function burn(address from, uint256 amount) external;
65+
function addToAllowList(address account) external;
66+
function removeFromAllowList(address account) external;
67+
function allowlist(address account) external view returns (bool);
68+
}
69+
```
70+
71+
Settings in `crates/ev-revm/src/factory.rs:52-74`:
72+
```rust
73+
pub struct MintPrecompileSettings {
74+
admin: Address, // Who can mint/burn and manage allowlist
75+
activation_height: u64, // When precompile activates
76+
}
77+
```
78+
79+
### Contract Size Limits
80+
81+
Override EIP-170 default (24KB) contract size limit. See `crates/ev-revm/src/factory.rs:77-99`:
82+
83+
```rust
84+
pub struct ContractSizeLimitSettings {
85+
limit: usize, // Custom limit in bytes
86+
activation_height: u64, // When limit changes
87+
}
88+
```
89+
90+
## Configuration Flow
91+
92+
1. Chainspec defines settings in `extras` field
93+
2. `EvolveChainSpecParser` parses into config structs
94+
3. `EvEvmFactory` receives settings at construction
95+
4. Settings applied during EVM execution based on block height
96+
97+
## Key Design Decisions
98+
99+
1. **Configurable Activation** - All features have activation heights for upgrades
100+
2. **Wrapper Pattern** - `EvEvmFactory` wraps standard factory, minimizing changes
101+
3. **Admin Control** - Mint precompile requires admin authorization (or allowlist)
102+
4. **Fee Preservation** - Base fees collected rather than burned (for bridging)
103+
104+
## Development Commands
105+
106+
```bash
107+
cargo test -p ev-revm # Test EVM crate
108+
cargo test -p ev-precompiles # Test precompiles
109+
```
110+
111+
## Exploration Starting Points
112+
113+
1. Start with `crates/ev-revm/src/factory.rs` for the wrapper pattern
114+
2. Read `crates/ev-revm/src/handler.rs:126-141` for `reward_beneficiary` override
115+
3. Read `crates/ev-precompiles/src/mint.rs` for precompile implementation
116+
4. Check `crates/ev-revm/src/base_fee.rs` for redirect logic
117+
5. See `crates/node/src/config.rs` for how settings are configured

0 commit comments

Comments
 (0)