fhe/LLM.md

LuxFHE - Fully Homomorphic Encryption Stack

Overview

LuxFHE (github.com/luxfhe) provides a complete FHE stack for Lux blockchain - JavaScript SDKs, Solidity contracts, Go/WASM backends, ML pipelines, and research implementations.

Packages

Package	Mode	Description
@luxfhe/v1-sdk	Standard	Single-key TFHE - simpler, faster for trusted setups
@luxfhe/v2-sdk	Threshold	Network-based TFHE - decentralized decryption
@luxfhe/wasm	Bindings	TFHE WASM bindings (web + node via conditional exports)
@luxfhe/kms	Bindings	KMS bindings (web + node via conditional exports)

Canonical Contracts: FHE contracts are published as part of @luxfi/contracts at ~/work/lux/standard.

@luxfi/contracts/contracts/fhe/     # Canonical FHE contracts location
├── FHE.sol                         # Core FHE library
├── IFHE.sol                        # FHE interface and types
├── FheOS.sol                       # FHE OS precompiles
├── access/                         # Permissioned access control
├── config/                         # Network configuration
├── finance/                        # Vesting, DeFi primitives
├── gateway/                        # Gateway for decryption
├── governance/                     # Confidential voting
├── token/ERC20/                    # Confidential ERC20 tokens
└── utils/                          # Errors, debugging

Sync workflow: Development happens in luxfhe/contracts/, then sync to lux/standard:

cd luxfhe/contracts && pnpm sync  # Syncs to ~/work/lux/standard/contracts/fhe/

Progression: v1 → v2 shows evolution from centralized to decentralized FHE.

Directory Structure

