Lux Docs
Lux Skills Reference

Lux Crypto

Cryptographic Primitives

Overview

Lux Crypto provides the complete cryptographic foundation for the Lux Network. It covers classical (secp256k1, ECDSA, BLS12-381), post-quantum (ML-DSA, SLH-DSA, ML-KEM, Lamport), hybrid key encapsulation, ring signatures, threshold signature schemes (FROST, CMP, BLS, Ringtail), MPC protocols, HPKE, ECIES, KZG polynomial commitments, and EVM crypto precompiles. All post-quantum algorithms use Cloudflare CIRCL under the hood.

Quick Reference

ItemValue
Modulegithub.com/luxfi/crypto
Go1.26.1

Key Dependencies

DependencyVersionPurpose
github.com/supranational/blstv0.3.16BLS12-381 (CGO, fast path)
github.com/cloudflare/circlv1.6.3PQ crypto: ML-DSA, SLH-DSA, ML-KEM, BLS (non-CGO), HPKE
github.com/consensys/gnark-cryptov0.19.2ZK-friendly crypto, BN256
github.com/crate-crypto/go-eth-kzgv1.5.0KZG polynomial commitments (Go)
github.com/ethereum/c-kzg-4844/v2v2.1.5KZG polynomial commitments (C)
filippo.io/agev1.3.1File encryption (age format)
github.com/ProjectZKM/ZirenlatestZK runtime (Keccak)
github.com/zeebo/blake3v0.2.4BLAKE3 hashing
github.com/luxfi/idsv1.2.9ID types
github.com/jedisct1/go-minisignlatestMinisign verification
github.com/leanovate/gopterv0.2.11Property-based testing

Package Map

Classical Signatures

PackageImportPurpose
bls/github.com/luxfi/crypto/blsBLS12-381 signatures. Dual backend: CGO (blst, bls_c.go) and pure-Go (circl, bls.go). Types: SecretKey, PublicKey, Signature, AggregatePublicKey, AggregateSignature. Functions: NewSecretKey(), SecretKeyFromSeed(), SecretKeyFromBytes(), SecretKeyToBytes(), Sign(), Verify(). Domain separation: BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_ (signing), BLS_POP_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_ (proof of possession).
bls/signer/.../bls/signerBLS signer interface
bls/blstest/.../bls/blstestBLS test helpers
bls12381/.../bls12381BLS12-381 pairing engine -- dual backend: blst (CGO) and gnark-crypto (pure Go)
secp256k1/.../secp256k1Ethereum-compatible ECDSA: key generation, signing, recovery, address derivation. Includes CGO (secp256k1_c.go, scalar_mult_c.go) and pure-Go (secp256k1.go) paths. Recovery cache for performance.
secp256r1/.../secp256r1P-256 (NIST) curve verifier
bn256/.../bn256BN256 pairing: fast (gnark) and slow (cloudflare/google) backends
signer/.../signerGeneric signer interface with test suite
signify/.../signifyMinisign-compatible signature verification

Post-Quantum Signatures (FIPS 204/205)

PackageImportModesSizes
mldsa/.../mldsaML-DSA-44 (128-bit, NIST L2), ML-DSA-65 (192-bit, NIST L3), ML-DSA-87 (256-bit, NIST L5)PK: 1312/1952/2592, SK: 2560/4032/4896, Sig: 2420/3309/4627 bytes
slhdsa/.../slhdsaSLH-DSA (FIPS 205, SPHINCS+): 12 modes -- SHA2/SHAKE x 128s/128f/192s/192f/256s/256fPK: 32/48/64, Sig: 7856-49856 bytes (small vs fast variants)

ML-DSA API: GenerateKey(rand, mode), PrivateKey.Sign(rand, msg, opts), PublicKey.Verify(msg, sig, opts), PublicKey.VerifySignature(msg, sig), PrivateKeyFromBytes(mode, data), PublicKeyFromBytes(data, mode).

SLH-DSA API: identical interface. Deterministic signing via slhdsa.SignDeterministic. 12 modes cover SHA2/SHAKE at 128/192/256-bit security with small (s) or fast (f) signing.

Post-Quantum Key Encapsulation (FIPS 203)

