ShellDAO · LucienSong · May 26, 2026 · May 26, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -59,7 +59,7 @@ Toolchain uses the `stable` channel via `rust-toolchain.toml` (+ rustfmt + clipp
 | `storage` | KvStore, witness pruner, settled-source index |
 | `consensus` | wPoA engine, validator set, slashing |
 | `genesis` | Genesis block construction |
-| `evm` | revm-backed PQVM execution adapter, parallel scheduler |
+| `pqvm` | revm-backed PQVM execution adapter, parallel scheduler |
 | `mempool` | Transaction pool |
 | `network` | libp2p gossipsub |
 | `rpc` | JSON-RPC, TLS, three-RPC fanout |

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -331,20 +331,20 @@ All notable changes to this project will be documented in this file.
   `expiry_block`, `root_signature`, and `session_signature`. RLP encodes as a
   5-field list. Breaking change vs v0.18.x wire format. See `docs/AA_PHASE2_SPEC.md`.
 
-- **AA Phase 2 contract paymaster** (`crates/evm`): `validatePaymasterOp` ABI call
+- **AA Phase 2 contract paymaster** (`crates/pqvm`): `validatePaymasterOp` ABI call
   dispatched when `paymaster_context` is present. Call runs in a world-state
   snapshot (mutations discarded). Gas cap 50k. Bool return decoded from 32-byte
   ABI word.
 
-- **AA Phase 2 session keys** (`crates/evm`): Session-key-signed AA bundles now
+- **AA Phase 2 session keys** (`crates/pqvm`): Session-key-signed AA bundles now
   validated via two-step PQ verification: (1) root key authorizes the session key
   via `session_auth_hash`; (2) session key signs the tx via `sender_signing_hash`.
   Constraint checks: expiry block, value cap (Σ inner call values), optional target
   restriction. New error variants: `SessionKeyExpired`, `SessionValueCapExceeded`,
   `SessionTargetMismatch`, `SessionRootSignatureInvalid`, `SessionKeySignatureInvalid`,
   `SessionKeyDisallowedAlgorithm`.
 
-- **AA Phase 2 guardian recovery** (`crates/evm`, `crates/storage`): `AccountManager`
+- **AA Phase 2 guardian recovery** (`crates/pqvm`, `crates/storage`): `AccountManager`
   system contract gains 4 new entry points: `setGuardians(address[],uint8,uint64)`,
   `submitRecovery(address,bytes,uint8)`, `executeRecovery(address)`,
   `cancelRecovery(address)`. `GuardianConfig` and `RecoveryProposal` persisted in
@@ -355,7 +355,7 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
-- **Double PQ signature verification** (`crates/evm`): `validate_tx()` and
+- **Double PQ signature verification** (`crates/pqvm`): `validate_tx()` and
   `validate_tx_for_import()` both previously called `verify_paymaster_signature()`
   after already invoking `validate_aa_tx()` which performs the same check internally.
   The redundant second call is now removed; PQ (Dilithium) sig verification is
@@ -591,16 +591,16 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
-- **Parallel EVM executor** (`crates/evm`): `ConflictMetric` type with `ReadWrite`, `WriteWrite`, and `Incomplete` variants for tracking inter-transaction state conflicts.
+- **Parallel PQVM executor** (`crates/pqvm`): `ConflictMetric` type with `ReadWrite`, `WriteWrite`, and `Incomplete` variants for tracking inter-transaction state conflicts.
 - `plan_with_metrics()`: transaction dependency graph builder that returns a `Vec<ConflictMetric>` alongside the execution plan.
-- CLI flag `--parallel-evm` (default: **OFF**) to opt-in to the parallel execution path.
-- CLI flag `--parallel-evm-workers <N>` to control the Rayon worker-pool size (default: number of logical CPUs).
-- `config/node.example.toml` updated with a `[parallel_evm]` section documenting both flags.
-- State validation tests: 11 unit tests in `crates/evm`, 3 benchmarks in `crates/bench` (`parallel_evm_throughput`, `conflict_detection_overhead`, `sequential_baseline`).
+- CLI flag `--parallel-pqvm` (default: **OFF**) to opt-in to the parallel execution path.
+- CLI flag `--parallel-pqvm-workers <N>` to control the Rayon worker-pool size (default: number of logical CPUs).
+- `config/node.example.toml` updated with a `[parallel_pqvm]` section documenting both flags.
+- State validation tests: 11 unit tests in `crates/pqvm`, 3 benchmarks in `crates/bench` (`parallel_pqvm_throughput`, `conflict_detection_overhead`, `sequential_baseline`).
 
 ### Changed
 
-- `parallel-evm` feature is gated behind the CLI flag and disabled on production nodes until further notice.
+- `parallel-pqvm` feature is gated behind the CLI flag and disabled on production nodes until further notice.
 
 ### Previous release: [0.13.0]
 
@@ -629,7 +629,7 @@ All notable changes to this project will be documented in this file.
 
 **Batch 4 — Operations & Observability**
 - Structured JSON logging with `--log-format json|text` and sensitive-field filtering
-- Extended Prometheus metrics: `shell_aa_tx_total`, `shell_key_rotation_total`, `shell_validator_weight`, `shell_consensus_slot_miss`, `shell_evm_gas_used_total`, `shell_snapshot_size_bytes`
+- Extended Prometheus metrics: `shell_aa_tx_total`, `shell_key_rotation_total`, `shell_validator_weight`, `shell_consensus_slot_miss`, `shell_pqvm_gas_used_total`, `shell_snapshot_size_bytes`
 - Admin RPC namespace (`admin_nodeInfo`, `admin_peers`, `admin_addPeer`, `admin_removePeer`, `admin_datadir`); requires `--admin-api` flag (loopback-only by default)
 - Hot backup / restore CLI: `shell-node backup create|restore|schedule`
 
@@ -696,11 +696,11 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 - Upgrade from Shanghai to Cancun EVM specification
-- EIP-2930 access list support in transactions, EVM execution, and RPC
+- EIP-2930 access list support in transactions, PQVM execution, and RPC
 - EIP-4844 basic blob transaction type and gas pricing
 - `debug_traceTransaction` and trace API for transaction debugging
 - Missing standard Ethereum JSON-RPC methods (full eth_* coverage)
-- Comprehensive EVM compatibility verification tests
+- Comprehensive Ethereum tooling compatibility verification tests
 - State pruning with configurable retention policy
 - Batch parallel signature verification with Rayon
 - RLP serialization replacing JSON in chain store for performance
@@ -783,7 +783,7 @@ All notable changes to this project will be documented in this file.
 - PoA consensus engine with pluggable trait
 - Genesis block initialization from config
 - Code storage and PQ public key registry in ChainStore
-- EVM executor with revm integration
+- PQVM executor with revm integration
 - PQ precompiles — disabled `ecrecover`, added Dilithium3 verify
 - Transaction validation pipeline with hybrid pubkey registration
 - JSON-RPC server with `eth_*` and `shell_*` endpoints

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -7,7 +7,7 @@ members = [
     "crates/storage",
     "crates/consensus",
     "crates/genesis",
-    "crates/evm",
+    "crates/pqvm",
     "crates/mempool",
     "crates/rpc",
     "crates/network",
@@ -63,7 +63,7 @@ async-trait = "0.1"
 # --- storage (trie) ---
 eth_trie = "0.4"
 
-# --- evm ---
+# --- pqvm ---
 revm = { version = "36", default-features = false, features = ["std", "optional_no_base_fee", "optional_balance_check"] }
 
 # --- rpc ---

diff --git a/README.md b/README.md
@@ -49,7 +49,7 @@ Accounts are identified by `0x`-prefixed 64-character lowercase hex addresses
 the full 32-byte BLAKE3 hash of `algo_id ‖ public_key`.
 
 At the **canonical layer** (RPC, storage, consensus, signing), addresses are always
-the full 32 bytes. At the **EVM execution boundary**, Shell-Chain maintains a
+the full 32 bytes. At the **revm adapter boundary**, Shell-Chain maintains a
 20-byte mapping layer: `Address::to_alloy()` takes the last 20 bytes of the 32-byte
 canonical address for use with revm, and `Address::from_alloy()` zero-pads left
 back to 32 bytes. This boundary is internal — external callers (SDK, CLI, explorer)
@@ -79,7 +79,7 @@ For the full design and current implementation status, see
 │                    shell-core               │
 │       (Block, Transaction, Account)         │
 ├──────────┬──────────────┼───────────────────┤
-│ shell-evm│ shell-crypto │  shell-storage    │
+│ shell-pqvm│ shell-crypto │  shell-storage    │
 │(PQVM/revm│  (PQ Crypto) │   (RocksDB)      │
 │ adapter) │              │                  │
 ├──────────┴──────────────┴───────────────────┤
@@ -97,7 +97,7 @@ For the full design and current implementation status, see
 | `shell-core` | Block, Transaction (AA-native), Account, Receipt, EIP-1559 gas model |
 | `shell-storage` | RocksDB backend, Merkle Patricia Trie, RLP serialization, state pruning, storage profiles |
 | `shell-consensus` | PoA engine (default); optional wPoA extension: weight-based fork choice, BFT finality, slashing |
-| `shell-evm` | PQVM execution adapter over revm for retained Cancun-style semantics, PQ precompiles, EIP-2930/4844 fields, system contracts |
+| `shell-pqvm` | PQVM execution adapter over revm for retained Cancun-style semantics, PQ precompiles, EIP-2930/4844 fields, system contracts |
 | `shell-mempool` | Transaction pool with PQ validation, fee-priority ordering, Replace-by-Fee |
 | `shell-network` | libp2p P2P: GossipSub, Kademlia DHT, NAT traversal, peer scoring, tx gossip |
 | `shell-rpc` | JSON-RPC (HTTP + WebSocket), CORS, rate limiting, filters, subscriptions, debug/trace APIs |
@@ -117,7 +117,7 @@ shell-chain/
 │   ├── consensus/       # Weighted PoA consensus engine and slashing
 │   ├── core/            # Block, Transaction, Account
 │   ├── crypto/          # Post-quantum cryptography
-│   ├── evm/             # PQVM/revm execution adapter and precompiles
+│   ├── pqvm/             # PQVM/revm execution adapter and precompiles
 │   ├── genesis/         # Genesis configuration
 │   ├── keystore/        # Encrypted key storage
 │   ├── mempool/         # Transaction pool

diff --git a/UPGRADE.md b/UPGRADE.md
@@ -432,7 +432,7 @@ New Prometheus metrics added in v0.13.0:
 | `shell_key_rotation_total` | Counter | PQ key rotations |
 | `shell_validator_weight{address}` | Gauge | Current validator weight |
 | `shell_consensus_slot_miss` | Counter | Empty slots (missed proposer) |
-| `shell_evm_gas_used_total` | Counter | Cumulative gas used |
+| `shell_pqvm_gas_used_total` | Counter | Cumulative gas used |
 | `shell_snapshot_size_bytes` | Gauge | Latest backup snapshot size |
 
 Update your Grafana dashboards by importing the updated JSON from `docker/grafana/`.

diff --git a/blog/why-native-account-abstraction.md b/blog/why-native-account-abstraction.md
@@ -34,10 +34,10 @@ Layer 1: Protocol-level signature check (Dilithium3 or SPHINCS+)
               ↓
 Layer 2: Account-specific validation contract (if set via AccountManager)
               ↓
-Layer 3: EVM execution
+Layer 3: PQVM execution
 ```
 
-The critical difference: validation happens **before** the EVM sees the
+The critical difference: validation happens **before** the PQVM sees the
 transaction. No bundler. No `UserOperation` mempool. No `EntryPoint` contract
 to re-enter. The chain itself is the bundler.
 

diff --git a/config/node.example.toml b/config/node.example.toml
@@ -36,9 +36,10 @@
 # level = "info"    # trace | debug | info | warn | error
 # format = "text"   # text | compact | json
 
-# ── Parallel-EVM scheduler ────────────────────────────────────────────────────
+# ── Parallel-PQVM scheduler ────────────────────────────────────────────────────
 # Enables conflict-graph-based parallel transaction scheduling.
-# Equivalent CLI flags: --parallel-evm  --parallel-evm-workers <N>
-[parallel_evm]
+# Preferred CLI flags: --parallel-pqvm  --parallel-pqvm-workers <N>
+# Deprecated aliases still accepted: --parallel-evm  --parallel-evm-workers <N>
+[parallel_pqvm]
 # enabled = false
 # worker_threads = 4
diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml
@@ -21,7 +21,7 @@ shell-core.workspace = true
 shell-storage.workspace = true
 shell-consensus = { path = "../consensus" }
 shell-genesis = { path = "../genesis" }
-shell-evm = { path = "../evm" }
+shell-pqvm = { path = "../pqvm" }
 shell-mempool = { path = "../mempool" }
 shell-rpc = { path = "../rpc" }
 shell-network = { path = "../network" }

diff --git a/crates/cli/src/commands/run.rs b/crates/cli/src/commands/run.rs
@@ -62,10 +62,10 @@ pub struct RunArgs {
     pub mempool_price_bump: Option<u64>,
     /// Account LRU cache size for the world-state trie, in MiB (default: 64).
     pub state_cache_size_mb: Option<usize>,
-    /// Enable the parallel-EVM conflict-graph scheduler.
-    pub parallel_evm: bool,
-    /// Number of worker threads for the parallel-EVM scheduler (default: logical CPUs).
-    pub parallel_evm_workers: Option<usize>,
+    /// Enable the parallel-PQVM conflict-graph scheduler.
+    pub parallel_pqvm: bool,
+    /// Number of worker threads for the parallel-PQVM scheduler (default: logical CPUs).
+    pub parallel_pqvm_workers: Option<usize>,
     /// Override witness bundle retention from the storage profile.
     /// `0` = keep forever. Omit to use the storage profile default.
     pub witness_retention: Option<u64>,
@@ -658,14 +658,14 @@ async fn run_with_store<S: KvStore + 'static>(
         },
         max_idle_interval_ms: args.max_idle_interval * 1000,
         state_cache_size_mb: args.state_cache_size_mb.unwrap_or(64),
-        parallel_evm: shell_node::config::ParallelEvmConfig {
-            enabled: args.parallel_evm,
-            max_workers: args.parallel_evm_workers.unwrap_or_else(|| {
+        parallel_pqvm: shell_node::config::ParallelPqvmConfig {
+            enabled: args.parallel_pqvm,
+            max_workers: args.parallel_pqvm_workers.unwrap_or_else(|| {
                 std::thread::available_parallelism()
                     .map(usize::from)
                     .unwrap_or(1)
             }),
-            ..shell_node::config::ParallelEvmConfig::default()
+            ..shell_node::config::ParallelPqvmConfig::default()
         },
         enable_stark_aggregation: args.enable_stark_aggregation,
         l2_stark_mode: args
@@ -840,14 +840,14 @@ mod tests {
     use super::*;
     use shell_core::BlockHeader;
     use shell_genesis::initialize_genesis;
-    use shell_node::config::ParallelEvmConfig;
+    use shell_node::config::ParallelPqvmConfig;
     use shell_primitives::{Bytes, U256};
     use shell_storage::{MemoryDb, DEFAULT_BODY_RETENTION, DEFAULT_WITNESS_RETENTION};
     use std::collections::HashMap;
 
-    /// Verify that `--parallel-evm --parallel-evm-workers 4` produces the correct config.
+    /// Verify that `--parallel-pqvm --parallel-pqvm-workers 4` produces the correct config.
     #[test]
-    fn parallel_evm_args_produce_correct_config() {
+    fn parallel_pqvm_args_produce_correct_config() {
         let args = RunArgs {
             datadir: std::path::PathBuf::from("shell-data"),
             rpc_addr: "127.0.0.1:8545".into(),
@@ -875,8 +875,8 @@ mod tests {
             mempool_max_size: None,
             mempool_price_bump: None,
             state_cache_size_mb: None,
-            parallel_evm: true,
-            parallel_evm_workers: Some(4),
+            parallel_pqvm: true,
+            parallel_pqvm_workers: Some(4),
             witness_retention: Some(DEFAULT_WITNESS_RETENTION),
             body_retention: Some(DEFAULT_BODY_RETENTION),
             storage_profile: "full".into(),
@@ -892,16 +892,16 @@ mod tests {
             },
         };
 
-        let expected = ParallelEvmConfig {
-            enabled: args.parallel_evm,
-            max_workers: args.parallel_evm_workers.unwrap(),
-            ..ParallelEvmConfig::default()
+        let expected = ParallelPqvmConfig {
+            enabled: args.parallel_pqvm,
+            max_workers: args.parallel_pqvm_workers.unwrap(),
+            ..ParallelPqvmConfig::default()
         };
 
-        assert!(expected.enabled, "--parallel-evm must set enabled = true");
+        assert!(expected.enabled, "--parallel-pqvm must set enabled = true");
         assert_eq!(
             expected.max_workers, 4,
-            "--parallel-evm-workers 4 must set max_workers = 4"
+            "--parallel-pqvm-workers 4 must set max_workers = 4"
         );
     }