Architecture#

Shell Chain is built as a modular Rust workspace with 12 independent crates. Each crate owns a single responsibility, enabling clean dependency boundaries, parallel compilation, and straightforward testing.

Dependency Layers#

┌─────────────────────────────────────────────────────┐
│                    shell-cli                         │  ← Binary entry point
│                    shell-node                        │  ← Async node harness
├──────────┬──────────┬───────────┬───────────────────┤
│ shell-rpc│shell-net │shell-pool │ shell-consensus    │  ← Service layer
│ (JSON-RPC)│ (libp2p)│ (mempool) │ (PoA engine)      │
├──────────┴──────────┴───────────┴───────────────────┤
│                    shell-evm                         │  ← Execution layer
│              (revm + PQ precompiles)                 │
├─────────────────────────────────────────────────────┤
│                   shell-storage                      │  ← Persistence layer
│            (RocksDB + Merkle Patricia Trie)          │
├──────────────────────┬──────────────────────────────┤
│     shell-core       │       shell-keystore          │  ← Domain layer
│ (Block, Tx, Account) │   (PQ keystore, argon2id)     │
├──────────────────────┴──────────────────────────────┤
│    shell-crypto      │      shell-primitives         │  ← Foundation layer
│ (Dilithium, SPHINCS+)│  (H256, Address, U256, etc.)  │
└──────────────────────┴──────────────────────────────┘

Higher layers depend on lower layers. No circular dependencies exist.

Crate Reference#

CrateDescription
shell-primitivesCore types: Keccak-256, BLAKE3 hashing, H256, Address, U256, Bytes. Every other crate depends on this.
shell-cryptoPost-quantum signing via CRYSTALS-Dilithium (ML-DSA) and SPHINCS+ (SLH-DSA). Wraps pqcrypto with an ergonomic API.
shell-coreDomain models — Block, Transaction (account-abstraction native), Account, Receipt. Defines the canonical chain types.
shell-keystoreEncrypted PQ keystore. Private keys are protected with argon2id key derivation and AES-256-GCM.
shell-storageRocksDB-backed persistence with a Merkle Patricia Trie for state proofs. Provides StateDB and ChainDB traits.
shell-evmEVM execution powered by revm (Cancun spec). Adds custom precompiles for PQ signature verification.
shell-consensusEpoch-based Proof-of-Authority engine with a finality tracker. Manages validator sets and block sealing.
shell-mempoolTransaction pool with PQ signature validation, nonce ordering, and gas-price priority queues.
shell-networkPeer-to-peer networking via libp2p. Uses GossipSub for block/tx propagation and Kademlia DHT for peer discovery.
shell-rpcJSON-RPC server (HTTP + WebSocket) exposing Ethereum-compatible endpoints plus Shell Chain extensions.
shell-nodeAsync node harness that wires every subsystem together. Handles block production, sync, and graceful shutdown.
shell-cliCLI binary. Parses TOML configuration, initializes logging, and launches the node.

Data Flow#

Transaction Lifecycle#

  1. Submission — A client sends a signed transaction via shell-rpc (eth_sendRawTransaction).
  2. Validation — shell-mempool verifies the PQ signature using shell-crypto, checks the nonce against shell-storage, and inserts the transaction into the priority queue.
  3. Propagation — shell-network broadcasts the transaction to peers via GossipSub.
  4. Inclusion — When it is the validator's turn, shell-consensus selects transactions from the mempool and passes them to shell-evm for execution.
  5. Execution — shell-evm runs each transaction against the state trie, producing receipts and state diffs.
  6. Sealing — shell-consensus assembles the block, and the validator signs it with their PQ key.
  7. Storage — shell-storage persists the block, receipts, and updated state trie to RocksDB.
  8. Finality — The finality tracker in shell-consensus marks the block as finalized after sufficient attestations.

Block Sync#

When a new node joins the network:

  1. shell-network discovers peers via Kademlia DHT.
  2. The node requests block headers and bodies from peers.
  3. shell-evm re-executes each block to verify state transitions.
  4. shell-storage commits verified state to RocksDB.

Build & Test#

# Build the entire workspace
cargo build --release

# Run all tests
cargo test --workspace

# Run a specific crate's tests
cargo test -p shell-evm

# Build only the CLI binary
cargo build --release -p shell-cli

Directory Layout#

shell-chain/
├── crates/
│   ├── shell-primitives/
│   ├── shell-crypto/
│   ├── shell-core/
│   ├── shell-keystore/
│   ├── shell-storage/
│   ├── shell-evm/
│   ├── shell-consensus/
│   ├── shell-mempool/
│   ├── shell-network/
│   ├── shell-rpc/
│   ├── shell-node/
│   └── shell-cli/
├── docs/
├── config/
└── Cargo.toml          # Workspace manifest