consensus/pkg/typescript/README.md

@luxfi/consensus

TypeScript/Node.js bindings for the Lux Consensus SDK.

Native performance through NAPI-RS with full TypeScript type safety.

Features

• Native Performance: Rust-based consensus engine compiled to native Node.js addon
• Type Safety: Full TypeScript definitions for all APIs
• 69% Byzantine Tolerance: Industry-leading fault tolerance (2% above standard 67%)
• 2-round finality API (block time / finality latency not measured for this binding)
• Quantum-Ready: Optional ML-DSA (FIPS 204) post-quantum signatures
• GPU Acceleration: Optional MLX (Apple Silicon) and CUDA support

Installation

npm install @luxfi/consensus
# or
pnpm add @luxfi/consensus
# or
yarn add @luxfi/consensus

Quick Start

import {
  ConsensusEngine,
  testnetConfig,
  VoteType,
  generateBlockId,
} from '@luxfi/consensus';

// Create engine with testnet configuration
const engine = new ConsensusEngine(testnetConfig());
engine.start();

// Create and add a block
const blockId = generateBlockId();
engine.addBlock({
  id: blockId,
  parentId: '00'.repeat(32), // Genesis parent
  height: 1,
  payload: Buffer.from('Hello, Lux!').toString('hex'),
  timestamp: Date.now(),
});

// Register the validators, then vote. Only members are counted, and a node id
// is 20 bytes — 40 hex characters.
const config = testnetConfig();
for (let i = 0; i < 9; i++) {
  const voter = i.toString(16).padStart(40, '0');
  engine.addValidator(voter, 100);
  engine.recordVote({
    blockId: blockId,
    voteType: VoteType.Preference,
    voter: voter,
  });
}

// Check if accepted
console.log('Block accepted:', engine.isAccepted(blockId)); // true

engine.stop();

Configuration

Default Configuration

import { defaultConfig } from '@luxfi/consensus';

const config = defaultConfig();
// {
//   alpha: 20,           // 69% quorum threshold
//   k: 20,               // Sample size
//   maxOutstanding: 10,  // Max concurrent polls
//   maxPollDelayMs: 1000,
//   networkTimeoutMs: 5000,
//   maxMessageSize: 2097152, // 2MB
//   securityLevel: 5,    // NIST Level 5
//   quantumResistant: true,
//   gpuAcceleration: true,
// }

Testnet Configuration

Lower thresholds for development and testing:

import { testnetConfig } from '@luxfi/consensus';

const config = testnetConfig();
// alpha: 5, k: 5, quantumResistant: false, gpuAcceleration: false

Mainnet Configuration

Production settings with full security:

import { mainnetConfig } from '@luxfi/consensus';

const config = mainnetConfig();
// alpha: 20, k: 21, quantumResistant: true, gpuAcceleration: true

API Reference

ConsensusEngine

The main consensus engine class.

class ConsensusEngine {
  constructor(config?: ConsensusConfig);

  start(): void;
  stop(): void;

  addBlock(block: Block): void;
  recordVote(vote: Vote): void;
  recordVotesBatch(votes: Vote[]): number;

  isAccepted(blockId: string): boolean;
  getStatus(blockId: string): BlockStatus;
}

Types

interface Block {
  id: string; // 32-byte hex
  parentId: string; // 32-byte hex
  height: number;
  payload: string; // hex-encoded
  timestamp: number; // Unix ms
}

interface Vote {
  blockId: string;
  voteType: VoteType;
  voter: string; // 20-byte hex — a node id, not a block id
  signature?: string;
}

enum BlockStatus {
  Unknown,
  Processing,
  Rejected,
  Accepted,
}

enum VoteType {
  Preference,
  Commit,
  Cancel,
}

Platform Support

Platform	Architecture	Status
macOS	arm64	✅
macOS	x64	✅
Linux	arm64 (glibc)	✅
Linux	x64 (glibc)	✅
Linux	arm64 (musl)	✅
Linux	x64 (musl)	✅
Windows	x64	✅

Building from Source

# Install dependencies
pnpm install

# Build release
pnpm build

# Build debug
pnpm build:debug

# Run tests
pnpm test

Performance

Not independently benchmarked. This package is a NAPI wrapper around the Rust FFI binding, which itself wraps the C library — it measures data-structure insertion, not consensus. The honest consensus-bound ceiling is the C-FFI rate of ≈21K votes/sec; a wrapper cannot exceed it. Earlier per-second throughput figures here were retracted. See .github/workflows/README.md and the "Honest Assessment" block in LLM.md.

Related Packages

• lux-consensus - Rust SDK
• lux-consensus-py - Python SDK
• libluxconsensus - C SDK

License

MIT License - See LICENSE for details.

Contributing

Contributions are welcome! Please see our Contributing Guide.