diff --git a/CLAUDE.md b/CLAUDE.md index 5e40a1b76a..2455f5c586 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,24 +4,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Build Commands - Build workspace: `just b` or `just build-native` +- Build rollup node: `just build-node` +- Build supervisor: `just build-supervisor` - Lint: `just l` or `just lint-native` +- Lint all targets (native, cannon, asterisc): `just lint-all` - Format: `just f` or `just fmt-native-fix` - Run all tests: `just t` or `just tests` - Run specific test: `cargo nextest run --package [package-name] --test [test-name]` - Run single test: `cargo nextest run --package [package-name] --test [test-name] -- [test_function_name]` -- Documentation: `just test-docs` +- Run online tests (excluded by default): `just test-online` +- Documentation tests: `just test-docs` +- Check spelling: `just lint-typos` (requires `typos-cli`) +- Feature powerset check: `just hack` (requires `cargo-hack`) ## Code Style - MSRV: 1.88 - Format with nightly rustfmt: `cargo +nightly fmt` -- Imports: organized by crate, reordered automatically -- Error handling: use proper error types, prefer `Result` over panics -- Naming: follow Rust conventions (snake_case for variables/functions, CamelCase for types) -- Prefer type-safe APIs and strong typing -- Documentation: rustdoc for public APIs, clear comments for complex logic -- Tests: write unit and integration tests for all functionality -- Performance: be mindful of allocations and copying, prefer references where appropriate -- No warnings policy: all clippy warnings are treated as errors (-D warnings) +- All clippy warnings are treated as errors (-D warnings) +- Imports: organized by crate, reordered automatically (`imports_granularity = "Crate"`) ## Architecture Overview @@ -39,7 +39,6 @@ Kona is a monorepo for OP Stack types, components, and services built in Rust. T - **`genesis`**: Genesis types for OP Stack chains - **`interop`**: Core functionality for OP Stack Interop features - **`registry`**: Rust bindings for superchain-registry -- **`comp`**: Compression types and utilities - **`hardforks`**: Consensus layer hardfork types and network upgrade transactions ### Proof (`crates/proof/`) @@ -55,39 +54,52 @@ Kona is a monorepo for OP Stack types, components, and services built in Rust. T - **`service`**: OP Stack rollup node service implementation - **`engine`**: Extensible rollup node engine client - **`rpc`**: OP Stack RPC types and extensions -- **`p2p`**: P2P networking including Gossip and Discovery +- **`gossip`**: P2P Gossip networking +- **`disc`**: P2P Discovery networking +- **`peers`**: Networking utilities ported from reth - **`sources`**: Data source types and utilities ### Supervisor (`crates/supervisor/`) - **`core`**: Core supervisor functionality - **`service`**: Supervisor service implementation - **`rpc`**: Supervisor RPC types and client -- **`storage`**: Database storage layer +- **`storage`**: Database storage layer (uses reth-db) - **`types`**: Common types for supervisor components -### Development Workflow - -1. **Testing**: The project uses `nextest` for test execution. Online tests are excluded by default and can be run separately with `just test-online` -2. **Cross-compilation**: Docker-based builds for `cannon` (MIPS) and `asterisc` (RISC-V) targets -3. **Documentation**: Both rustdoc and a separate documentation site at rollup.yoga -4. **Monorepo Integration**: Pins and integrates with the Optimism monorepo for action tests - -### Key Configuration Files -- `rust-toolchain.toml`: Pins Rust version to 1.88 -- `rustfmt.toml`: Custom formatting configuration with crate-level import grouping -- `clippy.toml`: MSRV configuration for clippy -- `deny.toml`: Dependency auditing and license compliance -- `release.toml`: Configuration for `cargo-release` tool - -### Target Architecture Support -- Native development on standard platforms -- Cross-compilation support for fault proof VMs: - - MIPS64 (cannon target) - - RISC-V (asterisc target) -- `no_std` compatibility for proof components - -### Dependencies and Features -- Heavy use of Alloy ecosystem for Ethereum types -- OP-specific extensions via op-alloy -- Modular feature flags for different compilation targets -- Workspace-level dependency management with version pinning +### Batcher (`crates/batcher/`) +- **`comp`**: Compression types and utilities for the OP Stack + +### Providers (`crates/providers/`) +- **`providers-alloy`**: Provider implementations backed by Alloy +- **`providers-local`**: Local provider implementations + +### Utilities (`crates/utilities/`) +- **`cli`**: Standard CLI utilities used across binaries +- **`serde`**: Serialization helpers +- **`macros`**: Utility macros + +## Cross-Compilation Targets + +The proof components support `no_std` and can be cross-compiled for fault proof VMs: +- **cannon**: MIPS64 target - `just build-cannon-client` +- **asterisc**: RISC-V target - `just build-asterisc-client` + +Linting for these targets requires Docker: +- `just lint-cannon` +- `just lint-asterisc` + +## E2E and Acceptance Tests + +Tests are located in `tests/` directory with its own justfile: +- Action tests for single-chain: `just action-tests-single` +- Action tests for interop: `just action-tests-interop` +- E2E tests with sysgo orchestrator: `just test-e2e-sysgo` +- Acceptance tests: `just acceptance-tests` + +These require building client binaries and setting up the Optimism monorepo submodule. + +## Key Dependencies +- **Alloy ecosystem**: Ethereum types and providers +- **op-alloy**: OP Stack extensions to Alloy +- **revm/op-revm**: EVM execution +- **reth**: Database types (for supervisor storage) diff --git a/docs/docs/pages/node/design/intro.mdx b/docs/docs/pages/node/design/intro.mdx index d549fd0ff2..52e899e3d1 100644 --- a/docs/docs/pages/node/design/intro.mdx +++ b/docs/docs/pages/node/design/intro.mdx @@ -42,15 +42,11 @@ but are currently defined as follows. node. The P2P stack consists of `discv5` peer discovery and block gossip through libp2p. Visit the [network][p2p] docs for more detail. -- **Supervisor Actor (beta)**: The supervisor actor is an - interop feature that allows the `kona-node` to be - "managed" (or "indexed") by the supervisor - a new - component in the OP Stack. A detailed overview of - interop and the supervisor's role is provided in the - [supervisor][supervisor] docs. -- **Runtime Actor**: Loads runtime values from the contracts - on the L1 chain for the OP Stack. This is a very - light-weight actor described in [runtime][runtime] docs. +- **L1 Watcher Actor**: Watches the L1 chain for new blocks + and system config updates. This lightweight actor polls + the L1 RPC for head and finalized block updates, forwards + them to other actors, and processes system config log + events (such as unsafe block signer updates). - **Sequencer Actor**: The sequencer actor extends the `kona-node` to be run as a sequencer. Sequencing is periphery to the basic rollup node operation. See @@ -65,8 +61,6 @@ but are currently defined as follows. [p2p]: ./p2p [engine]: ./engine [derivation]: ./derivation -[supervisor]: #TODO -[runtime]: #TODO [sequencer]: ./sequencer [specs]: https://specs.optimism.io/protocol/rollup-node.html diff --git a/docs/docs/pages/node/design/p2p.mdx b/docs/docs/pages/node/design/p2p.mdx index 52d3ed1938..6f83f8662d 100644 --- a/docs/docs/pages/node/design/p2p.mdx +++ b/docs/docs/pages/node/design/p2p.mdx @@ -146,12 +146,51 @@ As of writing these docs, block validation follows a few rules. ### Node Identification -TODO +Peers on the OP Stack P2P network are identified using Ethereum Node +Records (ENRs). Each ENR contains an `opstack` key that encodes the +chain ID and version, allowing nodes to verify they are connecting +to peers on the same network. + +The [`OpStackEnr`][opstack-enr] type represents this OP Stack-specific +ENR data. It contains: +- **Chain ID**: The L2 chain identifier (e.g., 10 for OP Mainnet, 8453 for Base) +- **Version**: Always set to 0 for the current protocol version + +When peers are discovered via discv5, their ENRs are validated using +[`EnrValidation`][enr-validation] before establishing a connection. +Validation checks that: +- The ENR contains the required `opstack` key +- The chain ID matches the expected network +- The version is valid (currently must be 0) + +Peers with invalid or mismatched ENRs are rejected, ensuring nodes +only connect to peers participating in the correct network. ### P2P Actor -TODO +The [`NetworkActor`][network-actor] orchestrates the P2P networking +layer for the rollup node. It wraps the [`NetworkBuilder`][network-builder] +and manages communication between the P2P stack and other node actors. + +The network actor handles several responsibilities: +- **Unsafe block signer updates**: Receives signer address updates from + the L1 watcher and configures block signature validation accordingly +- **P2P RPC requests**: Processes peer information queries from the RPC layer +- **Admin RPC requests**: Handles administrative network operations +- **Block publishing**: Receives execution payloads from the sequencer + actor and publishes them to the gossip network + +When started, the network actor builds the discovery and gossip drivers, +then enters its main loop where it: +1. Polls the gossip driver for incoming blocks and network events +2. Processes inbound requests from other actors +3. Handles peer management based on discovery events + +[network-actor]: https://github.com/op-rs/kona/blob/main/crates/node/service/src/actors/network/actor.rs +[network-builder]: https://github.com/op-rs/kona/blob/main/crates/node/service/src/actors/network/builder.rs +[opstack-enr]: https://docs.rs/kona-p2p-peers/latest/kona_p2p_peers/struct.OpStackEnr.html +[enr-validation]: https://docs.rs/kona-p2p-peers/latest/kona_p2p_peers/enum.EnrValidation.html @@ -169,7 +208,7 @@ TODO [discv5-service]: https://docs.rs/discv5/latest/discv5/struct.Discv5.html -[driver]: https://docs.rs/kona-p2p/latest/kona_p2p/struct.Discv5Driver.html +[driver]: https://docs.rs/kona-disc/latest/kona_disc/struct.Discv5Driver.html [discv5]: https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md [libp2p]: https://libp2p.io/ diff --git a/docs/docs/pages/sdk/overview.mdx b/docs/docs/pages/sdk/overview.mdx index f62a6db7c8..b8adbaddef 100644 --- a/docs/docs/pages/sdk/overview.mdx +++ b/docs/docs/pages/sdk/overview.mdx @@ -34,7 +34,7 @@ To use Kona as a library, add the relevant crates to your `Cargo.toml`: [dependencies] kona-derive = "0.1" kona-protocol = "0.1" -kona-node = "0.1" +kona-node-service = "0.1" ``` ## Examples diff --git a/docs/docs/pages/sdk/protocol/registry.mdx b/docs/docs/pages/sdk/protocol/registry.mdx index e355197523..cf1ebf8c8f 100644 --- a/docs/docs/pages/sdk/protocol/registry.mdx +++ b/docs/docs/pages/sdk/protocol/registry.mdx @@ -60,7 +60,6 @@ println!("OP Mainnet Chain Config: {:?}", op_chain_config); [op-superchain]: https://docs.optimism.io/stack/explainer [osr]: https://github.com/ethereum-optimism/superchain-registry -[s]: #TODO [sc]: https://crates.io/crates/kona-registry [g]: https://crates.io/crates/kona-genesis diff --git a/docs/sidebar.ts b/docs/sidebar.ts index 54a107226a..6ccf6d5dee 100644 --- a/docs/sidebar.ts +++ b/docs/sidebar.ts @@ -79,7 +79,6 @@ export const sidebar: SidebarItem[] = [ ] }, { text: "Configuration", link: "/node/configuration" }, - { text: "Kurtosis Integration", link: "/kurtosis/overview" }, { text: "Monitoring", link: "/node/monitoring" }, { text: "Subcommands", link: "/node/subcommands" }, { @@ -186,8 +185,7 @@ export const sidebar: SidebarItem[] = [ { text: "Create a new L1BlockInfoTx Hardfork Variant", link: "/sdk/examples/new-l1-block-info-tx-hardfork" }, { text: "Create a new kona-executor test fixture", link: "/sdk/examples/executor-test-fixtures" }, { text: "Configuring P2P Network Peer Scoring", link: "/sdk/examples/p2p-peer-scoring" }, - { text: "Custom Derivation Pipeline with New Stage", link: "/sdk/examples/custom-derivation-pipeline" }, - { text: "Testing Kona Sequencing with Kurtosis", link: "/sdk/examples/kurtosis-sequencing-test" } + { text: "Custom Derivation Pipeline with New Stage", link: "/sdk/examples/custom-derivation-pipeline" } ] } ] diff --git a/docs/vocs.config.ts b/docs/vocs.config.ts index 0338924d97..c20c2a7814 100644 --- a/docs/vocs.config.ts +++ b/docs/vocs.config.ts @@ -11,7 +11,7 @@ export default defineConfig({ topNav: [ { text: 'Run', link: '/node/run/overview' }, { text: 'SDK', link: '/sdk/overview' }, - { text: 'Rustdocs', link: 'https://docs.rs/kona-node/latest/' }, + { text: 'Rustdocs', link: 'https://docs.rs/kona-node-service/latest/' }, { text: 'GitHub', link: 'https://github.com/op-rs/kona' }, { text: 'v0.1.0',