add additional details and style conventions from ajj example

Author: dylanlott

.claude/CLAUDE.md

@@ -1,10 +1,8 @@
-# CLAUDE.md
+# Signet Block Builder Development Guide
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+## Crate Summary
 
-## Project Overview
-
-Signet Block Builder - a Rust application that simulates transactions and bundles against rollup state to create valid Signet rollup blocks, then submits them to Ethereum as EIP-4844 blob transactions via Flashbots.
+Single-crate Rust application (not a workspace) that builds Signet rollup blocks. Actor-based async task system: watches host/rollup chains, ingests transactions and bundles, simulates them against rollup state, then submits valid blocks to Ethereum as EIP-4844 blob transactions via Flashbots. Built on alloy, trevm, tokio, and the `signet-*` SDK crates. Binary: `zenith-builder-example`. Minimum Rust 1.88, Edition 2024.
 
 ## Build Commands
 
@@ -17,43 +15,115 @@ make fmt          # Format code
 make clippy       # Lint with warnings denied
 ```
 
-Equivalent cargo commands work directly (`cargo build`, `cargo test`, etc.).
+Always lint before committing. The Makefile provides shortcuts (`make fmt`, `make clippy`, `make test`)
 
 ## Architecture
 
-The builder uses an actor-based async task system with five main tasks communicating via channels:
+Five actor tasks communicate via tokio channels:
+
+1. **EnvTask** (`src/tasks/env.rs`) - Subscribes to rollup blocks, fetches matching host headers, runs Quincey preflight slot check, constructs `SimEnv` (host + rollup `BlockEnv`), broadcasts via `watch` channel.
+2. **CacheTasks** (`src/tasks/cache/`) - `TxPoller` and `BundlePoller` ingest transactions/bundles into a shared `SimCache`.
+3. **SimulatorTask** (`src/tasks/block/sim.rs`) - Receives `SimEnv`, clones the cache, builds a `BlockBuild` with a slot-derived deadline, produces `SimResult`.
+4. **FlashbotsTask** (`src/tasks/submit/flashbots.rs`) - Receives `SimResult`, prepares signed EIP-4844 blob transaction via `SubmitPrep` + Quincey, bundles with host txs, submits to Flashbots relay.
+5. **MetricsTask** (`src/tasks/metrics.rs`) - Tracks tx mining status and records metrics.
+
+**Data flow:** `EnvTask → (watch) → SimulatorTask ← (SimCache) ← CacheTasks` `SimulatorTask → (mpsc) → FlashbotsTask → Quincey → Flashbots`
+
+### Source Layout
+
+```
+bin/
+  builder.rs          - Binary entry point, spawns all tasks, select! on join handles
+src/
+  lib.rs              - Crate root, global CONFIG OnceLock, lint directives
+  config.rs           - BuilderConfig (FromEnv), provider type aliases, connect_* methods
+  quincey.rs          - Quincey enum (Remote/Owned), signing + preflight
+  service.rs          - Axum /healthcheck endpoint
+  macros.rs           - span_scoped!, span_debug/info/warn/error!, res/opt_unwrap_or_continue!
+  utils.rs            - Signature extraction, gas population helpers
+  test_utils.rs       - setup_test_config, new_signed_tx, test_block_env helpers
+  tasks/
+    mod.rs            - Module re-exports
+    env.rs            - EnvTask, SimEnv, Environment types
+    block/
+      mod.rs          - Module re-exports
+      sim.rs          - SimulatorTask, SimResult, block building + deadline calc
+      cfg.rs          - SignetCfgEnv for simulation
+    cache/
+      mod.rs          - Module re-exports
+      task.rs         - CacheTask
+      tx.rs           - TxPoller
+      bundle.rs       - BundlePoller
+      system.rs       - CacheSystem, CacheTasks orchestration
+    submit/
+      mod.rs          - Module re-exports
+      flashbots.rs    - FlashbotsTask, bundle preparation + submission
+      prep.rs         - SubmitPrep (tx preparation + Quincey signing), Bumpable
+      sim_err.rs      - SimErrorResp, SimRevertKind
+    metrics.rs        - MetricsTask
+```
+
+## Repo Conventions
+
+- Global static config: `CONFIG: OnceLock<BuilderConfig>` initialized via `config_from_env()`. Tasks access config via `crate::config()`.
+- Provider type aliases: `HostProvider`, `RuProvider`, `FlashbotsProvider`, `ZenithInstance` are defined in `config.rs` and used throughout.
+- `connect_*` methods on `BuilderConfig` use `OnceCell`/`OnceLock` for memoization -- providers and signers are connected once, then cloned.
+- Internal macros: `span_scoped!`, `span_debug/info/warn/error!` log within an unentered span. `res_unwrap_or_continue!` and `opt_unwrap_or_continue!` unwrap-or-log-and-continue in loops.
+- Quincey has two modes: `Remote` (HTTP/OAuth for production) and `Owned` (local/AWS KMS for dev). Configured by presence of `SEQUENCER_KEY` env var.
+- Tasks follow a `new() -> spawn()` pattern: `new()` connects providers, `spawn()` returns channel endpoints + `JoinHandle`.
+- Block simulation uses `trevm` with `concurrent-db` and `AlloyDB` backed by alloy providers.
+- EIP-4844 blob encoding uses `SimpleCoder` and the 7594 sidecar builder.
+
+## init4 Organization Style
+
+### Research
+
+- Prefer building crate docs (`cargo doc`) and reading them over grepping.
+
+### Code Style
+
+- Functional combinators over imperative control flow. No unnecessary nesting.
+- Terse Option/Result handling: `option.map(Thing::do_something)` or `let Some(a) = option else { return; };`.
+- Small, focused functions and types.
+- Never add incomplete code. No `TODO`s for core logic.
+- Never use glob imports. Group imports from the same crate. No blank lines between imports.
+- Visibility: private by default, `pub(crate)` for internal, `pub` for API. Never use `pub(super)`.
+
+### Error Handling
 
-1. **EnvTask** (`src/tasks/env.rs`) - Watches host/rollup blocks, maintains block environment state via watch channel
-2. **CacheTasks** (`src/tasks/cache/`) - TxPoller and BundlePoller ingest transactions/bundles into SimCache
-3. **SimulatorTask** (`src/tasks/block/sim.rs`) - Simulates txs/bundles against rollup state, builds blocks with 1.5s buffer deadline
-4. **FlashbotsTask** (`src/tasks/submit/flashbots.rs`) - Signs blocks via Quincey, submits to Flashbots relay
-5. **MetricsTask** (`src/tasks/metrics.rs`) - Tracks tx mining status and records metrics
+- `thiserror` for library errors. Never `anyhow`. `eyre` is allowed in this binary crate but not in library code.
+- Propagate with `?` and `map_err`.
 
-**Data flow:** EnvTask → (block_env) → SimulatorTask ← (SimCache) ← CacheTasks; SimulatorTask → (built block) → FlashbotsTask → Quincey → Flashbots
+### Tracing
 
-## Key Components
+- Use `tracing` crate. Instrument work items, not long-lived tasks.
+- `skip(self)` when instrumenting methods. Add only needed fields.
+- Levels: TRACE (rare, verbose), DEBUG (sparingly), INFO (default), WARN (potential issues), ERROR (prevents operation).
+- Propagate spans through task boundaries with `Instrument`.
+- This crate uses `span_scoped!` macros to log within unentered spans.
 
-- **Quincey** (`src/quincey.rs`): Block signing client - supports remote (HTTP/OAuth) or local (AWS KMS) signing
-- **BuilderConfig** (`src/config.rs`): Environment variable loading, provider connections
-- **Service** (`src/service.rs`): HTTP server with `/healthcheck` endpoint
+### Async
 
-## Dependencies
+- Tokio multi-thread runtime. No blocking in async functions.
+- Long-lived tasks: return a spawnable future via `spawn()`, don't run directly.
+- Short-lived spawned tasks: consider span propagation with `.instrument()`.
 
-Key external crates:
-- `signet-*`: SDK crates for constants, simulation, tx-cache, types, zenith contract
-- `alloy`: Ethereum interaction (providers, signers, EIP-4844)
-- `trevm`: EVM simulator with concurrent-db
-- `tokio`: Async runtime
+### Testing
 
-## Configuration
+- Tests panic, never return `Result`. Use `unwrap()` directly.
+- Use `setup_test_config()` from `test_utils` to initialize the global config.
+- Unit tests in `mod tests` at file bottom. Integration tests in `tests/`.
 
-Required environment variables: `HOST_RPC_URL`, `ROLLUP_RPC_URL`, `QUINCEY_URL`, `TX_POOL_URL`, `BUILDER_KEY`, `BUILDER_REWARDS_ADDRESS`, `BUILDER_PORT`, `BLOCK_QUERY_CUTOFF_BUFFER`, plus OAuth settings (`OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_AUTHENTICATE_URL`, `OAUTH_TOKEN_URL`, `AUTH_TOKEN_REFRESH_INTERVAL`).
+### Rustdoc
 
-Optional: `SEQUENCER_KEY` for local signing instead of remote Quincey, `CONCURRENCY_LIMIT` for parallel simulation threads.
+- Doc all public items. Include usage examples in rustdoc.
+- Hide scaffolding with `#`. Keep examples concise.
+- Traits must include an implementation guide.
 
-## Rust Version
+### GitHub
 
-Minimum: 1.88, Edition: 2024
+- Fresh branches off `main` for PRs. Descriptive branch names.
+- AI-authored GitHub comments must include `**[Claude Code]**` header.
 
 ## Local Development
 

.gitignore

@@ -24,4 +24,5 @@ target/
 .vscode/launch.json
 
 .claude/*.local.*
+.claude/settings.json
 CLAUDE.local.md