docs: update docs (#166)

Author: matthias-wright

.codex

@@ -47,12 +47,12 @@ cargo build --release
 
 ### 1. Generate Validator Keys
 ```bash
-cargo run -- --key-path path/to/store/key keys generate
+cargo run -- keys generate --key-store-path /path/to/keys
 ```
 
 ### 2. View Your Public Key
 ```bash
-cargo run -- --key-path path/to/store/key keys show
+cargo run -- keys show --key-store-path /path/to/keys
 ```
 
 ### 3. Configure Genesis
@@ -61,10 +61,10 @@ Create a genesis file that references your EVM genesis configuration. See [examp
 ### 4. Start Your Validator
 Ensure your EVM client is running, then:
 ```bash
-cargo run -- \
-  --key-path /path/to/priv-key \
+cargo run -- run \
+  --key-store-path /path/to/keys \
   --store-path /storage/directory \
-  --engine-jwt-path /path/to/evm/jwt.hex \
+  --engine-ipc-path /tmp/reth_engine_api.ipc \
   --genesis-path /path/to/genesis.toml
 ```
 

README.md

@@ -135,12 +135,12 @@ Summit is a modular consensus client implementing the Simplex protocol for EVM-b
      │    (key-value)   │                                                                                             
      │  • Consensus     │                                                                                             
      │    state by      │                                                                                             
-     │    height        │                                                                                             
+     │    epoch         │                                                                                             
      │  • Checkpoints   │                                                                                             
      │    by epoch      │                                                                                             
      │  • Finalized     │                                                                                             
      │    headers       │                                                                                             
-     │    by height     │                                                                                             
+     │    by epoch      │                                                                                             
      │                  │                                                                                             
      │  finalizer/src/  │                                                                                             
      │  db.rs           │                                                                                             
@@ -276,4 +276,4 @@ Summit uses Commonware's storage primitives for persistent state
 - **Network Attacks**: Authenticated P2P prevents impersonation
 - **Consensus Attacks**: Simplex protocol handles Byzantine validators
 - **Execution Attacks**: Engine API isolation prevents direct EVM access
-- **Storage Attacks**: Cryptographic verification prevents tampering
+- **Storage Attacks**: Cryptographic verification prevents tampering

docs/architecture.md

@@ -98,14 +98,15 @@ When a node starts, it attempts to load the most recent checkpoint:
 
 ### Database Schema
 
-Checkpoints and headers are stored in separate column families:
+Checkpoints and headers are stored in a single QMDB store using prefixed keys and explicit tracker entries for the latest stored epoch:
 
-| Column Family | Key | Value |
-|---------------|-----|-------|
-| `checkpoints` | epoch (u64) | Checkpoint bytes |
-| `finalized_headers` | epoch (u64) | FinalizedHeader bytes |
-| `most_recent_checkpoint` | - | epoch (u64) |
-| `most_recent_finalized_header` | - | epoch (u64) |
+| Key Space | Key | Value |
+|-----------|-----|-------|
+| `checkpoint` | epoch (u64) | `(Checkpoint, last_block)` |
+| `finalized_header` | epoch (u64) | `FinalizedHeader` bytes |
+| `latest_checkpoint_epoch` | fixed state key | epoch (u64) |
+| `latest_finalized_header_epoch` | fixed state key | epoch (u64) |
+| `consensus_state` | epoch (u64) | `ConsensusState` bytes |
 
 ## Checkpoint Verification
 
@@ -185,7 +186,7 @@ checkpoint_dir/
 
 ### Checkpoint Verification on Startup
 
-When the `finalized_headers/` directory is present, the node automatically verifies the checkpoint on startup by calling `verify_checkpoint_chain` with the genesis state, the loaded headers, and the checkpoint. This allows the node to trustlessly validate a checkpoint received from an untrusted source.
+When the `finalized_headers/` directory is present, the node loads the checkpoint artifacts from disk first, then verifies the checkpoint during startup after loading genesis by calling `verify_checkpoint_chain` with the genesis state, the loaded headers, and the checkpoint. This allows the node to trustlessly validate a checkpoint received from an untrusted source.
 
 If the `finalized_headers/` directory is absent, verification is skipped and the node trusts the checkpoint as-is.
 

docs/checkpointing.md

@@ -9,10 +9,11 @@ Summit leverages the [Commonware library](https://commonware.xyz) extensively fo
 **Used for**: Simplex consensus protocol implementation
 
 **Key Components:**
-- `simplex::SimplexConsensus` - Core consensus engine
-- `simplex::types::Activity` - Consensus activities/messages
-- `simplex::signing_scheme::Scheme` - Signature verification
+- `simplex` - Simplex consensus engine
+- `simplex::scheme::Scheme` - Signature verification scheme
+- `types::{Epoch, Epocher, FixedEpocher, Round, View, ViewDelta, Height}` - Consensus primitives
 - `Block` trait - Block interface definition
+- `Reporter` trait - Hook for consensus activity notifications
 
 **Critical Usage:**
 - **Consensus Protocol**: All consensus logic delegated to Commonware's Simplex implementation
@@ -41,10 +42,11 @@ Summit leverages the [Commonware library](https://commonware.xyz) extensively fo
 **Used for**: Peer-to-peer communication between validators
 
 **Key Components:**
-- `authenticated` - Authenticated P2P connections
-- `Manager` - Peer connection management
+- `authenticated` - Authenticated P2P connections (production)
+- `simulated` - In-process network (deterministic tests)
+- `Manager`, `Provider`, `TrackedPeers`, `PeerSetUpdate` - Peer set management
 - `Sender`/`Receiver` - Message transmission
-- `utils::requester` - Request-response patterns
+- `Blocker`, `Ingress` - Connection filtering and admission
 
 **Critical Usage:**
 - **Validator Discovery**: Automatic peer discovery and connection
@@ -57,25 +59,29 @@ Summit leverages the [Commonware library](https://commonware.xyz) extensively fo
 **Used for**: Persistent storage of consensus state and blocks
 
 **Key Components:**
-- **Storage traits**: Generic storage interface
-- **Database implementations**: Pluggable storage backends
-- **Atomic operations**: Transactional state updates
+- `qmdb::store::db::Db` - QMDB authenticated key-value store (consensus state, headers)
+- `archive` / `archive::immutable` - Block archive keyed by height
+- `journal::contiguous::variable` - Append-only write-ahead log
+- `translator::EightCap` - Key translator for the QMDB store
+- `metadata::Metadata` - Metadata store for pointer/tip data
 
 **Critical Usage:**
-- **State Persistence**: Consensus state and validator set storage
-- **Block Storage**: Immutable block data with efficient retrieval
-- **Atomic Updates**: Ensuring consistency during state transitions
-- **Historical Data**: Compressed archival of old blocks
+- **State Persistence**: Consensus state, validator set, and finalized headers in QMDB
+- **Block Storage**: Finalized blocks archived by height via `archive::immutable`
+- **Atomic Updates**: Journal-backed writes with WAL semantics
+- **Checkpoints**: Durable checkpoint records for fast sync
 
 ### 5. Runtime (`commonware-runtime`)
 
 **Used for**: Async runtime abstractions and utilities
 
 **Key Components:**
-- `Clock` - Time management
-- `Spawner` - Task spawning abstractions
-- `Metrics` - Performance monitoring
-- `buffer::PoolRef` - Memory pool management
+- `tokio::Runner` - Production async runtime (wraps Tokio)
+- `deterministic::Runner` - Seeded, deterministic runtime for tests
+- `Clock`, `Spawner`, `Handle` - Time, task spawning, and join handles
+- `Metrics` - Prometheus-compatible metrics registry
+- `Network`, `Storage` - Abstract network and disk interfaces
+- `buffer::paged::CacheRef`, `BufferPooler` - Paged buffer caching for storage
 
 **Critical Usage:**
 - **Task Management**: Async task spawning and coordination
@@ -88,10 +94,10 @@ Summit leverages the [Commonware library](https://commonware.xyz) extensively fo
 **Used for**: Common data structures and utilities
 
 **Key Components:**
-- `NZU64`, `NZUsize` - Non-zero integer types
-- `Span` - Efficient byte spans
-- `sequence` - Sequence number management
-- Hex utilities - Hexadecimal encoding/decoding
+- `NZU64`, `NZUsize` - Non-zero integer types (and their constructor macros)
+- `from_hex_formatted`, `hex` - Hexadecimal encoding/decoding
+- `Hostname` - Validated hostname type for bootstrap configuration
+- `acknowledgement::{Acknowledgement, Exact}` - Activity acknowledgement tracking
 
 ### 7. Codec (`commonware-codec`)
 
@@ -121,6 +127,33 @@ Summit leverages the [Commonware library](https://commonware.xyz) extensively fo
 - `Consumer`/`Producer` - Data request/response
 - `p2p::Producer` - P2P data resolution
 
+### 10. Macros (`commonware-macros`)
+
+**Used for**: Async control-flow macros and instrumented test harness
+
+**Key Components:**
+- `select!` / `select_loop!` - Async branching and loops (used in `application/`, `syncer/`)
+- `test_traced!` - Instrumented test harness with deterministic tracing
+
+### 11. Math (`commonware-math`)
+
+**Used for**: Cryptographic randomness
+
+**Key Components:**
+- `algebra::Random` - Random key generation for BLS12-381 and Ed25519 schemes
+
+**Critical Usage:**
+- **Key Generation**: Deterministic randomness for consensus and node key creation in `node/src/keys.rs`
+- **Testing**: Seeded randomness for reproducible test fixtures
+
+### 12. Parallel (`commonware-parallel`)
+
+**Used for**: Sequential and parallel processing strategies
+
+**Key Components:**
+- `Strategy` - Abstraction over execution strategies
+- `Sequential` - Single-threaded execution strategy (used by the syncer and engine)
+
 ## Security Analysis
 
 ### Cryptographic Security
@@ -207,17 +240,21 @@ use commonware_macros::test_traced;
 
 ### Upgrade Path
 
-Summit can upgrade Commonware components independently by updating the git revision in `Cargo.toml`:
+Summit pins Commonware to a versioned release in the workspace `Cargo.toml`. All 12 `commonware-*` workspace dependencies are bumped in lockstep:
 
 ```toml
-commonware-consensus = { git = "https://github.com/commonwarexyz/monorepo.git", rev = "f395c9e" }
+commonware-consensus = "2026.4.0"
+commonware-cryptography = "2026.4.0"
+# ...
 ```
 
+To upgrade, bump the version across every `commonware-*` entry in the root `Cargo.toml` and run `cargo update -p commonware-consensus` (etc.).
+
 ## Audit Recommendations
 
 When auditing Summit's Commonware usage:
 
-1. **Verify Git Revision**: Ensure using audited Commonware revision
+1. **Verify Version**: Ensure the pinned Commonware release corresponds to an audited version
 2. **Integration Points**: Review how Summit integrates Commonware APIs
 3. **Configuration**: Verify Commonware components configured securely
 4. **Error Handling**: Ensure proper error handling around Commonware calls

docs/commonware-dependencies.md

@@ -28,6 +28,8 @@ pub trait EngineClient: Clone + Send + Sync + 'static {
         fork_choice_state: ForkchoiceState,
         timestamp: u64,
         withdrawals: Vec<Withdrawal>,
+        suggested_fee_recipient: Address,
+        parent_beacon_block_root: Option<FixedBytes<32>>,
     ) -> impl Future<Output = Option<PayloadId>> + Send;
 
     fn get_payload(
@@ -43,7 +45,7 @@ pub trait EngineClient: Clone + Send + Sync + 'static {
     fn commit_hash(
         &mut self,
         fork_choice_state: ForkchoiceState,
-    ) -> impl Future<Output = ()> + Send;
+    ) -> impl Future<Output = ForkchoiceUpdated> + Send;
 }
 ```
 
@@ -182,4 +184,4 @@ let provider = ProviderBuilder::default().connect_ipc(ipc).await?;
 
 **Logging**: Summit uses the `tracing` crate for logging
 
-**Health Checks**: Summit exposes an HTTP API bound to port 3030 by default. This API includes the method `GET /health` which will reply with `"OK"` if you are lucky. While this API is fairly minimal at the time of this writing, we would not be surprised this bloats up in the future
+**Health Checks**: Summit exposes a JSON-RPC API bound to port 3030 by default. The health check is the `health` RPC method, which currently returns `"Ok"`.

docs/engine-api-integration.md

@@ -4,20 +4,20 @@ Easiest way to run a network locally is to use the testnet bin. This will start
 
 ## Steps to do this:
 
-1. First make sure you have seismic-reth installed and in your PATH
+1. First make sure you have a `reth` binary installed and in your `PATH`. For Seismic development, that typically means building `seismic-reth` and placing the resulting binary in your path as `reth`.
    ```bash
    git clone https://github.com/SeismicSystems/seismic-reth.git && cd seismic-reth && cargo build --release
    ```
-   - move the seismic bin somewhere in your path under the name reth
+   - Move the built binary somewhere in your path under the name `reth`
    ```bash
    mv target/release/seismic-reth ~/.cargo/bin/reth
    ```
 
-2. Then run cd into this repo and run `cargo run --bin testnet` at root of this repo. This will start 4 nodes in that terminal
+2. Then `cd` into this repo and run `cargo run --bin testnet` at the repo root. This will start 4 Summit nodes and 4 Reth nodes in that terminal.
 
-3. You can reach the reth rpc at localhost:8545 (ports for the other 3 nodes ar 8546, 8547, 8548)
+3. You can reach the Reth RPC endpoints on the ports printed by the testnet binary. By default they are `localhost:8545`, `localhost:8546`, `localhost:8547`, and `localhost:8548`.
 
-4. To start the network fresh run this from the root of this repo
+4. To reset the local testnet data and start fresh, run this from the repo root:
    ```bash
    cd testnet && ./reset.sh && cd ..
    ```
@@ -26,8 +26,8 @@ Easiest way to run a network locally is to use the testnet bin. This will start
 
 ## Running distributed
 
-To run a fresh network on multiple systems you should install summit on each server and then run `cargo run -- keys generate && cargo run -- keys show` to get the keys for each node.
+To run a fresh network on multiple systems you should install Summit on each server and then run `cargo run -- keys generate` and `cargo run -- keys show` to get the keys for each node.
 
-You will then recreate the example_genesis.toml file to have the keys and ips of all your nodes.
+You will then recreate the example_genesis.toml file to have the keys and IPs of all your nodes.
 
-After the genesis file is in place you would just start seismic-reth with the `--mock-enclave` flag and then start summit on each and the network should start
+After the genesis file is in place you would start your `reth`/`seismic-reth` instance and then start Summit on each host with the matching genesis configuration.

docs/running-local-network.md

@@ -51,8 +51,7 @@ We use SHA-256 in several places:
 
 All peer-to-peer communication is cryptographically authenticated with the following properties:
 - **Mutual Authentication**: Both peers verify each other's identity
-- **Perfect Forward Secrecy**: Session keys derived independently
-- **Replay Protection**: Nonces prevent message replay attacks
+- **Message Authentication**: Signed/authenticated communication between peers
 - **Identity Verification**: Peer public keys verified against validator set
 
 ## BFT Properties
@@ -70,10 +69,14 @@ Summit communicates with execution clients exclusively through the Engine API:
 ```rust
 // NOTE: no direct access to execution state
 pub trait EngineClient: Clone + Send + Sync + 'static {
-    fn start_building_block(...) -> impl Future<Output = Option<PayloadId>>;
+    fn start_building_block(
+        ...,
+        suggested_fee_recipient: Address,
+        parent_beacon_block_root: Option<FixedBytes<32>>,
+    ) -> impl Future<Output = Option<PayloadId>>;
     fn get_payload(...) -> impl Future<Output = ExecutionPayloadEnvelopeV4>;
     fn check_payload(...) -> impl Future<Output = PayloadStatus>;
-    fn commit_hash(...) -> impl Future<Output = ()>;
+    fn commit_hash(...) -> impl Future<Output = ForkchoiceUpdated>;
 }
 ```
 
@@ -97,7 +100,6 @@ pub trait EngineClient: Clone + Send + Sync + 'static {
 
 **Threat**: Man-in-the-middle attacks
 **Mitigation**:
-- Perfect forward secrecy in P2P connections
 - End-to-end message authentication
 - Public key verification against validator set
 

docs/security-model.md

@@ -11,11 +11,16 @@ The changes were made to accommodate every consensus node having 2 keys to parti
 ## Becoming a Validator
 
 1. Deploy the Summit image on a TDX VM. This will start seismic-reth and Summit as well as the enclave.
-2. The deposit function requires a signature with the node's keys. Since they are only available from within the secure enclave, an RPC endpoint is exposed to receive the signed calldata that includes the signature from the node at default port 3030:
+2. The deposit function requires a signature with the node's keys. Since they are only available from within the secure enclave, the node exposes a JSON-RPC method on port 3030 by default to produce the signed deposit calldata:
+   ```json
+   {
+     "jsonrpc": "2.0",
+     "method": "getDepositSignature",
+     "params": [32000000000, "0x0000000000000000000000000000000000000000"],
+     "id": 1
+   }
    ```
-   /get_deposit_signature?amount=32000000000&address=0x0000000000000000000000000000000000000000
-   ```
-   The `amount` should be the staking amount and `address` should be your Ethereum address you want to be able to withdraw to.
+   The `amount` should be the staking amount and `address` should be the Ethereum address you want to be able to withdraw to.
 3. Send a signed transaction to the deposit contract with the calldata from the previous step, along with a value equal to the amount being staked (contract address: `0x00000000219ab540356cBB839Cbe05303d7705Fa`, same as Ethereum).
 4. Download the latest checkpoint and load it into the node.
 5. Keep your node running and it will start participating in the next epoch.