Architecture

Makechain uses a layered architecture with single-chain Simplex BFT consensus, parallel per-project execution, and a separate data availability layer.

System Overview

┌─────────────────────────┐
│  Clients                │  grpc-web / gRPC
│  (Browser, CLI, SDK)    │
└───────────┬─────────────┘
            │
┌───────────▼──────────────────────────────────────┐
│  Validator Node                                   │
│                                                   │
│  ┌──────────┐  ┌──────────────┐  ┌────────────┐  │
│  │ gRPC API │→ │ Mempool      │→ │ Execution  │  │
│  │ (tonic)  │  │              │  │ Engine     │  │
│  └──────────┘  └──────┬───────┘  └─────┬──────┘  │
│                       │                │          │
│               ┌───────▼────────────────▼───────┐  │
│               │ Simplex BFT (single chain)     │  │
│               │ ~200ms blocks, ~300ms finality  │  │
│               └───────────────┬────────────────┘  │
│                               │                   │
│               ┌───────────────▼────────────────┐  │
│               │ State Engine (MemoryStore)      │  │
│               │ Prefix-namespaced key-value     │  │
│               └────────────────────────────────┘  │
└───────────────────────────────────────────────────┘

Layers

Message Layer

Every message is a self-authenticating envelope containing a BLAKE3 hash, Ed25519 signature, and the signer's public key. Messages are structurally validated before entering the mempool.

Consensus Layer

A single Simplex BFT consensus chain orders all messages. The leader proposes blocks by draining the mempool, and the execution engine processes them in two phases:

Account pre-pass — KEY_ADD, KEY_REMOVE, ACCOUNT_DATA, VERIFICATION_ADD/REMOVE, PROJECT_CREATE, PROJECT_REMOVE, and FORK are applied serially (they modify shared account state like project count)
Parallel project execution — Remaining project-scoped messages are grouped by project_id and executed in parallel via rayon, each with its own copy-on-write overlay store

This single-chain model with parallel execution achieves high throughput without the complexity of cross-shard coordination.

State Layer

State is stored in a prefix-namespaced key-value store with lexicographic ordering for range scans:

Prefix	Namespace
`0x01`	Project state
`0x02`	Project metadata
`0x03`	Refs
`0x04`	Commits
`0x05`	Collaborators
`0x06`	Account state
`0x07`	Account metadata
`0x08`	Key entries
`0x09`	Verifications
`0x0A`	Project name index
`0x0B`	Key reverse index (pubkey → mid)

Currently backed by an in-memory BTreeMap (MemoryStore). The StateStore trait is designed for future migration to QMDB (Queryable Merkle Database) for persistence and merkle proofs.

Data Availability Layer

The consensus layer stores only message metadata (~100-500 bytes). File content (blobs, trees) lives in a separate DA layer, referenced by da_reference in commit bundles.

Commonware Primitives

Makechain builds on the Commonware Library:

Primitive	Usage
`commonware-consensus`	Simplex BFT consensus engine
`commonware-p2p`	Authenticated peer connections
`commonware-parallel`	Execution strategies (Sequential, Rayon)
`commonware-runtime`	Async task execution (tokio backend)
`commonware-cryptography`	Ed25519 signing, BLAKE3 digests
`commonware-codec`	Binary serialization

gRPC API

The node exposes a gRPC service on port 50051 (configurable) with:

grpc-web support — browser clients via HTTP/1.1 (tonic-web)
CORS — configured for cross-origin grpc-web requests
Server reflection — runtime service discovery (grpc reflection v1)
Message streaming — SubscribeMessages with type and project_id filters