PackageImportPurpose
mlkem/.../mlkemML-KEM (FIPS 203): ML-KEM-512 (128-bit), ML-KEM-768 (192-bit), ML-KEM-1024 (256-bit). Full encapsulate/decapsulate with CGO optimization. PK: 800/1184/1568, SK: 1632/2400/3168, CT: 768/1088/1568 bytes.
kem/.../kemKEM factory: GetKEM(id) returns implementation. IDs: MLKEM768, MLKEM1024, X25519, HybridKEM (x25519+mlkem768). Interface: GenerateKeyPair(), Encapsulate(pk), Decapsulate(sk, ct).
kem/hybrid.../kemHybrid KEM combining X25519 + ML-KEM-768 for PQ-safe key exchange

Hash-Based Signatures

PackageImportPurpose
lamport/.../lamportLamport one-time signatures. Hash functions: SHA256, SHA512, SHA3-256, SHA3-512. GenerateKey(rng, hashFunc), PrivateKey.Public(), Sign(), Verify(). SHA256: PK 16KB, Sig 8KB.

Ring Signatures

PackageImportSchemes
ring/.../ringLSAG (Linkable Spontaneous Anonymous Group, secp256k1), LatticeLSAG (post-quantum, Module-LWE), DualRing (efficient ring construction). Key image support for double-spend prevention. Used in Q-Chain for private transactions.

Threshold Signatures

PackageImportPurpose
threshold/.../thresholdUnified interface for 4 threshold schemes. Interface: Scheme, DKG, TrustedDealer, Signer, Aggregator, Verifier, KeyRefresh, Resharing.
threshold/bls/.../threshold/blsBLS threshold signatures (non-interactive aggregation)

Threshold schemes:

SchemeIDNameTypePQ-SafeNon-Interactive
SchemeFROSTFROSTSchnorr threshold (Ed25519-compatible)NoNo
SchemeCMPCMP/CGGMP21Threshold ECDSANoNo
SchemeBLSBLSBLS thresholdNoYes
SchemeRingtailRingtailLattice-based thresholdYesNo

DKG protocol: up to 3 rounds (Round1 -> broadcast -> Round2 -> broadcast -> Round3 -> KeyShare). Also supports TrustedDealer for centralized setup.

MPC (Multi-Party Computation)

PackageImportPurpose
mpc/.../mpcPer-account MPC management. Protocols: ProtocolGG18, ProtocolGG20, ProtocolCMP. Manager handles account-to-MPC mapping. Shamir secret sharing with configurable threshold/parties.
cggmp21/.../cggmp21CGGMP21 threshold ECDSA with Paillier encryption

Aggregated Signatures

PackageImportPurpose
aggregated/.../aggregatedSignature aggregation managers: multi-signature aggregation for consensus

Encryption

PackageImportPurpose
ecies/.../eciesElliptic Curve Integrated Encryption Scheme (ECIES) -- asymmetric encryption
hpke/.../hpkeHybrid Public Key Encryption (RFC 9180). KEMs: P-256/P-384/P-521/X25519. KDFs: HKDF-SHA256/384/512. AEADs: AES-128-GCM/AES-256-GCM/ChaCha20-Poly1305.
aead/.../aeadAuthenticated Encryption with Associated Data utilities
encryption/.../encryptionFile encryption using filippo.io/age

Hashing

PackageImportPurpose
hash/.../hashUnified hash interface: Hasher, SHA256, SHA256File(). Mock hasher for testing.
hash/blake3/.../hash/blake3BLAKE3 hashing
hash/poseidon2/.../hash/poseidon2Poseidon2 ZK-friendly hash
hash/consistent/.../hash/consistentConsistent hashing (ring-based distribution)
hashing/.../hashingLegacy hashing interface
blake2b/.../blake2bBLAKE2b with AVX2 acceleration
keccak.gorootKeccak-256 (Ethereum standard)
keccak_ziren.gorootKeccak via Ziren ZK runtime
kdf/.../kdfKey Derivation Function schedule

Polynomial Commitments & ZK

PackageImportPurpose
kzg4844/.../kzg4844KZG polynomial commitments for EIP-4844 blobs. Dual backend: C (ckzg) and Go (gokzg). BlobToCommitment(), ComputeProof(), VerifyProof().
ipa/.../ipaInner Product Argument (IPA) multiproofs for Verkle trees. Bandersnatch/Banderwagon curves.

EVM Precompiles

