[examples/revm] Add REVM example on threshold-simplex

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,39 @@
+[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
+rand.workspace = true
+revm = { version = "33.1.0", default-features = false, features = ["std", "asyncdb"] }
+thiserror.workspace = true
+
+[[bin]]
+name = "commonware-revm"
+bench = false

examples/revm/README.md

@@ -0,0 +1,87 @@
+# 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).
+- State commitment is deterministic and does not require iterating the whole DB:
+  - `delta = keccak256(Encode(StateChanges))`
+  - `new_root = keccak256(prev_root || delta)`
+- 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/types.rs`: canonical block/tx types and digest mapping (`ConsensusDigest = sha256(BlockId)`).
+- `src/application/`: proposal/verification logic (marshaled), shared state (mempool + DB snapshots), reporters, and query handle.
+- `src/execution.rs`: EVM execution (`EthEvmBuilder`) and the seed precompile.
+- `src/commitment.rs`: canonical `StateChanges` encoding and rolling `StateRoot` commitment.
+- `src/sim/`: 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/sim/node.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.
+
+## 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` is a rolling commitment over per-tx state deltas.
+- 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/src/application/app.rs

@@ -0,0 +1,154 @@
+//! Consensus-facing application implementation for the REVM chain example.
+//!
+//! Threshold-simplex orders only block commitments (digests). Full blocks are disseminated and
+//! backfilled by `commonware_consensus::marshal`. The `commonware_consensus::application::marshaled::Marshaled`
+//! wrapper bridges these layers by fetching required ancestors from marshal and calling into this
+//! module with an `AncestorStream` you can iterate to walk back over pending blocks.
+//!
+//! The node wiring that wraps this application lives in `examples/revm/src/sim/node.rs`.
+
+use super::state::Shared;
+use crate::{
+    execution::{evm_env, execute_txs},
+    types::{Block, TxId},
+    ConsensusDigest, PublicKey,
+};
+use alloy_evm::revm::primitives::B256;
+use commonware_consensus::{
+    marshal::ingress::mailbox::AncestorStream,
+    simplex::{scheme::Scheme, types::Context},
+    Application, VerifyingApplication,
+};
+use commonware_cryptography::Committable as _;
+use commonware_runtime::{Clock, Metrics, Spawner};
+use futures::StreamExt as _;
+use rand::Rng;
+use std::{collections::BTreeSet, marker::PhantomData};
+
+#[derive(Clone)]
+pub(crate) struct RevmApplication<S> {
+    max_txs: usize,
+    state: Shared,
+    _scheme: PhantomData<S>,
+}
+
+impl<S> RevmApplication<S> {
+    pub(crate) const fn new(max_txs: usize, state: Shared) -> Self {
+        Self {
+            max_txs,
+            state,
+            _scheme: PhantomData,
+        }
+    }
+}
+
+impl<E, S> Application<E> for RevmApplication<S>
+where
+    E: Rng + Spawner + Metrics + Clock,
+    S: Scheme<ConsensusDigest>
+        + commonware_cryptography::certificate::Scheme<PublicKey = PublicKey>,
+{
+    type SigningScheme = S;
+    type Context = Context<ConsensusDigest, PublicKey>;
+    type Block = Block;
+
+    async fn genesis(&mut self) -> Self::Block {
+        self.state.genesis_block()
+    }
+
+    async fn propose(
+        &mut self,
+        _context: (E, Self::Context),
+        mut ancestry: AncestorStream<Self::SigningScheme, Self::Block>,
+    ) -> Option<Self::Block> {
+        let parent = ancestry.next().await?;
+
+        // Transactions remain in the mempool until the block that includes them finalizes. Walk
+        // back over pending ancestors so we do not propose a block that re-includes in-flight txs.
+        let mut included = BTreeSet::<TxId>::new();
+        for tx in parent.txs.iter() {
+            included.insert(tx.id());
+        }
+        while let Some(block) = ancestry.next().await {
+            for tx in block.txs.iter() {
+                included.insert(tx.id());
+            }
+        }
+
+        let parent_digest = parent.commitment();
+        let parent_snapshot = self.state.parent_snapshot(&parent_digest).await?;
+        let seed_hash = self.state.seed_for_parent(&parent_digest).await;
+        let prevrandao = seed_hash.unwrap_or_else(|| B256::from(parent_digest.0));
+
+        let txs = self.state.build_txs(self.max_txs, &included).await;
+
+        let mut child = Block {
+            parent: parent.id(),
+            height: parent.height + 1,
+            prevrandao,
+            state_root: parent.state_root,
+            txs,
+        };
+
+        let (db, outcome) = execute_txs(
+            parent_snapshot.db,
+            evm_env(child.height, child.prevrandao),
+            parent.state_root,
+            &child.txs,
+        )
+        .ok()?;
+        child.state_root = outcome.state_root;
+
+        let digest = child.commitment();
+        self.state
+            .insert_snapshot(digest, db, child.state_root, outcome.qmdb_changes)
+            .await;
+        Some(child)
+    }
+}
+
+impl<E, S> VerifyingApplication<E> for RevmApplication<S>
+where
+    E: Rng + Spawner + Metrics + Clock,
+    S: Scheme<ConsensusDigest>
+        + commonware_cryptography::certificate::Scheme<PublicKey = PublicKey>,
+{
+    async fn verify(
+        &mut self,
+        _context: (E, Self::Context),
+        mut ancestry: AncestorStream<Self::SigningScheme, Self::Block>,
+    ) -> bool {
+        let block = match ancestry.next().await {
+            Some(block) => block,
+            None => return false,
+        };
+        let parent = match ancestry.next().await {
+            Some(block) => block,
+            None => return false,
+        };
+
+        let parent_digest = parent.commitment();
+        let Some(parent_snapshot) = self.state.parent_snapshot(&parent_digest).await else {
+            return false;
+        };
+
+        let (db, outcome) = match execute_txs(
+            parent_snapshot.db,
+            evm_env(block.height, block.prevrandao),
+            parent.state_root,
+            &block.txs,
+        ) {
+            Ok(result) => result,
+            Err(_) => return false,
+        };
+        if outcome.state_root != block.state_root {
+            return false;
+        }
+
+        let digest = block.commitment();
+        self.state
+            .insert_snapshot(digest, db, block.state_root, outcome.qmdb_changes)
+            .await;
+        true
+    }
+}

examples/revm/src/application/handle.rs

@@ -0,0 +1,39 @@
+//! Handle for interacting with the application state.
+//!
+//! The simulation harness uses this handle to:
+//! - submit transactions into the node-local mempool, and
+//! - query state at a finalized digest for assertions.
+
+use super::state::Shared;
+use crate::{
+    types::{StateRoot, Tx},
+    ConsensusDigest,
+};
+use alloy_evm::revm::primitives::{Address, B256, U256};
+
+#[derive(Clone)]
+pub struct NodeHandle {
+    state: Shared,
+}
+
+impl NodeHandle {
+    pub(crate) const fn new(state: Shared) -> Self {
+        Self { state }
+    }
+
+    pub async fn submit_tx(&self, tx: Tx) -> bool {
+        self.state.submit_tx(tx).await
+    }
+
+    pub async fn query_balance(&self, digest: ConsensusDigest, address: Address) -> Option<U256> {
+        self.state.query_balance(digest, address).await
+    }
+
+    pub async fn query_state_root(&self, digest: ConsensusDigest) -> Option<StateRoot> {
+        self.state.query_state_root(digest).await
+    }
+
+    pub async fn query_seed(&self, digest: ConsensusDigest) -> Option<B256> {
+        self.state.query_seed(digest).await
+    }
+}

examples/revm/src/application/mod.rs

@@ -0,0 +1,11 @@
+//! Chain application logic (block production and verification).
+
+mod app;
+mod handle;
+mod reporters;
+mod state;
+
+pub(crate) use app::RevmApplication;
+pub use handle::NodeHandle;
+pub(crate) use reporters::{FinalizedReporter, SeedReporter};
+pub(crate) use state::Shared;