Rivellum is a Layer-1 blockchain built on encrypted batch ingress, lane-parallel execution, Aurora BFT consensus, and Proof-of-Useful-Work (PoUW). This document covers the end-to-end architecture.

System Layers

┌──────────────────────────────────────────────────┐
│          Clients & SDKs (TypeScript SDK)          │
├──────────────────────────────────────────────────┤
│   Encrypted Batch Ingress (EncryptedEnvelope)     │
│   Admission Pool → Lane Router → Batchers         │
├──────────────────────────────────────────────────┤
│   Lane-Parallel Execution (Photon Engine)         │
│  ┌────────┬────────┬────────┬────────┐           │
│  │ Lane 0 │ Lane 1 │ Lane 2 │ Lane N │           │
│  │ RocksDB│ RocksDB│ RocksDB│ RocksDB│           │
│  └────────┴────────┴────────┴────────┘           │
├──────────────────────────────────────────────────┤
│   Aurora BFT Consensus (per-Committee)            │
│   Three-phase: Propose → Vote → Commit            │
├──────────────────────────────────────────────────┤
│   PoUW Proof Layer (Winterfell/Plonky2/Halo2)    │
├──────────────────────────────────────────────────┤
│   State Storage (RocksDB + Sparse Merkle Tree)    │
│   WAL + COW Snapshots + MetaRoot Aggregation      │
└──────────────────────────────────────────────────┘

1. Ingress Layer

• Encrypted Envelopes: Intents are encrypted with ChaCha20-Poly1305 before submission — no plaintext mempool
• Admission Pool: Validates envelope structure, checks rate limits, applies backpressure (429 when full)
• Lane Router: Routes envelopes to lanes via blake3(sender) % lane_count
• MEV Elimination: Content is encrypted until the committee decrypts for execution — no front-running possible

2. Execution Layer (Photon)

• Per-Lane Workers: Each lane has a Move VM worker pool processing intents in parallel
• Ordered Apply: Single-threaded per-lane apply ensures deterministic state transitions
• COW Snapshots: Copy-on-write state via Arc<StateSnapshotRef> — O(1) snapshot creation
• Mist Contracts: Produce PVI (Proof-Verified Invocation) graphs verified by the UVL engine

3. Consensus Layer (Aurora BFT)

• Committee Threading: Each committee is an in-process thread group (leader + N workers)
• Three-Phase Commit: Propose → Vote → Commit with quorum certificates (QC)
• Two-Level Finality: Per-lane commit then global MetaRoot aggregation
• BFT Guarantee: Tolerates up to 1/3 Byzantine validators per committee

4. Proof Layer (PoUW)

• Job Tiers: Micro (per-instruction), Macro (per-intent), Full (per-batch)
• Claim-Based Market: External provers run rivellum-pouwd, claim jobs, submit proofs
• ZK Backends: Winterfell (STARKs), Plonky2 (recursive SNARKs), Halo2 (no trusted setup)

5. Storage Layer

• Per-Lane RocksDB: Independent state database per lane
• Sparse Merkle Tree: State commitments with inclusion/exclusion proofs
• WAL: Write-ahead log with CRC32C checksums and configurable fsync policy
• MetaRoot: Global root aggregated from all lane SMT roots

Intent Model

Rivellum uses intents instead of traditional transactions. An intent declares a desired outcome; the protocol handles execution.

Encrypted Envelope

Every intent is submitted as an EncryptedEnvelope:

pub struct EncryptedEnvelope {
    pub envelope_id: EnvelopeId,     // BLAKE3 hash
    pub sender: Address,             // visible for routing
    pub encrypted_payload: Vec<u8>,  // ChaCha20-Poly1305 ciphertext
    pub nonce: u64,                  // replay protection
    pub max_fee: u64,                // fee cap
    pub signature: Signature,        // Dilithium3
}

Key properties:

• No mempool exposure: Payload is encrypted; only sender and fee cap are visible
• Lane routing: blake3(sender) % lane_count determines target lane
• Batch decryption: Committee decrypts just before execution within the consensus round

Intent Lifecycle

Client → EncryptedEnvelope → Admission Pool → Lane Batcher → Sealed Batch
    → Committee Decrypt → Photon Execute → Aurora BFT Consensus → Finalize

1. Submit: Client encrypts intent, signs envelope, POSTs to /v1/submit_envelope
2. Admit: Admission pool validates signature, nonce, fee; routes to lane
3. Batch: Lane batcher seals envelopes into a batch
4. Decrypt: Committee decrypts batch payload
5. Execute: Photon engine runs intents through Move VM workers
6. Consensus: Aurora BFT three-phase commit (QC threshold: >2/3 validators)
7. Finalize: State committed to RocksDB, SMT root updated, MetaRoot aggregated

Intent Kinds

Lanes & Committees

Lanes provide horizontal scalability. Each lane is an independent state partition with its own RocksDB, SMT, and commit pipeline.

Lane Routing

lane_id = blake3(sender_address) % lane_count

• Deterministic: same address always routes to same lane
• Uniform distribution via BLAKE3
• Configurable lane count at genesis

Committee Model

Each committee manages one or more lanes:

Committee 0: [Lane 0, Lane 1]
Committee 1: [Lane 2, Lane 3]
Committee 2: [Lane 4, Lane 5]

• Committees are in-process thread groups, not separate processes
• Each committee has a leader and N executor workers
• Multi-node scaling uses the same committee assignment model

Cross-Lane Transfers (CPC)

When value must move between lanes, the Cross-lane Payment Channel (CPC) protocol ensures atomicity:

1. Debit on source lane (atomic, produces CreditReceipt)
2. Credit on destination lane (consumes receipt, checked by nullifier)
3. CommitCert binds lane state (lane ID, epoch, height, root, quorum signatures)

Invariants: no double-credit (nullifier check), no orphaned debits, no cross-epoch receipt reuse.

Cryptography

All cryptographic primitives are post-quantum:

No classical fallback — every cryptographic operation is post-quantum.

Contract Runtime (Mist / PVI / UVL)

Rivellum executes contracts through the Mist toolchain:

1. Mist: Domain-specific contract language compiled to Value IR with 8-layer conservation engine (MCE)
2. PVI: Proof-Verified Invocation — a DAG of typed value operations produced by contracts
3. UVL: Universal Value Ledger — verifies PVI graph invariants before settlement

Key Properties

• Contracts produce value graphs, not raw state mutations
• 8-layer Mist Conservation Engine enforces value safety at compile time (linear types, value lineage graphs, symbolic amounts, runtime assertion injection)
• 10 UVL invariants verified before any state change
• Move VM provides gas metering and resource safety
• Prefab contracts available for common operations (transfers, NFTs, collections)

API

The node exposes a REST API on the configured HTTP port:

For deeper dives, see:

• Consensus Deep Dive
• PoUW Specification
• Getting Started