PackageImportPurpose
precompile/.../precompilePost-quantum EVM precompiles: BLS verification, Lamport verification, SHAKE hashing. Interface: Precompile with Run(input). Exported via precompile/export.go.

Encoding & Utilities

PackageImportPurpose
cb58/.../cb58CB58 encoding (Base58Check, used for Lux addresses)
common/.../commonAddress (20 bytes), Hash (32 bytes), hex utilities
rlp/.../rlpRLP encoding for EVM compatibility
address/.../addressAddress formatting and conversion
bitutil/.../bitutilBit manipulation utilities
certificate.gorootTLS certificate handling
random.gorootCryptographic random number generation
gpu/.../gpuGPU acceleration stubs
cgo/.../cgoCGO linking configuration for C crypto libs

Foreign Language Bindings

BindingPathPurpose
C ABIbindings/cabi/C foreign function interface
Pythonbindings/python/Python bindings
Rustbindings/rust/Rust FFI bindings
TypeScriptbindings/typescript/TypeScript/WASM bindings

Data Availability

PackageImportPurpose
da/.../daData availability layer types

Verkle Trees

PackageImportPurpose
verkle/.../verkleVerkle tree cryptographic primitives

Key Hierarchy (Lux Consensus)

Key TypePackageUsage
ed25519(stdlib)Node identity
BLS12-381bls/Fast finality signatures (Quasar)
Lattice (ML-DSA)mldsa/Post-quantum finality certificates
secp256k1 + Lamportsecp256k1/, lamport/EVM wallet signing (PQ-safe)
secp256k1 + ML-DSAsecp256k1/, mldsa/X-Chain UTXO signing (PQ-safe)
ML-KEM + X25519kem/PQ-safe key exchange (hybrid)

API Examples

BLS Signatures


sk, _ := bls.NewSecretKey()
pk := sk.PublicKey()

msg := []byte("transaction data")
sig := bls.Sign(sk, msg)
valid := bls.Verify(pk, msg, sig)

ML-DSA (Post-Quantum Signatures)

    "crypto/rand"
    "github.com/luxfi/crypto/mldsa"
)

// NIST Level 5 (256-bit security)
sk, _ := mldsa.GenerateKey(rand.Reader, mldsa.MLDSA87)
sig, _ := sk.Sign(rand.Reader, message, nil)
valid := sk.PublicKey.VerifySignature(message, sig)

// Serialize/deserialize
skBytes := sk.Bytes()
sk2, _ := mldsa.PrivateKeyFromBytes(mldsa.MLDSA87, skBytes)

SLH-DSA (Stateless Hash-Based Signatures)


// 256-bit security, small signatures
sk, _ := slhdsa.GenerateKey(rand.Reader, slhdsa.SHA2_256s)
sig, _ := sk.Sign(rand.Reader, message, nil) // 29792 bytes
valid := sk.PublicKey.VerifySignature(message, sig)

ML-KEM (Post-Quantum Key Exchange)


k, _ := kem.GetKEM(kem.HybridKEM) // X25519 + ML-KEM-768
pk, sk, _ := k.GenerateKeyPair()
ct, sharedSecret, _ := k.Encapsulate(pk)
recovered, _ := k.Decapsulate(sk, ct)
// sharedSecret == recovered

Ring Signatures (Q-Chain Privacy)


// LSAG: linkable anonymous group signature
// LatticeLSAG: post-quantum ring signature
// Provides sender anonymity with double-spend prevention via key images

Threshold Signatures


scheme, _ := threshold.GetScheme(threshold.SchemeFROST)
dkg := scheme.NewDKG(threshold.DKGConfig{
    Threshold:    2,
    TotalParties: 5,
    PartyIndex:   0,
})
// Round1 -> broadcast -> Round2 -> broadcast -> Round3 -> KeyShare

secp256k1 (EVM)


pk, _ := secp256k1.GenerateKey()
sig, _ := secp256k1.Sign(hash, pk)
pubkey, _ := secp256k1.RecoverPubkey(hash, sig)
  • lux/lux-consensus.md -- Uses BLS/ML-DSA for Quasar finality
  • lux/lux-fhe.md -- Fully homomorphic encryption
  • lux/lux-lattice.md -- Post-quantum lattice HE
  • lux/lux-wallet.md -- HD wallet implementation
  • lux/lux-sdk.md -- SDK that consumes this module

On this page