REVM example: digest-first EVM execution with QMDB persistence

Cargo.toml

@@ -25,6 +25,7 @@ members = [
     "examples/log",
     "examples/sync",
     "examples/reshare",
+    "examples/revm",
 
     # Fuzz builds
     "broadcast/fuzz",

examples/revm/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "commonware-revm"
+edition.workspace = true
+publish = true
+version.workspace = true
+license.workspace = true
+description = "REVM-based example chain running on threshold-simplex (simplex + threshold BLS signatures)."
+readme = "README.md"
+homepage.workspace = true
+repository = "https://github.com/commonwarexyz/monorepo/tree/main/examples/revm"
+
+[lints]
+workspace = true
+
+[dependencies]
+
+# EVM execution
+alloy-evm = { version = "=0.25.1", default-features = false, features = ["std"] }
+anyhow.workspace = true
+bytes.workspace = true
+clap.workspace = true
+commonware-broadcast.workspace = true
+commonware-codec.workspace = true
+commonware-consensus.workspace = true
+commonware-cryptography.workspace = true
+commonware-p2p.workspace = true
+commonware-parallel.workspace = true
+commonware-runtime.workspace = true
+commonware-storage.workspace = true
+commonware-utils.workspace = true
+futures.workspace = true
+governor.workspace = true
+libc.workspace = true
+rand.workspace = true
+revm = { version = "33.1.0", default-features = false, features = ["std", "asyncdb"] }
+thiserror.workspace = true
+tracing.workspace = true
+
+[[bin]]
+name = "commonware-revm"
+bench = false

examples/revm/README.md

@@ -0,0 +1,91 @@
+# commonware-revm
+
+[![Crates.io](https://img.shields.io/crates/v/commonware-revm.svg)](https://crates.io/crates/commonware-revm)
+
+REVM-based example chain driven by threshold-simplex (`commonware_consensus::simplex`) and executed with `alloy-evm`.
+
+## What This Demonstrates
+
+- Threshold-simplex orders opaque 32-byte digests; full blocks are disseminated and backfilled by `commonware_consensus::marshal` over `commonware_p2p::simulated`.
+- Blocks carry a batch of EVM transactions plus an advertised 32-byte `state_root` commitment.
+- Validators re-execute proposed blocks with `alloy-evm` / `revm` and reject proposals whose `state_root` mismatches.
+- State is persisted in QMDB and exposed to REVM via `WrapDatabaseAsync` + `CacheDB` (QMDB is the base store; CacheDB is the speculative overlay).
+- The `state_root` is derived from authenticated QMDB partition roots (accounts, storage, code).
+- Seed plumbing: threshold-simplex certificate seed signatures are hashed to 32 bytes and injected as `block.prevrandao` (EIP-4399).
+- Bonus: a stateful precompile at `0x00000000000000000000000000000000000000ff` returns the current block's `prevrandao` (32 bytes).
+
+## Components
+
+- `src/domain/`: canonical block/tx types, commitment mapping, and deterministic state-change encoding.
+- `src/application/`: proposal/verification logic (marshaled), shared state (mempool + DB snapshots), reporters, and query handle.
+- `src/application/execution.rs`: EVM execution (`EthEvmBuilder`) and the seed precompile.
+- `src/qmdb/`: QMDB-backed persistence and REVM database adapter.
+- `src/simulation/`: tokio, single-process simulation harness (N nodes, simulated P2P).
+
+## How It Works
+
+This example is intentionally "digest-first":
+
+- Simplex agrees on a `ConsensusDigest` for each height (32 bytes).
+- The application maps `ConsensusDigest <-> Block` and ensures a digest is only accepted if the
+  corresponding block re-executes to the advertised `state_root`.
+
+### Block Lifecycle (One Height)
+
+1. Genesis: the application creates the genesis block and prefunds accounts in the EVM DB.
+2. Propose: when Simplex asks a leader to propose, the application builds a child block, executes
+   its txs, stores the block + resulting DB snapshot locally, and returns the full block to the
+   `commonware_consensus::application::marshaled::Marshaled` wrapper (consensus still orders only
+   the block commitment digest).
+3. Disseminate: marshal broadcasts the full block and serves backfill requests for missing ancestors.
+4. Verify: validators re-execute the block on the parent snapshot and accept only if the computed
+   `state_root` matches the advertised `state_root` (the wrapper notifies marshal on success).
+5. Finalize: marshal delivers finalized blocks to the node, the simulation records the digest, and stops after the configured
+   number of finalizations per node.
+
+The main glue points are `src/application/node/start.rs` (wiring) and `src/application/` (application logic).
+
+### Seed Lifecycle
+
+- On notarization/finalization, threshold-simplex emits a seed signature.
+- This example hashes that seed signature to 32 bytes and stores it alongside the finalized digest.
+- The next block uses the parent digest's stored seed hash as `prevrandao` (EIP-4399).
+- The seed precompile returns the current block's `prevrandao` so contracts can read it.
+
+### State Root Semantics
+
+- Block headers publish the pre-commit QMDB root computed after merkleization but before durability is enforced.
+- QMDB commit operations append to the authenticated log, so the post-commit root can differ even when state does not.
+- Treat the header `state_root` as the consensus commitment and do not compare it to the post-commit QMDB root.
+
+## Run (Tokio Simulation)
+
+```sh
+cargo run -p commonware-revm --release -- --nodes 4 --blocks 5 --seed 1
+```
+
+Flags:
+
+- `--nodes`: number of validators (default: 4)
+- `--blocks`: number of finalized blocks to wait for per node (default: 3)
+- `--seed`: seeded DKG + demo inputs (default: 1)
+
+Expected output is consistent for a given `--seed` and includes:
+
+- Finalized head digest (agreed by consensus)
+- Final `state_root` commitment
+- Final balances for the example accounts
+- Latest tracked threshold seed (32 bytes) and the current block's `prevrandao`
+
+## Test
+
+```sh
+cargo test -p commonware-revm
+```
+
+## Notes and Next Steps
+
+- This is intentionally minimal and does not implement an Ethereum trie; `state_root` comes from authenticated QMDB partition roots.
+- Transactions are built directly as EVM call environments (no signature/fee market modeling); gas price is set to 0.
+- The demo block stream is minimal (a single transfer is injected early); extend `src/application/` to add more tx generation.
+- The example now uses a QMDB-backed persistence layer with per-finalized-block batch commits.

examples/revm/docs/ARCHITECTURE.md

@@ -0,0 +1,137 @@
+# REVM Example Architecture
+
+This document explains how the REVM example works end to end. It is written so a reader can choose
+between a quick high-level scan and a deeper technical pass.
+
+## Status and scope
+
+- This is an example chain, not a production client.
+- It demonstrates how Commonware consensus, marshal, and QMDB persistence can drive REVM execution.
+- It intentionally omits signatures, fee markets, Ethereum MPT state roots, and many other features.
+
+## How to read this
+
+- Quick scan: read "System overview" and "Data flow by stage".
+- Deep dive: also read "State and persistence semantics" and "Safety and invariants".
+- If you want domain vocabulary, see DOMAIN_MODEL.md.
+
+## System overview
+
+At a high level, the example does this:
+
+1. Consensus orders 32-byte digests, not full blocks.
+2. Full blocks are disseminated and backfilled by marshal.
+3. Each block is verified by re-executing its transactions in REVM.
+4. The resulting state changes are translated into a QMDB change set.
+5. Finalized blocks are persisted in QMDB in batch order.
+
+The architecture diagram is in `revm_architecture.png` (source: `revm_architecture.dot`).
+
+## Component map (what owns what)
+
+| Component | Responsibility | Key files |
+| --- | --- | --- |
+| CLI | Parses flags, starts a simulation | `examples/revm/src/main.rs` |
+| Simulation | Orchestrates N nodes, waits for finalization | `examples/revm/src/simulation/mod.rs` |
+| Node wiring | Connects consensus, marshal, application, and storage | `examples/revm/src/application/node/` |
+| Consensus (simplex) | Orders digests and emits notarization and finalization events | `commonware_consensus` |
+| Marshal | Disseminates blocks and serves backfill requests | `examples/revm/src/application/node/marshal.rs` |
+| Application | Propose and verify full blocks | `examples/revm/src/application/app.rs` |
+| Execution | Runs REVM and extracts state changes | `examples/revm/src/application/execution.rs` |
+| Ledger view | Mempool, snapshots, seeds, persistence coordination | `examples/revm/src/application/ledger/` |
+| QMDB | Authenticated storage for accounts, storage, and code | `examples/revm/src/qmdb/` |
+| Reporters | React to consensus and marshal events | `examples/revm/src/application/reporters/` |
+| Observers | Log domain events (non-mutating) | `examples/revm/src/application/observers.rs` |
+
+## Data flow by stage
+
+### 1) Propose
+
+- Simplex asks the application to propose a block.
+- The application gathers transactions from the mempool, skipping any already included in pending
+  ancestors.
+- REVM executes the batch using a parent snapshot and a prevrandao seed.
+- The application computes a QMDB state root for the change set.
+- The block is produced with the advertised `state_root` and cached as a local snapshot.
+
+### 2) Verify
+
+- Validators receive a full block and re-execute it against the parent snapshot.
+- The computed `state_root` must match the block header.
+- If it matches, the validator caches the snapshot. If it does not match, the block is rejected.
+
+### 3) Finalize and persist
+
+- Marshal delivers finalized blocks to `FinalizedReporter`.
+- If the snapshot already exists, we reuse it. If not, we re-execute to rebuild it.
+- We recompute the root and ensure it matches the block header.
+- We commit the aggregated change set to QMDB and mark the digest as persisted.
+- We prune the mempool and acknowledge marshal so delivery can continue.
+
+The block lifecycle diagram is in `revm_block_lifecycle.png`.
+The persistence flow diagram is in `revm_persistence_flow.png`.
+
+## State and persistence semantics
+
+### Digest and root definitions
+
+- `BlockId` is `keccak256(Encode(Block))`.
+- The consensus digest is `sha256(BlockId)`.
+- `StateRoot` is a commitment over QMDB partition roots for accounts, storage, and code.
+
+### Pre-commit vs post-commit root
+
+- The block header uses a pre-commit root computed by merkleizing partition roots.
+- QMDB commit operations append authenticated log entries, so the post-commit root can differ.
+- Treat the header `state_root` as the consensus commitment.
+
+### Snapshots
+
+- Each executed block produces a `LedgerSnapshot` with:
+  - Parent digest
+  - REVM overlay database (`RevmDb`)
+  - `StateRoot`
+  - `QmdbChangeSet`
+- Snapshots are cached to avoid re-executing on finalization.
+
+## Runtime and determinism
+
+- The example uses the tokio runtime because REVM requires a tokio runtime to bridge the async QMDB
+  adapter into REVM's sync database interface.
+- Determinism is achieved by seeded key generation and a simulated network with fixed configuration.
+- Runtime scheduling is not guaranteed deterministic. The tests focus on stable outcomes for fixed
+  seeds, not on exact message ordering.
+
+## Safety and invariants
+
+These are the main correctness checks and invariants:
+
+- A block is only accepted if re-execution yields the advertised `state_root`.
+- QMDB changes for a digest are merged in order, ancestor to child, before persistence.
+- Persisting a digest is idempotent. Duplicate persist calls are a no-op.
+- The mempool is pruned only after successful persistence of the finalized block.
+
+## Failure handling
+
+- If a finalized block arrives without a cached snapshot, we re-execute it to rebuild the snapshot.
+- If re-execution or root computation fails, we log and acknowledge the update to avoid stalling
+  marshal delivery.
+- Errors returned by mutable QMDB methods are treated as fatal for that database instance.
+  Callers must not use the database after such an error.
+
+## Performance considerations
+
+- Executing and committing per block is expensive. This example batches QMDB commits per finalized
+  block for simplicity.
+- Snapshot caching avoids re-execution for proposers and validators.
+- The simulated network uses fixed link latency and message size caps.
+
+## Extension points
+
+This example is intentionally minimal. Common extension points include:
+
+- Adding transaction signatures and nonce validation.
+- Implementing a fee market and gas price handling.
+- Replacing `StateRoot` with an Ethereum-compatible trie.
+- Adding richer transaction generation for the simulation.
+- Introducing byzantine behavior in the simulated network to stress consensus.