Lux Consensus
SDK

Documentation

Go SDK

The Go SDK is the reference implementation of Lux Consensus, used in production blockchain nodes.

Installation

go get github.com/luxfi/consensus

Quick Start

package main

import (
    "context"
    "fmt"
    "github.com/luxfi/consensus/engine/core"
    "github.com/luxfi/consensus/core/types"
)

func main() {
    // Create engine with default config
    config := core.DefaultConfig()
    engine := core.NewChain(config)

    // Add a block
    block := &types.Block{
        ID: types.ID{1, 2, 3},
        ParentID: types.GenesisID,
        Height: 1,
    }

    ctx := context.Background()
    if err := engine.Add(ctx, block); err != nil {
        panic(err)
    }

    // Vote on the block
    vote := &types.Vote{
        BlockID: block.ID,
        VoteType: types.VotePreference,
    }

    if err := engine.RecordVote(ctx, vote); err != nil {
        panic(err)
    }

    // Check if accepted
    if engine.IsAccepted(block.ID) {
        fmt.Println("Block accepted!")
    }
}

AI-Powered Consensus

The Go SDK includes AI consensus capabilities:

import (
    "github.com/luxfi/consensus/ai"
)

// Create AI agent with neural network model
agent := ai.New[ai.BlockData](
    "node-001",
    model,       // Your AI model implementation
    quasar,      // Quasar consensus engine
    photon,      // Photon emitter for broadcasting
)

// Propose AI-powered decision
decision, err := agent.ProposeDecision(ctx, blockData, context)
if err != nil {
    panic(err)
}

// AI consensus follows photon→quasar flow
// Phase 1: Photon - Emit proposal
// Phase 2: Wave - Broadcast through network
// Phase 3: Focus - Collect votes and converge
// Phase 4: Prism - Validate through DAG
// Phase 5: Horizon - Finalize with quantum certificate

MLX GPU Acceleration

Enable Apple Silicon GPU acceleration for high-throughput consensus:

//go:build mlx
// +build mlx

import (
    "github.com/luxfi/consensus/ai"
)

// Create MLX-accelerated backend
backend, err := ai.NewMLXBackend(32) // batch size
if err != nil {
    log.Fatal(err)
}

// Process votes on GPU
votes := []ai.Vote{
    {VoterID: voterID, BlockID: blockID},
    // ... more votes
}

processed, err := backend.ProcessVotesBatch(votes)
fmt.Printf("Processed %d votes on GPU\n", processed)
fmt.Printf("Throughput: %.0f votes/sec\n", backend.GetThroughput())

Build with MLX support:

# Install MLX Go bindings
go get github.com/luxfi/mlx@latest

# Build with MLX tag
go build -tags mlx ./examples/mlx

# Run
./mlx

Performance (Apple Silicon M1 Max):

  • Batch processing: 25-30x faster than CPU
  • Throughput: 200K+ votes/sec on GPU
  • Automatic GPU/CPU fallback
  • Zero-copy on unified memory

Performance Benchmarks

BenchmarkSimpleModelDecide-10    2032738   1.704 μs/op   912 B/op   18 allocs/op
BenchmarkSimpleModelLearn-10     5993274   618.0 ns/op   2327 B/op  2 allocs/op
BenchmarkFeatureExtraction-10   96700432   37.11 ns/op   0 B/op     0 allocs/op
BenchmarkSigmoid-10            638402244   5.613 ns/op   0 B/op     0 allocs/op

API Reference

Engine Creation

func NewChain(config Config) *ChainEngine
func NewDAG(config Config) *DAGEngine
func NewPQ(config Config) *PQEngine

Block Operations

func (e *Engine) Add(ctx context.Context, block *Block) error
func (e *Engine) Get(id ID) (*Block, error)
func (e *Engine) IsAccepted(id ID) bool
func (e *Engine) Preference() ID

Voting

func (e *Engine) RecordVote(ctx context.Context, vote *Vote) error
func (e *Engine) GetVoteCount(blockID ID) int

Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run benchmarks
go test -bench=. ./...

Examples

See the examples directory for complete examples:

  • 01-simple-bridge - Cross-chain transfer basics
  • 02-ai-payment - AI payment validation
  • 07-ai-consensus - Full AI consensus orchestration
  • mlx/ - MLX GPU acceleration example (requires -tags mlx)