ZK L2 Sequencer for Stellar Mesh Network

A lightweight sequencer for the Stellar ZK L2 mesh network. Designed to run on both servers and mobile devices (with Mopro for native proving).

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MESH NETWORK                              │
│                                                                  │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐      │
│   │   Mobile    │◄───►│   Mobile    │◄───►│   Server    │      │
│   │  (Light)    │ BLE │  (Full+Mopro)│ TCP │  (Full)     │      │
│   └─────────────┘     └─────────────┘     └──────┬──────┘      │
│                                                   │              │
│   Offline mesh continues working                  │ Online       │
│   Proven batches relay to online nodes            ▼              │
│                                           ┌──────────────┐      │
│                                           │  Stellar L1  │      │
│                                           │  (Settlement)│      │
│                                           └──────────────┘      │
└─────────────────────────────────────────────────────────────────┘

Modes

Light Sequencer

• Collects and validates L2 transactions
• Builds batches
• Gossips transactions/batches to peers
• No proof generation - relays to full sequencers
• Runs on any device (very lightweight)

Full Sequencer

• Everything light does PLUS
• Generates Groth16 proofs (settlement circuit)
• Submits proven batches to Stellar L1
• Can use snarkjs (slower) or Mopro (fast native)

Performance

Backend	Platform	Proof Time
Mopro	iOS (iPhone 13)	39-42ms
Mopro	Android	200-800ms
snarkjs	Node.js	3-5 seconds
snarkjs	WASM (browser)	10+ seconds

With Mopro, mobile devices can run full sequencers!

Installation

npm install

Usage

Start a Light Sequencer

npm run start:light

Start a Full Sequencer

npm run start:full

Programmatic Usage

import { Sequencer, createDefaultConfig } from '@lumenbro/zk-sequencer';

// Create a light sequencer
const config = createDefaultConfig('light');
const sequencer = new Sequencer(config);

// Start
await sequencer.start();

// Submit a transaction
await sequencer.submitTransaction({
  id: 'tx-123',
  type: 'transfer',
  senderPubkey: '123...',
  recipientPubkey: '456...',
  assetId: '0',
  amount: '1000000',
  inputCommitment: 'abc...',
  nonce: '1',
  timestamp: Date.now(),
  signature: { r: '...', s: '...' }
});

// Get stats
console.log(sequencer.getStats());

// Stop
await sequencer.stop();

With Mopro (Mobile)

import { Sequencer, createDefaultConfig, MoproBackend } from '@lumenbro/zk-sequencer';
import MoproFfi from 'mopro-ffi';

const config = createDefaultConfig('full');
config.circuitPath = './assets/circuits';

const sequencer = new Sequencer(config);

// Use Mopro for fast native proving
sequencer.setProverBackend(new MoproBackend(MoproFfi));

await sequencer.start();

Gossip Protocol

Sequencers communicate via a gossip protocol supporting multiple transports:

Transport	Use Case	Bandwidth
TCP/WebSocket	Online servers	High
Bluetooth LE	Offline mesh	Low (~247 bytes/msg)
WiFi Direct	Offline, close range	Medium

Message Types

• NEW_TX - Broadcast new transaction
• NEW_BATCH - Broadcast unproven batch
• PROVEN_BATCH - Broadcast proven batch (ready for L1)
• REQUEST_TXS - Request missing transactions
• STATE_SYNC - Synchronize state roots
• PEER_ANNOUNCE - Discover peers

Components

Mempool

Stores pending transactions waiting to be batched.

BatchBuilder

Aggregates transactions into batches based on:

• Max batch size (configurable)
• Timeout (create batch even if not full)

StateManager

Manages L2 state:

• UTXO Merkle tree (Poseidon hashes)
• Nullifier accumulator
• State transitions

Prover

Generates Groth16 proofs using:

• SnarkjsBackend - Universal, slower
• MoproBackend - Native, fast (mobile)

GossipManager

P2P communication with multiple transports.

Configuration

interface SequencerConfig {
  mode: 'light' | 'full';
  sequencerId: string;
  networkId: 'testnet' | 'mainnet';
  maxBatchSize: number;
  batchTimeoutMs: number;
  circuitPath?: string;        // Full mode only
  zkeyPath?: string;           // Full mode only
  settlementContractId: string;
  stellarSecret?: string;      // Full mode only
  gossip: {
    enableBluetooth: boolean;
    enableWifiDirect: boolean;
    tcpPort: number;
    wsPort: number;
    bootstrapPeers: string[];
  };
  storagePath: string;
}

Related Repositories

• lumenbro/Circuits - Circom circuits
• lumenbro/stellar-groth16 - Groth16 verifier library
• lumenbro/zk-l2-settlement - Settlement contract
• lumenbro/zk-bridge - Bridge contract

License

MIT