chore: add onboarding skill

.claude/skills/contracts.md

@@ -0,0 +1,70 @@
+---
+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.
+---
+
+# Contracts Onboarding
+
+## Overview
+
+The contracts live in `contracts/` and use Foundry for development. There are two main contracts:
+
+1. **AdminProxy** (`src/AdminProxy.sol`) - Bootstrap contract for admin addresses at genesis
+2. **FeeVault** (`src/FeeVault.sol`) - Collects base fees, bridges to Celestia via Hyperlane (cross-chain messaging protocol)
+
+## Key Files
+
+### Contract Sources
+- `contracts/src/AdminProxy.sol` - Transparent proxy pattern for admin control
+- `contracts/src/FeeVault.sol` - Fee collection and bridging logic
+
+### Deployment Scripts
+- `contracts/script/DeployFeeVault.s.sol` - FeeVault deployment with CREATE2
+- `contracts/script/GenerateAdminProxyAlloc.s.sol` - Admin proxy allocation for genesis
+- `contracts/script/GenerateFeeVaultAlloc.s.sol` - Fee vault allocation for genesis
+
+### Tests
+- `contracts/test/AdminProxy.t.sol` - AdminProxy test suite
+- `contracts/test/FeeVault.t.sol` - FeeVault test suite
+
+## Architecture
+
+### AdminProxy
+The AdminProxy contract provides a bootstrap mechanism for setting admin addresses at genesis. It uses a transparent proxy pattern allowing upgrades.
+
+### FeeVault
+The FeeVault serves as the destination for redirected base fees (instead of burning them). Key responsibilities:
+- Receive base fees from block production
+- Bridge accumulated fees to Celestia via Hyperlane
+- Manage withdrawal permissions
+
+## Connection to Rust Code
+
+The contracts integrate with ev-reth through:
+1. **Base Fee Redirect** - `crates/ev-revm/src/base_fee.rs` redirects fees to the configured sink address
+2. **Chainspec Config** - `crates/node/src/config.rs` defines `base_fee_sink` field for the fee recipient address
+3. **Genesis Allocation** - Scripts generate allocations included in chainspec
+
+## Development Commands
+
+```bash
+cd contracts
+
+# Build contracts
+forge build
+
+# Run tests
+forge test
+
+# Run specific test
+forge test --match-test testFeeCollection
+
+# Generate allocations
+forge script script/GenerateFeeVaultAlloc.s.sol
+```
+
+## Exploration Starting Points
+
+1. Read `contracts/src/FeeVault.sol` for fee handling logic
+2. Read `contracts/src/AdminProxy.sol` for admin patterns
+3. Check `contracts/script/` for deployment patterns
+4. See how `crates/ev-revm/src/base_fee.rs` interacts with the sink address

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

