Lux Docs

Overview

Lux MPC (mpcd) is a distributed threshold signing service for securely generating and managing cryptographic wallets across MPC nodes -- without ever exposing the full private key. It uses CGGMP21 for ECDSA (secp256k1) and FROST for EdDSA (Ed25519), supporting Bitcoin, Ethereum, XRPL, Solana, TON, and Lux Network.

Quick reference

Item	Value
Module	`github.com/luxfi/mpc`
Go	1.26.1
Binaries	`mpcd` (daemon), `lux-mpc-cli` (tooling)
API Port	8081 (dashboard API), 9651 (consensus transport)
Default Branch	`main`
License	Apache 2.0

Hard requirements

ALWAYS use github.com/luxfi/* packages -- NEVER go-ethereum or luxfi
NEVER store passwords in plaintext -- ZapDB uses ChaCha20-Poly1305 encryption
ALWAYS use CBOR serialization for FROST/LSS configs -- JSON corrupts crypto types

Architecture

mpcd
├── cmd/
│   ├── mpcd/              # Main MPC daemon (consensus-embedded)
│   └── lux-mpc-cli/       # CLI tools for config, keygen, identity
├── pkg/
│   ├── mpc/               # MPC engine (TSS protocols)
│   ├── transport/         # Consensus-embedded transport (ZAP + PoA)
│   ├── client/            # Go client library
│   ├── kvstore/           # ZapDB/BadgerDB encrypted storage
│   ├── identity/          # Ed25519 identity management
│   ├── protocol/          # Protocol session management
│   ├── api/               # Dashboard REST API
│   ├── backup/            # Encrypted backup/restore
│   ├── hsm/               # HSM integration layer
│   ├── kms/               # KMS integration
│   ├── messaging/         # NATS messaging (DEPRECATED)
│   ├── infra/             # Consul integration (DEPRECATED)
│   ├── settlement/        # Settlement attestation
│   ├── smart/             # Smart contract interaction
│   ├── threshold/         # Threshold protocol wrappers
│   ├── encryption/        # Encryption utilities
│   └── txtracker/         # Transaction tracking
├── e2e/                   # End-to-end tests
├── deployments/           # Bridge compatibility deployment
├── k8s/                   # Kubernetes manifests
└── dashboard/             # Dashboard UI

Threshold Scheme

Uses t-of-n threshold signing with t >= floor(n/2) + 1:

n = total MPC nodes (key shares)
t = minimum nodes required to sign
Full private key is never reconstructed

Example (2-of-3): node0 + node1 signs, node0 alone cannot.

Transport Modes

Consensus-Embedded (Recommended)

No external dependencies. Uses ZAP wire protocol with PoA membership:

mpcd start --mode consensus \
  --node-id node0 \
  --listen :9651 \
  --api :9800 \
  --data /data/mpc/node0 \
  --threshold 2 \
  --peer node1@127.0.0.1:9652 \
  --peer node2@127.0.0.1:9653

ZAP message types 60-79 for MPC operations (broadcast, direct, keygen, sign, reshare, result).

Legacy (NATS + Consul) -- DEPRECATED

lux-mpc-cli generate-peers -n 3
lux-mpc-cli register-peers
lux-mpc-cli generate-initiator
mpcd start --mode legacy -n node0

One-file quickstart

Build from source

git clone https://github.com/luxfi/mpc.git
cd mpc
make build
# Or install directly:
go install ./cmd/mpcd
go install ./cmd/lux-mpc-cli

Configuration

# config.yaml
nats:
  url: nats://127.0.0.1:4222
consul:
  address: localhost:8500
mpc_threshold: 2
environment: local
badger_password: "32-byte-password-for-AES-256..."
event_initiator_pubkey: "hex-encoded-ed25519-pubkey"
max_concurrent_keygen: 2
db_path: "."
backup_enabled: true
backup_period_seconds: 300
backup_dir: backups

Go client

    "github.com/luxfi/mpc/pkg/client"
    "github.com/nats-io/nats.go"
)

natsConn, _ := nats.Connect("nats://localhost:4222")
mpcClient := client.NewMPCClient(client.Options{
    NatsConn: natsConn,
    KeyPath:  "./event_initiator.key",
})
mpcClient.OnWalletCreationResult(func(event event.KeygenSuccessEvent) {
    // Handle wallet creation
})
mpcClient.CreateWallet(walletID)

Key Dependencies

github.com/luxfi/threshold@v1.5.5   -- CGGMP21, FROST, LSS protocols
github.com/luxfi/hsm@v1.1.0         -- HSM/KMS integration
github.com/luxfi/crypto@v1.17.40    -- BLS, secp256k1, certificates
github.com/luxfi/database@v1.17.43  -- ZapDB encrypted storage
github.com/luxfi/fhe@v1.7.6         -- FHE primitives
github.com/luxfi/lattice/v7@v7.0.0  -- Post-quantum lattice crypto
github.com/luxfi/log@v1.4.1         -- Structured logging
github.com/hanzoai/orm@v0.3.2       -- ORM for dashboard API
github.com/hanzoai/kv-go/v9         -- Valkey/Redis client

Supported Networks

Network	Curve	Protocol
Bitcoin (Legacy/SegWit)	secp256k1	CGGMP21/LSS
Bitcoin (Taproot)	secp256k1	FROST
Ethereum/EVM	secp256k1	CGGMP21/LSS
XRPL	secp256k1	CGGMP21/LSS
Lux Network	secp256k1	CGGMP21/LSS
Solana	Ed25519	FROST (Taproot mode)
TON	Ed25519	FROST (Taproot mode)

Production Deployment

Namespace: lux-mpc (3 nodes, dashboard API, postgres, valkey)
Storage: ZapDB with ChaCha20-Poly1305 encryption
Dashboard API: Port 8081, enabled via MPC_API_DB env var
Multi-tenancy: One postgres, _entities JSONB table, kind + orgId scoping
Binary distribution: S3 bucket lux-mpc-backups/binaries/

Performance

Operation	Timing
Key Generation	~30s for 3 nodes
Signing	<1s for threshold signatures
Storage per node	~100MB with backups

Testing

# Unit tests
go test ./... -v

# E2E tests
cd e2e && make test

# Coverage
make test-coverage

Troubleshooting

Issue	Cause	Solution
Protocol message corruption	Using JSON for FROST/LSS configs	Use CBOR via `MarshalFROSTConfig()`
Party ID mismatch	Inconsistent ordering	Ensure `GetReadyPeersIncludeSelf()` sorts IDs
NATS topic mismatch	Wrong prefix	Use `mpc.mpc_keygen_result.<walletID>`
Self-message warnings	Normal pub/sub behavior	Ignore "Handler cannot accept message" logs
Session hangs	No timeout on protocol handler	Add context with timeout

lux/lux-threshold.md -- Threshold signature library (CGGMP21, FROST, LSS)
lux/lux-hsm.md -- HSM/KMS integration for key protection
lux/lux-bridge.md -- Bridge integration using MPC signing

Lux MPC - Multi-Party Computation Wallet Service