diff --git a/README.md b/README.md index 451ed75..4c0bd6c 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,9 @@ Summit is a high-performance consensus client designed to drive EVM-based blockc - **Responsive Consensus**: Powered by the [Simplex consensus protocol](https://eprint.iacr.org/2023/463), enabling sub-second block times - **High Throughput**: Significantly higher TPS than Ethereum - **EVM Compatible**: Works with any execution client supporting the Engine API -- **BLS12-381 Cryptography**: Secure validator key management +- **BLS12-381 & Ed25519 Cryptography**: Secure validator key management - **Built with Commonware**: Leverages primitives from the [Commonware library](https://commonware.xyz) +- **Dynamic Validator Set**: Supports validator deposits (EIP-6110) and withdrawals (EIP-7002) Summit uses the Simplex protocol, a responsive consensus mechanism that adapts to network conditions rather than waiting for predetermined timeouts. This allows the network to move as fast as conditions permit, achieving sub-second block times in most cases. @@ -85,9 +86,6 @@ Summit acts as the consensus layer, communicating with EVM execution clients thr - Network communication ## Next steps / Future Roadmap -- Dynamic Validator sets and staking through the Ethereum staking contract - - Currently Summit just uses a static validator set at Genesis - - We will leverage EVMs staking contract and add and remove validators in a similar fashion as Ethereum - Deeper benchmarks - More optimizations (potentially DKG threshold signatures to improve throughput) - Full Audit and completeness Q4 2025 diff --git a/docs/actor-system.md b/docs/actor-system.md index 75da1f5..4077182 100644 --- a/docs/actor-system.md +++ b/docs/actor-system.md @@ -30,6 +30,16 @@ Summit's architecture follows the actor model with these key principles: ### 1. Application Actor (`application/src/actor.rs`) +**Purpose**: Handles block production, validation, and finalization + +**Key Responsibilities:** +- Propose blocks when selected as leader +- Validate blocks received from network +- Coordinate with execution client via Engine API +- Maintain block cache for pending/finalized blocks + +### 2. Finalizer Actor (`finalizer/src/actor.rs`) + **Purpose**: Manages consensus state, validator set, and staking logic **Key Responsibilities:** @@ -39,17 +49,6 @@ Summit's architecture follows the actor model with these key principles: - Handle withdrawal processing - Create and verify checkpoints -### 2. Finalizer Actor (`finalizer/src/actor.rs`) - -**Purpose**: Handles block production, validation, and finalization - -**Key Responsibilities:** -- Propose blocks when selected as leader -- Validate blocks received from network -- Coordinate with execution client via Engine API -- Process consensus finalization messages -- Maintain block cache for pending/finalized blocks - ### 3. Syncer Actor (`syncer/src/actor.rs`) **Purpose**: Manages block synchronization, caching, and network state @@ -60,17 +59,17 @@ Summit's architecture follows the actor model with these key principles: - Broadcast verified blocks to peers - Maintain local block cache - Coordinate synchronization with peers +- Push notarized and finalized blocks to the Finalizer Actor ### 4. Orchestrator Actor (`orchestrator/src/actor.rs`) **Purpose**: Coordinates consensus protocol execution and activity management **Key Responsibilities:** -- Execute Simplex consensus protocol -- Coordinate consensus rounds and view changes -- Broadcast and receive consensus activities -- Manage consensus timeouts -- Interface with Commonware consensus primitives +- Epoch transition management +- Simplex engine lifecycle management +- Network channel multiplexing +- Epoch boundary block synchronization ## Actor Supervision and Error Handling diff --git a/docs/architecture.md b/docs/architecture.md index 012c969..c1a9193 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -5,33 +5,146 @@ Summit is a modular consensus client implementing the Simplex protocol for EVM-based blockchains. It follows an actor-based architecture with clear separation of concerns between consensus, execution, networking, and storage. ``` -┌─────────────────────────────────────────────────────────────┐ -│ Summit Consensus Client │ -├─────────────────────────────────────────────────────────────┤ -│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │ -│ │ RPC Server │ │ Orchestrator │ │ Application │ │ -│ │ (External │ │ (Consensus │ │ (State Management) │ │ -│ │ API) │ │ Coordination)│ │ │ │ -│ └─────────────┘ └──────────────┘ └─────────────────────┘ │ -│ │ │ │ │ -│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │ -│ │ Syncer │ │ Finalizer │ │ Buffer/Broadcast │ │ -│ │ (Block Sync │ │ (Block Prod. │ │ (Network Buffering) │ │ -│ │ & Valid'n) │ │ & Finality) │ │ │ │ -│ └─────────────┘ └──────────────┘ └─────────────────────┘ │ -│ │ │ │ │ -│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │ -│ │ Storage │ │ Engine Client│ │ P2P Network │ │ -│ │ (Consensus │ │ (Execution │ │ (Validator Comm.) │ │ -│ │ State) │ │ Interface) │ │ │ │ -│ └─────────────┘ └──────────────┘ └─────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - │ - ┌──────────────┐ - │ Reth/Geth │ - │ (Execution │ - │ Client) │ - └──────────────┘ + ┌─────────────────────────────────────────────────────────────────────────────────┐ + │ ORCHESTRATOR │ + │ │ + │ • Epoch transition management │ + │ • Simplex engine lifecycle management │ + │ • Network channel multiplexing │ + │ • Epoch boundary block synchronization │ + │ │ + │ orchestrator/src/actor.rs │ + └────────────┬────────────────────────────────────────────────────────────────────┘ + │ + │ spawn/abort engines per epoch + │ + ▼ + ┌──────────────────────────┐ + │ SIMPLEX CONSENSUS │ + │ (commonware_consensus) │ ┌──────────────────────┐ + │ │ │ FINALIZER │ + │ • Leader election │ │ (State Execution) │ + │ • View management │ │ │ + │ • Notarization (2/3+1) │ │ • Canonical state │ + │ • Finalization (3/3) │ │ • Fork states │ + │ • Reports consensus │ │ • Execute blocks │ + │ messages │ │ • Commit to engine │ + │ │ │ • Create checkpoints│ + │ External crate │ │ • Store headers │ + └────────┬─────────────────┘ │ │ + │ │ finalizer/src/ │ + │ Automaton trait │ actor.rs │ + │ Relay trait └──────────┬───────────┘ + │ │ + ▼ │ + ┌──────────────────────────┐ │ + │ APPLICATION │ │ + │ (Consensus Interface) │ │ + │ │ │ + │ • Propose(round, parent)│────────subscribe parent────────────────┤ + │ • Verify(round, payload)│────────notify_at_height────────────────┤ + │ • Broadcast(payload) │────────get_aux_data────────────────────┤ + │ │ │ + │ Implements: │ │ + │ - Automaton trait │ │ + │ - Relay trait │ │ + │ │ │ + │ application/src/actor.rs│ │ + └────────┬─────────────────┘ │ + │ │ + │ broadcast() │ + │ verified() │ + │ subscribe() │ + ▼ │ + ┌──────────────────────────┐ │ + │ SYNCER │ │ + │ (Coordination Hub) │ │ + │ │ │ + │ • Block cache │────────Update::NotarizedBlock──────────┤ + │ • Finalization archive │────────Update::FinalizedBlock──────────┤ + │ • Finalized blocks │────────Update::Tip─────────────────────┤ + │ • Resolver (backfill) │ │ + │ • Broadcast engine │ │ + │ • Subscription mgmt │ │ + │ │ │ + │ Messages: │ │ + │ - Broadcast │◄───────acknowledgement─────────────────┘ + │ - Verified │ + │ - Notarization │◄───────Simplex reports via + │ - Finalization │ Reporter trait + │ - Subscribe │ + │ - GetBlock │ + │ - GetFinalization │ + │ │ + │ syncer/src/actor.rs │ + └────────┬─────────────────┘ + │ + │ buffered broadcast + │ resolver requests + ▼ + ┌──────────────────────────┐ + │ NETWORK │ + │ │ + │ • Broadcast network │ + │ • P2P resolver │ + │ • Block propagation │ + │ │ + │ commonware_p2p │ + │ commonware_broadcast │ + └──────────────────────────┘ + + + ┌─────────────────────────────────────────────────────────────────────────────────┐ + │ EXTERNAL INTERFACES │ + └─────────────────────────────────────────────────────────────────────────────────┘ + + APPLICATION & FINALIZER + │ + │ start_building_block(forkchoice, timestamp, withdrawals) + │ get_payload(payload_id) + │ commit_hash(forkchoice) + ▼ + ┌──────────────────┐ + │ ENGINE CLIENT │ + │ │────────────────────────────────┐ + │ Interface to │ │ + │ Execution Layer │ ▼ + │ │ ┌─────────────────────────┐ + │ types/src/ │ │ ETHEREUM EXECUTION │ + │ engine_client.rs│ │ CLIENT (Reth, Geth) │ + └──────────────────┘ │ │ + │ • Block building │ + │ • State execution │ + │ • Forkchoice updates │ + └─────────────────────────┘ + + FINALIZER & SYNCER + │ + │ store_consensus_state() + │ get_consensus_state() + │ store_finalized_checkpoint() + │ store_finalized_header() + ▼ + ┌──────────────────┐ + │ STORAGE │ + │ │ + │ commonware_ │ + │ storage │ + │ │ + │ • ADB Store │ + │ (append-only) │ + │ • Consensus │ + │ state by │ + │ height │ + │ • Checkpoints │ + │ by epoch │ + │ • Finalized │ + │ headers │ + │ by height │ + │ │ + │ finalizer/src/ │ + │ db.rs │ + └──────────────────┘ ``` ## Core Components @@ -51,67 +164,64 @@ The central coordinator that orchestrates all components Handles block production, validation, and finalization with Reth **Key Responsibilities:** -- Block proposal when selected as leader -- Block validation from other validators -- Consensus finalization via Simplex protocol -- Execution client coordination (Engine API) +- Maintain current validator set and staking information +- Process validator additions/removals based on execution layer events +- Manage consensus state transitions +- Handle withdrawal processing +- Create and verify checkpoints ### 3. Syncer (`syncer/`) Manages block synchronization and network state **Key Responsibilities:** -- Block reception and validation -- Missing block resolution -- Network state synchronization -- Block propagation to peers +- Receive and cache blocks from network +- Resolve missing blocks through backfill +- Broadcast verified blocks to peers +- Maintain local block cache +- Coordinate synchronization with peers +- Push notarized and finalized blocks to the Finalizer Actor ### 4. Application (`application/`) Manages consensus state and validator set **Key Responsibilities:** -- Validator set management -- Consensus state transitions -- Checkpoint creation and verification -- Staking/unstaking logic +- Propose blocks when selected as leader +- Validate blocks received from network +- Coordinate with execution client via Engine API +- Maintain block cache for pending/finalized blocks ### 5. Orchestrator (`orchestrator/`) Coordinates consensus activities **Key Responsibilities:** -- Handles Simplex instances for each epoch -- Activity broadcast and reception -- Timeout management -- View change coordination +- Epoch transition management +- Simplex engine lifecycle management +- Network channel multiplexing +- Epoch boundary block synchronization ## Data Flow ### Block Production Flow 1. **Leader Selection**: Leader election is handled by the current Simplex instance -2. **Block Building**: Finalizer requests block from execution client via Engine API -3. **Block Proposal**: Finalizer broadcasts proposed block to network -4. **Block Validation**: Peer validators validate block via execution client -5. **Consensus**: Orchestrator coordinates consensus on proposed block -6. **Finalization**: Finalizer commits finalized block to execution client +2. **Block Building**: Application requests block from execution client via Engine API +3. **Block Proposal**: Application broadcasts proposed block to network +4. **Block Validation**: Application of peer validators validate block +5. **Optimistic Execution**: Syncer sends notarized blocks to the finalizer for optimistic execution +6. **Finalization**: Syncer sends finalized blocks to the finalizer for finalization -``` -Orchestrator → Finalizer → EngineClient → Reth → EngineClient → Finalizer → Network -``` ### Block Reception Flow 1. **Block Reception**: Syncer receives block from network 2. **Block Caching**: Block stored in cache for validation 3. **Block Validation**: Execution client validates block via Engine API -4. **Consensus Participation**: Orchestrator participates in consensus +5. **Optimistic Execution**: Finalizer optimistically executes notarized block 5. **Block Finalization**: Finalizer applies finalized block -``` -Network → Syncer → Cache → EngineClient → Reth → EngineClient → Orchestrator → Finalizer -``` ### Synchronization Flow @@ -120,9 +230,6 @@ Network → Syncer → Cache → EngineClient → Reth → EngineClient → Orch 3. **Validation**: Each block validated via execution client 4. **State Application**: Validated blocks applied to consensus state -``` -Syncer → Resolver → Peers → EngineClient → Reth → Application → ConsensusState -``` ## Actor Communication diff --git a/docs/staking-and-participating.md b/docs/staking-and-participating.md index dc85587..2cff80c 100644 --- a/docs/staking-and-participating.md +++ b/docs/staking-and-participating.md @@ -4,7 +4,7 @@ Summit is a PoS(Proof of Stake) consensus client. In order to participate in the ## Staking Contract The staking contract is almost the same as ethereum's and the source code of the modified version is available here (https://github.com/SeismicSystems/seismic-contracts/blob/main/src/seismic-std-lib/DepositContract.sol) -The changes that were made were only to accomodate every consensus node needing 2 keys to participate instead of the 1 like on ethereum. A node needs a BL 12-381 key that is aggregeted with other consensus nodes as well as a ED25519 key that is used for authenticated networking messages and is much faster verify. The changes add these keys to the deposit function and as well as to the deposit event. Other than that our validator deposit flow is exactly as it is in Ethereum and for more information on how that works see (https://docs.beaconcha.in/faqs/deposit-process) +The changes that were made were only to accommodate every consensus node needing 2 keys to participate instead of the 1 like on ethereum. A node needs a BL 12-381 key that is aggregeted with other consensus nodes as well as a ED25519 key that is used for authenticated networking messages and is much faster verify. The changes add these keys to the deposit function and as well as to the deposit event. Other than that our validator deposit flow is exactly as it is in Ethereum and for more information on how that works see (https://docs.beaconcha.in/faqs/deposit-process) ## Becoming a validator E2E