Lichen Architecture

A technical deep-dive into how Lichen is designed — from network gossip to state commitment. Lichen is an agent-first, high-performance Layer-1 blockchain with WASM smart contracts, on-chain reputation, and a Tendermint-style BFT consensus mechanism.

Overview

Lichen is structured as four distinct layers, each with a clear responsibility boundary. From bottom to top:

Each transaction flows downward through these layers: the Network layer receives it via RPC, Consensus orders it into a block, Execution runs the logic, and State persists the result. This separation allows each layer to be optimized independently.

Tendermint BFT Consensus

Lichen uses Tendermint-style BFT, a leader-based consensus with deterministic finality: Propose → Prevote → Precommit → Commit.

Block Production

Block time targets a continuous 400ms slot cadence. Validators produce liveness blocks even when the mempool is empty, and transaction-bearing blocks use the same slot target.

Leader Selection

Leaders are selected via weighted random sampling where the weight is:

weight = stake_amount × contribution_score

contribution_score = (
    0.4 × uptime_ratio +        // % of slots online (trailing 1000 epochs)
    0.3 × attestation_ratio +   // % of votes cast correctly
    0.2 × block_success_ratio + // % of assigned blocks produced
    0.1 × community_score       // governance participation, bug reports, tooling
)

This means a validator with less stake but excellent uptime and contributions can compete with a larger, less-reliable validator.

PBFT Finality

After a leader proposes a block, it enters a 3-phase PBFT (Practical Byzantine Fault Tolerance) voting round:

1. Pre-prepare — Leader broadcasts the proposed block to all validators
2. Prepare — Validators validate the block and broadcast a prepare vote
3. Commit — Upon receiving 2/3+ prepare votes, validators broadcast a commit vote

A block is considered finalized once 2/3+ of validators (by stake weight) submit commit votes. Under normal network conditions, Lichen targets finality on the 400ms slot cadence.

Canonical Finality Proofs

Every block after height 1 commits its parent's finality proof in an internal versioned consensus transaction. The proof contains a sorted quorum certificate and the complete sorted voting powers for the parent height. The parent header authenticates that denominator through validators_hash, so a validator-set change in the child cannot reinterpret the parent's two-thirds threshold. The certificate also commits the parent's complete post-effects state root. Proposal validation, peer sync, checkpoint verification, archive startup, and getBlockCommit verify the same parent-scoped proof.

Transaction Lifecycle

Every transaction follows a defined path from submission to state commitment:

State Model

Lichen uses an account-based state model (not UTXO). All state is stored in RocksDB, organized into column families for efficient access patterns.

Column Families

Account Structure

Every account on Lichen has the following fields:

pub struct Account {
    /// Native LICN balance in spores (1 LICN = 1e9 spores)
    pub balance: u64,

    /// Transaction sequence number (prevents replay attacks)
    pub nonce: u64,

    /// LichenID reputation score (0.0 – 100.0, stored as u32 * 100)
    pub reputation: u32,

    /// Amount of LICN staked in validator or delegation
    pub staked: u64,

    /// LichenID trust tier (0 = unverified, 1–6 = tier levels)
    pub trust_tier: u8,

    /// If this is a program account, the WASM bytecode hash
    pub program_hash: Option<[u8; 32]>,

    /// Arbitrary account data (up to 10 MB for program accounts)
    pub data: Vec<u8>,

    /// Account owner (system program or deploying program)
    pub owner: Pubkey,
}

WASM Execution

Lichen executes smart contracts using the Wasmer WebAssembly runtime with ahead-of-time (AOT) compilation for near-native performance. Contracts are compiled from Rust to wasm32-unknown-unknown and deployed as program accounts.

Host Functions

Contracts interact with the chain through a set of host functions injected into the WASM environment at runtime:

Gas Metering

Every WASM instruction consumes gas. The runtime injects metering checkpoints at basic block boundaries during AOT compilation. Base costs:

• Arithmetic/logic ops: 1 gas per instruction
• Memory load/store: 3 gas per instruction
• storage_read: 200 gas + 1 gas per byte read
• storage_write: 5,000 gas + 5 gas per byte written (new key) or 200 gas (update)
• emit_event: 375 gas + 8 gas per byte of event data
• cross_contract_call: 2,500 gas base + callee gas

The per-transaction gas limit is 200,000 by default. The per-block gas limit is 50,000,000.

Memory Model

Each contract execution gets an isolated linear memory space starting at 1 page (64 KB) and expandable to 256 pages (16 MB) via memory.grow. Memory is reset between calls — contracts cannot persist state in WASM memory across transactions. Use storage_get/storage_set for persistence.

LichenID Integration

LichenID is Lichen's on-chain identity and reputation layer. It is deeply integrated into the protocol — not just an application-level feature. Trust tiers directly affect transaction processing, fees, and rate limits at the consensus and mempool layers.

Trust Tiers

How Reputation Affects the Stack