luxfhe/
├── js/                     # JavaScript SDKs
│   ├── v1-sdk/             # @luxfhe/v1-sdk - Standard TFHE
│   ├── v2-sdk/             # @luxfhe/v2-sdk - Threshold TFHE  
│   └── permit/             # Permit handling utilities
│
├── contracts/              # @luxfhe/contracts - Solidity FHE
│   └── contracts/
│       ├── access/         # Access control
│       ├── experimental/   # Experimental features
│       ├── finance/        # DeFi primitives
│       ├── governance/     # Voting/governance
│       ├── token/          # ERC20/721/1155 FHE variants
│       ├── utils/          # Utility contracts
│       ├── FHE.sol         # Core FHE operations
│       ├── FheOS.sol       # FHE OS interface
│       └── IFHE.sol        # FHE types and interface
│
├── core/                   # Core FHE implementations
│   ├── concrete/           # TFHE compiler (Python to FHE)
│   ├── fhevm/              # Full-stack FHEVM framework
│   ├── fhevm-solidity/     # FHEVM Solidity library
│   ├── kms/                # Key Management System (Rust)
│   └── threshold/          # Threshold FHE library (Rust)
│
├── sdk/                    # Additional SDKs
│   ├── relayer/            # Relayer SDK for FHEVM protocol
│   └── fhe/              # CoFHE SDK monorepo
│
├── ml/                     # Machine Learning with FHE
│   ├── torus-ml/           # ML with FHE (Python)
│   ├── biometrics/         # FHE biometrics demo
│   └── extensions/         # Torus ML extensions
│
├── cmd/                    # Command-line applications
│   └── fhed/               # FHE daemon (standalone server)
│
├── go/                     # Go implementations
│   └── tfhe/               # Go TFHE bindings + server
│       └── cmd/            # CLI tools
│
├── wasm/                   # WebAssembly
│   └── tfhe/               # TFHE WASM bindings
│
├── examples/               # 25+ reference implementations
│   ├── blind-auction/      # [v1] Blind auction demo
│   ├── blind-auction-v2/   # [v2] Blind auction (threshold)
│   ├── binary-guessing/    # Binary number guessing game
│   ├── confidential-contracts/ # Confidential contract patterns
│   ├── confidential-voting/ # [v1] Private voting
│   ├── dapps/              # Multi-dapp monorepo
│   ├── demo-v2/            # v2 SDK demo (Nuxt)
│   ├── encrypto/           # Foundry-based FHE examples
│   ├── erc20-tutorial/     # [v1] FHE ERC20 tutorial
│   ├── fhe-voting/         # FHE voting implementation
│   ├── ios-demo/           # iOS FHE demo app
│   ├── kuhn-poker/         # FHE Kuhn poker variant
│   ├── playground/         # [v1] Interactive demo
│   ├── poker/              # [v1] FHE Kuhn poker
│   ├── redact/             # Data redaction example
│   ├── rng-game/           # [v1] Random number guessing
│   ├── rps-game/           # [v2] Rock-paper-scissors
│   ├── secret-santa/       # [v2] Secret Santa
│   ├── smart-wallet/       # [v1] Smart wallet POC
│   ├── ticket-manager/     # Ticket management (Nuxt)
│   ├── ticketing/          # Ticket contracts
│   ├── tickets/            # Ticket UI (Nuxt)
│   └── voting/             # FHE voting demo
│
├── templates/              # Project starters
│   ├── fhevm-hardhat/      # Hardhat + FHEVM
│   ├── foundry/            # Foundry template
│   ├── hardhat/            # Basic hardhat
│   ├── hardhat-starter/    # Hardhat quickstart
│   ├── miniapp/            # Mini-app template
│   ├── next/               # Next.js template
│   ├── nuxt/               # Nuxt.js template
│   ├── react/              # React template
│   ├── scaffold-eth/       # Scaffold-ETH2 + FHE
│   ├── ui/                 # UI component templates
│   └── vue/                # Vue.js template
│
├── plugins/                # Development plugins
│   ├── hardhat/            # Hardhat plugin
│   └── remix/              # Remix IDE plugin
│
├── mocks/                  # Mock contracts for testing
│   ├── fhe/              # CoFHE mock contracts
│   ├── fhevm/              # FHEVM mocks
│   └── foundry/            # Foundry mocks
│
├── research/               # Research implementations
│   ├── acm-threshold/      # ACM threshold paper code
│   ├── ocp-fhe/            # Open compute protocol FHE
│   ├── threshold-paper/    # Threshold FHE benchmarks
│   └── verifiable-fhe/     # Verifiable FHE proofs
│
├── proto/                  # Protocol buffers
│   └── decryption-oracle/  # Decryption oracle protos
│
├── docs/                   # Documentation
│   ├── fhe/              # Threshold FHE docs (Docusaurus)
│   ├── luxfhe/             # Legacy docs
│   ├── resources/          # Awesome FHE resources
│   └── workshop/           # Workshop materials
│
├── tests/                  # Test suites
│   └── fhevm-suite/        # FHEVM test suite
│
├── scaffold-eth/           # Scaffold-ETH2 integration
└── hardhat-plugin/         # Hardhat plugin monorepo

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         JavaScript Applications                         │
├────────────────────────────┬────────────────────────────────────────────┤
│   @luxfhe/v1-sdk           │         @luxfhe/v2-sdk                     │
│   (Standard TFHE)          │         (Threshold TFHE)                   │
│   - Single encryption key  │         - Distributed key shares (t-of-n) │
│   - Key holder decrypts    │         - Network consensus decryption    │
│   - Lower latency          │         - No single point of trust        │
│   - Trusted environments   │         - Public DeFi, trustless apps     │
├────────────────────────────┴────────────────────────────────────────────┤
│                          @luxfhe/contracts                              │
│                    Solidity FHE Smart Contracts                         │
│    FHE.sol · FheOS.sol · token/* · finance/* · governance/*            │
├─────────────────────────────────────────────────────────────────────────┤
│                         Core Components                                  │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐            │
│  │   concrete/    │  │    fhevm/      │  │     kms/       │            │
│  │ TFHE Compiler  │  │ Full Stack VM  │  │ Key Management │            │
│  │   (Python)     │  │   (Solidity)   │  │    (Rust)      │            │
│  └────────────────┘  └────────────────┘  └────────────────┘            │
├─────────────────────────────────────────────────────────────────────────┤
│                    Backend Services                                      │
│  ┌───────────────────────────────┐  ┌───────────────────────────────┐  │
│  │   Go FHE Server               │  │   WASM Bindings               │  │
│  │   ~/work/lux/tfhe/cmd/        │  │   luxfhe/wasm/tfhe            │  │
│  │   /encrypt /decrypt /evaluate │  │   Browser-native FHE          │  │
│  └───────────────────────────────┘  └───────────────────────────────┘  │
├─────────────────────────────────────────────────────────────────────────┤
│                    Cryptographic Foundations                             │
│     github.com/luxfi/tfhe (Pure Go)  ·  github.com/luxfi/lattice       │
└─────────────────────────────────────────────────────────────────────────┘

SDK Comparison

v1-sdk (Standard TFHE)

• Single encryption key
• Key holder performs decryption
• Simpler architecture
• Lower latency
• Best for: Trusted environments, private apps

v2-sdk (Threshold TFHE)

• Distributed key shares (t-of-n)
• Network consensus for decryption
• No single point of trust
• Requires FHE server network
• Best for: Public DeFi, trustless apps

Examples by SDK

v1-sdk examples (single-key):

• blind-auction, confidential-voting, erc20-tutorial
• playground, poker, rng-game, smart-wallet

v2-sdk examples (threshold):

• blind-auction-v2, rps-game, secret-santa, demo-v2

Framework-agnostic (works with both):

• binary-guessing, confidential-contracts, dapps
• encrypto, fhe-voting, ios-demo, kuhn-poker
• redact, ticket-manager, ticketing, tickets, voting

Core Components

concrete/ - TFHE Compiler

Python-to-FHE compiler. Converts Python code with numpy operations into FHE circuits.

• frontends/ - Python frontend
• compilers/ - FHE circuit compilers
• backends/ - Execution backends (CPU, GPU)

fhevm/ - Full-Stack FHEVM

Complete blockchain FHE framework:

• coprocessor/ - FHE coprocessor
• gateway-contracts/ - Gateway smart contracts
• protocol-contracts/ - Protocol layer
• sdk/ - TypeScript SDK
• test-suite/ - Comprehensive tests

kms/ - Key Management System

Rust-based threshold key management:

• core/ - KMS core logic
• core-client/ - Client library
• Docker compose files for centralized/threshold modes

threshold/ - Threshold FHE Library

Rust implementation of threshold TFHE:

• src/ - Core threshold logic
• examples/ - Usage examples
• benches/ - Performance benchmarks

ML with FHE

torus-ml/

Machine learning on encrypted data:

• src/ - Core library
• use_case_examples/ - Real-world ML examples
• benchmarks/ - Performance benchmarks
• docs/ - Comprehensive documentation

biometrics/

FHE biometric verification demo:

• client/ - Client-side processing
• server/ - Server-side FHE operations
• notebooks/ - Jupyter demos

extensions/

Torus-ML extensions:

• rust/ - Rust accelerations
• Additional ML operations

FHE Daemon (fhed)

The fhed daemon provides a standalone FHE server for fully homomorphic encryption operations.

Quick Start

# Install
go install github.com/luxfi/fhe/cmd/fhed@latest

# Start daemon (auto-generates keys on first run)
fhed start --http :8448

# Or with custom data directory
fhed start --http :8448 --data /path/to/keys

# Generate keys separately
fhed keygen --output ./keys --params PN10QP27

Threshold Mode (t-of-n)

# Start in threshold mode with mDNS discovery
fhed start --mode threshold --threshold 2

# Generate 2-of-3 threshold keys
fhed keygen --threshold --t 2 --n 3 --output ./keys

# Reshare to new threshold/parties (LSSS)
fhed reshare --input ./keys --new-t 3 --new-n 5 --output ./reshared

Features

• HTTP API for encrypt/decrypt/evaluate operations
• Automatic key management - generates keys on first start
• Boolean gates - AND, OR, XOR, NOT, NAND, NOR, XNOR, MUX, MAJORITY
• Bit-by-bit encryption - true TFHE with bootstrapping
• Integer support - uint32/uint64 as arrays of encrypted bits
• mDNS discovery - zero-config cluster formation via github.com/luxfi/mdns
• LSSS resharing - add/remove nodes without full key regeneration
• Proactive security - share refresh to invalidate compromised shares

API Endpoints

Endpoint	Method	Description
/v1/fhe/health	GET	Health check with params info
/v1/fhe/publickey	GET	Get public key (hex-encoded)
/v1/fhe/encrypt	POST	Encrypt bit or integer
/v1/fhe/decrypt	POST	Decrypt ciphertext(s)
/v1/fhe/evaluate	POST	Boolean gate evaluation
/v1/fhe/cluster/status	GET	Cluster state (threshold mode)
/v1/fhe/cluster/peers	GET	Discovered peers (threshold mode)
/v1/fhe/cluster/reshare	POST	Trigger reshare (threshold mode)

Parameters

• PN10QP27 (default) - ~128-bit security, good performance
• PN11QP54 - ~128-bit security, higher precision (Q=0x3FFFFFFFFED001, 54-bit prime)
• STD128 - OpenFHE compatible

Example Usage

# Encrypt a bit
curl -X POST http://localhost:8448/v1/fhe/encrypt \
  -H "Content-Type: application/json" \
  -d '{"bit": true}'

# Encrypt an integer
curl -X POST http://localhost:8448/v1/fhe/encrypt \
  -H "Content-Type: application/json" \
  -d '{"uint32": 42}'

# Boolean AND gate
curl -X POST http://localhost:8448/v1/fhe/evaluate \
  -H "Content-Type: application/json" \
  -d '{"operation": "and", "operands": ["<ct1>", "<ct2>"]}'

# Check cluster status (threshold mode)
curl http://localhost:8448/v1/fhe/cluster/status

mDNS Discovery Package

Zero-config peer discovery for local networks: github.com/luxfi/mdns

import "github.com/luxfi/mdns"

// Create discovery
disc := mdns.New("_fhed._tcp", "node-1", 8448,
    mdns.WithMetadata(map[string]string{"version": "1.0"}),
)

// Handle peer events
disc.OnPeer(func(peer *mdns.Peer, joined bool) {
    if joined {
        fmt.Printf("Peer: %s at %s\n", peer.NodeID, peer.Address())
    }
})

// Start/stop
disc.Start()
defer disc.Stop()

// Query peers
for _, peer := range disc.Peers() {
    fmt.Println(peer.NodeID, peer.Get("version"))
}

Used by: fhed, mpcd, and other Lux daemons for local cluster formation.

Go & WASM

go/tfhe/

Go bindings for TFHE with FHE server:

• cmd/ - CLI tools and server
• internal/ - Internal implementations
• libtfhe-wrapper/ - C FFI bindings
• wasm-cmd/ - WASM generation tools

wasm/tfhe/

Browser-native FHE via WebAssembly:

• wasm-code/ - Core WASM code
• wasmer/ - Wasmer runtime
• scripts/ - Build scripts

Research

ocp-fhe/

Open Compute Protocol for FHE - decentralized compute network:

• chain/ - Blockchain integration
• demo-frontend/ - Demo UI
• ocf/ - OCF implementation

threshold-paper/

Academic threshold TFHE paper implementation:

• benchmarks/ - Performance data
• src/ - Reference implementation

verifiable-fhe/

Verifiable FHE proofs - proving correct FHE computation:

• src/ - Proof generation/verification

Quick Start

# Install SDK
pnpm add @luxfhe/v2-sdk  # or @luxfhe/v1-sdk

# Install contracts
pnpm add @luxfhe/contracts

import { createFheClient } from '@luxfhe/v2-sdk'

const client = await createFheClient({
  provider: window.ethereum,
  networkUrl: 'https://fhe.lux.network'
})

// Encrypt a value
const encrypted = await client.encrypt_uint32(42)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "@luxfhe/contracts/FHE.sol";

contract ConfidentialToken {
    mapping(address => euint32) private _balances;
    
    function transfer(address to, euint32 amount) external {
        _balances[msg.sender] = FHE.sub(_balances[msg.sender], amount);
        _balances[to] = FHE.add(_balances[to], amount);
    }
}

Backend (Go)

The FHE server lives at ~/work/lux/tfhe:

• cmd/fhe-server/ - HTTP server for FHE operations
• Supports both standard and threshold modes
• Endpoints: /encrypt, /decrypt, /evaluate, /publickey

Development

Building Examples

cd examples/playground
pnpm install
pnpm dev

Running Tests

# Contracts
cd contracts && pnpm test

# SDK
cd js/v2-sdk && pnpm test

# Core
cd core/fhevm && npm test

Using Templates

# Hardhat project
cp -r templates/hardhat my-fhe-project
cd my-fhe-project
pnpm install

# Next.js frontend
cp -r templates/next my-fhe-frontend
cd my-fhe-frontend
pnpm install && pnpm dev

Native luxd Integration (2024-12-31)

Architecture

The goal is for FHE to work natively with luxd --dev mode, eliminating the need for separate Docker containers:

luxd (single node, --dev mode)
├── C-Chain (EVM)
│   └── FHE Precompiles (precompiles/fhe/)
│       - FHEAdd, FHESub, FHEMul, FHEDiv, FHERem
│       - FHEEq, FHELt, FHEGt, FHELe, FHEGe
│       - FHEAnd, FHEOr, FHEXor, FHENot
│       - TrivialEncrypt, VerifyCiphertext
│       - Decrypt, Reencrypt
│
└── T-Chain (ThresholdVM)
    └── FHE RPC Service (vms/thresholdvm/fhe/)
        - GetPublicParams
        - RegisterCiphertext
        - RequestDecrypt / GetDecryptResult
        - CreatePermit / VerifyPermit

SDK Connection

The @luxfhe/sdk currently connects to a standalone FHE server at localhost:8448. For native luxd:

• SDK should connect to luxd's RPC endpoint
• T-Chain provides FHE services via JSON-RPC at /ext/bc/T/rpc

Unified FHE API (2025-01-01)

One way to do everything - no backwards compatibility, forward perfection.

Decryption Pattern

// Step 1: Request async decryption
FHE.decrypt(encryptedValue);

// Step 2: Get result when ready
bool result = FHE.reveal(encryptedValue);         // Reverts if not ready
(bool result, bool ready) = FHE.revealSafe(encryptedValue);  // Safe version

Precompile Interface (IFHEDecrypt @ 0x0200...0083)

function decrypt(bytes32 handle, uint8 ctType) external returns (bytes32 requestId);
function reveal(bytes32 requestId) external view returns (bytes memory result, bool ready);

Examples Status (2025-01-01)

✅ All Compiling (unified API):

• binary-guessing, blind-auction, blind-auction-v2
• confidential-contracts, confidential-voting
• rng-game, rps-game, secret-santa, voting

⚠️ Not using @luxfi/contracts:

• dapps/ - Uses @fhevm/solidity (lux's library)
• poker/, kuhn-poker/ - Custom implementation
• ticketing/, tickets/ - Package manager issues

Key Dependencies

Package	Version	Purpose
@luxfi/contracts	1.4.0	Solidity FHE library
@luxfhe/sdk	0.5.0	JavaScript SDK

Licenses

All code uses permissive licenses:

• MIT - Most components
• BSD-3-Clause - LuxFHE-derived code
• Apache-2.0 - Some Rust components

Key Files

Path	Purpose
contracts/contracts/FHE.sol	Core FHE operations
js/v2-sdk/src/index.ts	v2 SDK entry point
js/v1-sdk/src/index.ts	v1 SDK entry point
core/fhevm/sdk/	FHEVM TypeScript SDK
core/kms/core/	KMS core logic
go/tfhe/cmd/	Go FHE server
ml/torus-ml/src/	ML with FHE

NTT (Go side, ntt_simd.go + ntt_gpu.go)

fhe.NTTEngine wraps a cached subring.SubRing keyed by (N, Q). Two API tiers:

Method	Path
NTTInPlace(coeffs) / INTTInPlace(coeffs)	Single polynomial, CPU subring.
NTTBatch(polys) / INTTBatch(polys)	Batch dispatch — luxfi/lattice/v7/gpu (Metal/CUDA) when gpu.GPUAvailable() AND the engine's (N,Q) passes byte-equality probe; otherwise per-poly CPU.
GPUNTTAvailable()	Reports whether the GPU path serves this engine.

CGo is the only build-tag axis. The byte-equality probe runs once per (N, Q) and caches the result — a GPU context that disagrees with the CPU oracle is rejected (never silently dispatched).

Tests: ntt_gpu_test.go::TestNTTBatch_ByteEqualToInPlace, TestINTTBatch_RoundTrip.