Lux Docs

Documentation for Lux C++ - High-Performance C++ Libraries for Blockchain description: '### Why LuxCPP?' AI

Overview

LuxCPP is a modular C++ library suite providing GPU-accelerated cryptography, FHE, lattice operations, DEX matching, and networking for the Lux blockchain ecosystem. It consists of 8 componentized libraries with Metal, CUDA, and WebGPU GPU backends, all built via CMake + Conan.

Why LuxCPP?

Multi-backend GPU: Metal (Apple Silicon), CUDA (NVIDIA), WebGPU (Dawn), CPU (SIMD) — compile-time or runtime backend selection
Full FHE stack: TFHE/CKKS/BGV via OpenFHE integration with GPU-accelerated NTT
Post-quantum crypto: BLS12-381 pairings, ML-DSA (Dilithium), lattice-based NTT
DEX engine: C++ CLOB matching engine for sub-microsecond order processing
Zero-copy FFI: C API boundary (lux/gpu.h) for Go, Rust, Python, WASM bindings

Tech Stack

Language: C++20
Build: CMake 3.26+ with Conan 2.x package manager
GPU: Metal (MLX), CUDA (CCCL), Dawn (WebGPU/WGSL)
Version: 1.0.0
License: BSD-3-Clause
Repo: github.com/luxfi/luxcpp

Components

Component	Library	Purpose
`lux-gpu`	`libluxgpu`	GPU compute dispatch (Metal/CUDA/WebGPU/CPU)
`lux-crypto`	`libluxcrypto`	BLS12-381, ML-DSA, secp256k1, hashing
`lux-lattice`	`libluxlattice`	NTT, ring operations, RLWE
`lux-fhe`	`libluxfhe`	TFHE/CKKS/BGV (OpenFHE-based)
`lux-cuda`	`libluxcuda`	CUDA kernels (proprietary)
`lux-http`	`libluxhttp`	HTTP/REST framework
`lux-grpc`	`libluxgrpc`	gRPC services
`lux-dex`	`libluxdex`	DEX matching engine

Dependency Hierarchy

lux-gpu      ← Foundation (cross-platform GPU acceleration)
    ▲
lux-crypto   ← BLS pairings, post-quantum (depends on gpu)
lux-lattice  ← NTT acceleration (depends on gpu)
    ▲
lux-fhe      ← TFHE/CKKS/BGV (depends on crypto + lattice)

When to use

Building GPU-accelerated blockchain operations (ZK proofs, FHE, NTT)
Integrating C++ crypto into Go/Rust services via FFI
Running high-performance DEX matching engines
Accelerating lattice-based post-quantum cryptography
Building cross-platform GPU compute (macOS Metal + Linux CUDA)

Hard requirements

CMake 3.26+ for build
Conan 2.x for dependency management
C++20 compiler (Clang 15+ or GCC 13+)
Metal SDK (macOS) or CUDA Toolkit (Linux/Windows) for GPU backends
Dawn (optional, for WebGPU backend)

Quick reference

Item	Value
Build system	CMake + Conan
Version	1.0.0
License	BSD-3-Clause
C++ standard	C++20
GPU backends	Metal, CUDA, WebGPU (Dawn), CPU (SIMD)
Install prefix	`include/lux/<pkg>/`, `lib/liblux<pkg>.*`
CMake targets	`lux::gpu`, `lux::crypto`, `lux::lattice`, `lux::fhe`
pkg-config	`lux-gpu`, `lux-crypto`, etc.
Repo	`github.com/luxfi/luxcpp`

One-file quickstart

Build all components

# Install dependencies
conan install . --output-folder=build --build=missing

# Configure and build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release
cmake --build .

# Run tests
ctest --test-dir .

Platform-specific profiles

# macOS Apple Silicon (Metal backend)
conan install . -pr:b=default -pr:h=profiles/macos-arm64

# Linux x86_64 (CUDA backend)
conan install . -pr:b=default -pr:h=profiles/linux-x86_64

# Windows x86_64
conan install . -pr:b=default -pr:h=profiles/windows-x86_64

Use from CMake

find_package(lux-gpu REQUIRED)
target_link_libraries(myapp lux::gpu)