• Mempool: All transactions are ordered strictly by fee (highest first), then FIFO for equal fees. Reputation does not affect queue priority.
• Gas Pricing: Higher-tier accounts receive fee discounts applied at the protocol level. A Tier 5 account paying a 0.001 LICN fee effectively pays 0.0009 LICN.
• Rate Limiting: Each account is allowed a maximum number of transactions per epoch (432 slots ≈ ~173 seconds). Exceeding the limit results in mempool rejection until the next epoch.
• Validator Selection: For validators, LichenID score contributes to the community_score component (10% weight) in leader selection.

Privacy & Security

Lichen's privacy architecture is centered on shielded transactions, nullifier-based double-spend prevention, and transparent STARK proofs for note validity. The current implementation uses a Poseidon2- and Plonky3-backed shielded flow in production deployments.

Implementation Status (Current)

Target ZK Architecture

• Proving system: Transparent STARKs (Plonky3/FRI) with no trusted setup
• Field / hash layer: Goldilocks arithmetic plus Poseidon2 hashing
• Commitments: Poseidon2 hash commitments for note value hiding + binding
• Merkle tree: Poseidon2-based tree and inclusion paths for shielded notes
• Nullifiers: Deterministic nullifier derivation to prevent double spends without revealing note contents

Shielded Transaction Flows

• Shield (transparent → shielded): Creates a new note commitment from public funds
• Unshield (shielded → transparent): Spends a note and reveals only the necessary public outputs
• Transfer (shielded → shielded): Consumes note inputs, emits new commitments, preserves value in-circuit

Security Properties

• Zero-knowledge: Proofs validate correctness without exposing note secrets
• Soundness: Invalid witness data cannot satisfy circuit constraints
• Double-spend resistance: One-time nullifier publication prevents note replay
• Value conservation: Circuit constraints enforce that spent and created value balances

Explorer and Docs Separation

Explorer pages are being kept telemetry-first (stats, transactions, nullifier checks). Architecture education and implementation details live in the Website and Developer Portal so chain observability stays cleanly separated from protocol documentation.

Keypair Encryption at Rest

CLI-managed keypairs are encrypted with AES-256-GCM (authenticated encryption with 12-byte random nonce). Encrypted keypair JSON uses encryption_version = 2 for the canonical AES-GCM format.

Faucet CORS Policy

The testnet faucet enforces an explicit origin allowlist (approved development origins + production domains) with restricted HTTP methods (GET/POST/OPTIONS) — replacing the previous permissive policy.

Performance Benchmarks

Benchmarks measured with Criterion.rs on the reference hardware (Apple M-series, single-threaded). Source: core/benches/processor_bench.rs.

Shared PQ runtime bundle: the shipped browser runtime is 44,333 bytes in both monitoring/shared/pq.js and wallet/shared/pq.js, which remains well below the 300-500 KB browser budget tracked in the PQ launch plan.

Network Topology

Lichen's network layer handles peer discovery, data propagation, and client connections.

Gossip Protocol

Nodes communicate over a structured gossip protocol built on libp2p. Every node maintains connections to 8–12 peers. Data propagation uses eager push with lazy pull fallback:

• Eager push: Blocks and high-priority transactions are immediately forwarded to all connected peers
• Lazy pull: Nodes periodically exchange inventory hashes with peers and request any missing data

Average block propagation reaches 95% of nodes within 200ms (for a 1,000-node network).

Peer Discovery

New nodes discover peers through three mechanisms:

1. Bootstrap nodes: Hardcoded seed nodes for initial connection (configurable per network)
2. Peer exchange (PEX): Connected nodes periodically share their known peer lists
3. DHT: A Kademlia-based distributed hash table for decentralized peer lookup

Bootstrap Nodes

# Mainnet bootstrap nodes (QUIC/UDP)
bootstrap_peers = [
    "seed-01.lichen.network:8001",
    "seed-02.lichen.network:8001",
    "seed-03.lichen.network:8001",
]

# Testnet bootstrap nodes (QUIC/UDP)
bootstrap_peers = [
    "seed-01.lichen.network:7001",
    "seed-02.lichen.network:7001",
    "seed-03.lichen.network:7001",
]

Block Sync

When a node falls behind (e.g., after restart or joining late), it uses snapshot sync to catch up efficiently:

1. Download the latest finalized state snapshot (compressed RocksDB checkpoint) from an authenticated peer
2. Verify its post-state root against the child-committed certificate, transaction Merkle proof, signed child header, and historical child finality powers
3. Apply any remaining blocks since the snapshot was created
4. Switch to normal gossip-based block following

Full state snapshots are generated every 1,000 slots (~6.7 minutes) by archive nodes. Typical sync time for a new node is under 2 minutes for testnet.

RPC & WebSocket Endpoints

Every full node exposes two client-facing interfaces:

• JSON-RPC (HTTP POST, default port 8899) — Request/response queries and transaction submission. See API Reference.
• WebSocket (default port 8900) — Persistent subscriptions for real-time block, transaction, and log events. See WebSocket Reference.