@@ -0,0 +1,111 @@
+---
+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.
+---
+
+# Core Node Architecture Onboarding
+
+## Overview
+
+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.
+
+## Key Files
+
+### Entry Point
+- `bin/ev-reth/src/main.rs` - Node binary, initializes tracing, extends RPC
+
+### Node Composition
+- `crates/node/src/node.rs` - `EvolveNode` unit struct with trait implementations
+- `crates/node/src/lib.rs` - Public API exports
+
+### Payload Building
+- `crates/node/src/builder.rs` - `EvolvePayloadBuilder` - executes transactions, builds blocks
+- `crates/node/src/payload_service.rs` - Integrates builder with Reth's payload service
+- `crates/node/src/attributes.rs` - `EvolveEnginePayloadBuilderAttributes`
+
+### Validation
+- `crates/node/src/validator.rs` - `EvolveEngineValidator` - custom block validation
+
+### Configuration
+- `crates/node/src/config.rs` - `EvolvePayloadBuilderConfig`, parses chainspec extras
+- `crates/node/src/chainspec.rs` - `EvolveChainSpecParser` with EIP-1559 config parsing
+- `crates/node/src/args.rs` - CLI argument handling
+- `crates/node/src/error.rs` - Error types
+
+### Execution
+- `crates/node/src/executor.rs` - EVM config and executor wiring
+
+## Architecture
+
+### Transaction Flow (Key Innovation)
+
+Unlike standard Ethereum, ev-reth accepts transactions directly through Engine API:
+
+```
+engine_forkchoiceUpdatedV3 (with transactions in payload attributes)
+    ↓
+EvolveEnginePayloadBuilderAttributes (decodes transactions)
+    ↓
+EvolvePayloadBuilder.build_payload()
+    ↓
+Execute transactions against current state
+    ↓
+Sealed block returned via engine_getPayloadV3
+```
+
+### Node Composition Pattern
+
+`EvolveNode` is a unit struct that implements `NodeTypes` and `Node<N>` traits:
+
+```rust
+pub struct EvolveNode;
+
+impl NodeTypes for EvolveNode {
+    type Primitives = EthPrimitives;
+    type ChainSpec = ChainSpec;
+    type StateCommitment = MerklePatriciaTrie;
+    type Storage = EthStorage;
+    type Payload = EthEngineTypes;
+}
+```
+
+The composition happens via trait implementations, connecting:
+- `EvolveEngineTypes` for custom payload types
+- `EvolveEngineValidator` for relaxed validation
+- `EvolvePayloadBuilderBuilder` for custom block building
+- `EvolveConsensusBuilder` from `evolve_ev_reth::consensus`
+
+### Validator Customizations
+
+`EvolveEngineValidator` bypasses certain checks for Evolve compatibility:
+- Block hash validation bypassed (Evolve uses prev block's apphash)
+- Equal timestamp blocks allowed
+- Custom gas limits per payload supported
+
+### Chainspec Extensions
+
+The chainspec parser supports Evolve-specific extras via `EvolveEip1559Config`:
+- EIP-1559 custom parameters (base fee settings)
+- Additional fields parsed from `evolve` key in chainspec extras
+
+## Key Design Decisions
+
+1. **No Mempool** - Transactions submitted directly via Engine API
+2. **Relaxed Validation** - Block hashes not validated (Evolve-specific)
+3. **Configurable Gas Limits** - Per-payload gas limits supported
+4. **Modular Builder** - Separates concerns between general and Evolve-specific logic
+
+## Development Commands
+
+```bash
+make build      # Release build
+make run-dev    # Run with debug logs
+make test-node  # Test node crate
+```
+
+## Exploration Starting Points
+
+1. Start with `bin/ev-reth/src/main.rs` for entry point
+2. Read `crates/node/src/node.rs` for component composition
+3. Read `crates/node/src/builder.rs` for payload building (this is the heart)
+4. Check `crates/node/src/validator.rs` for validation customizations
+5. See `crates/node/src/chainspec.rs` for config parsing

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

@@ -0,0 +1,117 @@
+---
+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.
+---
+
+# EVM Customizations Onboarding
+
+## Overview
+
+EVM customizations live in `crates/ev-revm/` and `crates/ev-precompiles/`. These modify how the EVM executes transactions.
+
+## Key Files
+
+### EVM Factory
+- `crates/ev-revm/src/factory.rs` - `EvEvmFactory` wraps `EthEvmFactory`
+- `crates/ev-revm/src/evm.rs` - `EvEvm`, `DefaultEvEvm` implementations
+- `crates/ev-revm/src/config.rs` - EVM configuration structs
+
+### Handlers
+- `crates/ev-revm/src/handler.rs` - `EvHandler` for execution handling
+- `crates/ev-revm/src/base_fee.rs` - `BaseFeeRedirect` logic
+
+### Precompiles
+- `crates/ev-precompiles/src/mint.rs` - `MintPrecompile` at address 0xF100
+
+### Shared
+- `crates/common/src/constants.rs` - Shared constants
+
+## Architecture
+
+### EvEvmFactory
+
+Wraps Reth's `EthEvmFactory` to inject custom behavior. See `crates/ev-revm/src/factory.rs:103-108`:
+
+```rust
+pub struct EvEvmFactory<F> {
+    inner: F,
+    redirect: Option<BaseFeeRedirectSettings>,
+    mint_precompile: Option<MintPrecompileSettings>,
+    contract_size_limit: Option<ContractSizeLimitSettings>,
+}
+```
+
+### Base Fee Redirect
+
+Instead of burning base fees, redirects them to a configurable address. See `crates/ev-revm/src/factory.rs:27-49`:
+
+```rust
+pub struct BaseFeeRedirectSettings {
+    redirect: BaseFeeRedirect,      // Contains fee_sink address
+    activation_height: u64,         // When redirect activates
+}
+```
+
+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.
+
+### Mint Precompile (0xF100)
+
+Custom precompile for native token minting/burning at address `0xF100`. See `crates/ev-precompiles/src/mint.rs`.
+
+**INativeToken Interface** (5 functions):
+```solidity
+interface INativeToken {
+    function mint(address to, uint256 amount) external;
+    function burn(address from, uint256 amount) external;
+    function addToAllowList(address account) external;
+    function removeFromAllowList(address account) external;
+    function allowlist(address account) external view returns (bool);
+}
+```
+
+Settings in `crates/ev-revm/src/factory.rs:52-74`:
+```rust
+pub struct MintPrecompileSettings {
+    admin: Address,             // Who can mint/burn and manage allowlist
+    activation_height: u64,     // When precompile activates
+}
+```
+
+### Contract Size Limits
+
+Override EIP-170 default (24KB) contract size limit. See `crates/ev-revm/src/factory.rs:77-99`:
+
+```rust
+pub struct ContractSizeLimitSettings {
+    limit: usize,               // Custom limit in bytes
+    activation_height: u64,     // When limit changes
+}
+```
+
+## Configuration Flow
+
+1. Chainspec defines settings in `extras` field
+2. `EvolveChainSpecParser` parses into config structs
+3. `EvEvmFactory` receives settings at construction
+4. Settings applied during EVM execution based on block height
+
+## Key Design Decisions
+
+1. **Configurable Activation** - All features have activation heights for upgrades
+2. **Wrapper Pattern** - `EvEvmFactory` wraps standard factory, minimizing changes
+3. **Admin Control** - Mint precompile requires admin authorization (or allowlist)
+4. **Fee Preservation** - Base fees collected rather than burned (for bridging)
+
+## Development Commands
+
+```bash
+cargo test -p ev-revm        # Test EVM crate
+cargo test -p ev-precompiles # Test precompiles
+```
+
+## Exploration Starting Points
+
+1. Start with `crates/ev-revm/src/factory.rs` for the wrapper pattern
+2. Read `crates/ev-revm/src/handler.rs:126-141` for `reward_beneficiary` override
+3. Read `crates/ev-precompiles/src/mint.rs` for precompile implementation
+4. Check `crates/ev-revm/src/base_fee.rs` for redirect logic
+5. See `crates/node/src/config.rs` for how settings are configured