find_package(lux-crypto REQUIRED)
target_link_libraries(myapp lux::crypto)

Core Concepts

Directory Structure

luxcpp/
├── gpu/                    # lux-gpu: GPU compute library
│   ├── include/lux/gpu.h   # C API (stable FFI boundary)
│   ├── src/                # Core dispatch, CPU backend, ZK ops
│   ├── webgpu/             # Dawn WebGPU backend + WGSL kernels
│   ├── kernels/cpu/        # CPU kernel implementations
│   ├── benchmarks/         # Performance tests
│   └── test/               # Unit tests
├── crypto/                 # lux-crypto: Cryptographic primitives
├── lattice/                # lux-lattice: NTT, ring operations
├── fhe/                    # lux-fhe: FHE (OpenFHE-based)
├── dex/                    # lux-dex: Matching engine
├── http/                   # lux-http: HTTP/REST
├── grpc/                   # lux-grpc: gRPC services
├── session/                # Session-related C++ components
├── consensus/              # Consensus C++ components
├── cuda/                   # CUDA kernel sources
├── metal/                  # Metal shader sources
├── webgpu/                 # WebGPU/WGSL shader sources
├── lux-accel/              # Umbrella acceleration package
├── lux-cuda/               # CUDA-specific build
├── lux-gpu/                # GPU-specific build
├── lux-metal/              # Metal-specific build
├── lux-webgpu/             # WebGPU-specific build
├── mlx-c-api/              # MLX C API bindings
├── third_party/            # Vendored dependencies
├── cmake/                  # CMake modules
├── profiles/               # Conan build profiles
├── scripts/                # Build & install scripts
├── conanfile.py            # Conan package definition
└── LIBRARY_CONTRACT.md     # Standard layout specification

GPU Backend Selection

The GPU library auto-selects the best available backend at compile time, with runtime fallback:

Backend	Platform	Acceleration
Metal	macOS (Apple Silicon)	MLX integration
CUDA	Linux/Windows (NVIDIA)	CCCL/cuBLAS
Dawn	Cross-platform	WebGPU via WGSL shaders
CPU	All platforms	SIMD (AVX2/NEON) fallback

Install Layout Convention

All libraries follow a canonical install layout:

Headers: include/lux/<pkg>/*.h
Libraries: lib/liblux<pkg>.\{dylib,so,a\}
CMake config: lib/cmake/lux-<pkg>/
pkg-config: lib/pkgconfig/lux-<pkg>.pc

Conan Build Options

# Component toggles
with_gpu=True       # GPU compute
with_fhe=True       # FHE operations
with_crypto=True    # Cryptographic primitives
with_lattice=True   # Lattice crypto
with_dex=True       # DEX matching engine
with_http=True      # HTTP framework
with_grpc=False     # gRPC (opt-in, large dep)

# Backend toggles
with_metal=True     # Metal (macOS)
with_cuda=True      # CUDA (Linux/Windows)
with_webgpu=True    # WebGPU (Dawn)
with_openmp=True    # OpenMP parallelism

# Features
with_tests=False    # Build tests
with_benchmarks=False  # Build benchmarks
embed_kernels=True  # Embed kernel sources in binary

Troubleshooting

Issue	Cause	Solution
Metal not found	Wrong platform	Metal only on macOS with Xcode
CUDA not found	Missing toolkit	Install CUDA Toolkit 12+
Conan errors	Wrong version	Requires Conan 2.x (not 1.x)
Dawn build fails	Missing deps	`git submodule update --init` in Dawn
Link errors	Missing component	Check `find_package(lux-<pkg>)` in CMakeLists

lux/lux-gpu.md — Go bindings for GPU acceleration (wraps this C++ code)
lux/lux-fhe.md — Go FHE library (uses lattice from here)
lux/lux-lattice.md — Go lattice crypto (EPFL, complements C++ NTT)
lux/lux-crypto.md — Go crypto primitives
lux/lux-dex.md — Go/Rust DEX engine (C++ matching core)
lux/lux-accel.md — Rust acceleration (complements C++)

Lux C++ - High-Performance C++ Libraries for Blockchain & AI