luxfi/fhe

Fork 0

mirror of https://github.com/luxfi/fhe.git synced 2026-07-27 07:24:44 +00:00

Files

T

Hanzo AI 5f82c63695 fix: all routes under /v1/fhe/* — canonical path pattern

2026-04-09 17:46:41 -07:00

21 KiB

Raw Permalink Blame History

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

21 KiB Raw Permalink Blame History

LuxFHE - Fully Homomorphic Encryption Stack

Overview

Packages

Directory Structure

Architecture

SDK Comparison

v1-sdk (Standard TFHE)

v2-sdk (Threshold TFHE)

Examples by SDK

Core Components

concrete/ - TFHE Compiler

fhevm/ - Full-Stack FHEVM

kms/ - Key Management System

threshold/ - Threshold FHE Library

ML with FHE

torus-ml/

biometrics/

extensions/

FHE Daemon (fhed)

Quick Start

Threshold Mode (t-of-n)

Features

API Endpoints

Parameters

Example Usage

mDNS Discovery Package

Go & WASM

go/tfhe/

wasm/tfhe/

Research

ocp-fhe/

threshold-paper/

verifiable-fhe/

Quick Start

Backend (Go)

Development

Building Examples

Running Tests

Using Templates

Native luxd Integration (2024-12-31)

Architecture

SDK Connection

Unified FHE API (2025-01-01)

Decryption Pattern

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

Examples Status (2025-01-01)

Key Dependencies

Licenses

Key Files

21 KiB

Raw Permalink Blame History