Skip to content

LLM.md

Latest commit

 

History

History
166 lines (127 loc) · 5.78 KB

LLM.md

File metadata and controls

166 lines (127 loc) · 5.78 KB

LLM.md - Threshold Signatures Library

AI assistant context for the Lux Threshold Signatures Library.

Project Overview

Production-ready universal threshold signature implementation supporting 20+ blockchains with post-quantum security. Written in Go 1.25, forked from taurusgroup/multi-party-sig.

Architecture

threshold/
├── cmd/threshold-cli/     # CLI tool
├── internal/              # Private implementation details
│   ├── bip32/            # BIP-32 key derivation
│   ├── elgamal/          # ElGamal encryption
│   ├── mta/              # Multiplicative-to-Additive conversion
│   ├── ot/               # Oblivious transfer (recently updated from upstream)
│   ├── params/           # Protocol parameters (ZKModIterations=128)
│   ├── round/            # Round-based protocol framework
│   └── test/             # Testing infrastructure
├── pkg/                   # Public API
│   ├── ecdsa/            # ECDSA signatures
│   ├── hash/             # BLAKE3-based hashing
│   ├── math/             # Cryptographic arithmetic (curve, polynomial, sample)
│   ├── paillier/         # Homomorphic encryption
│   ├── party/            # Party identification
│   ├── pool/             # Thread pool for parallelization
│   ├── protocol/         # Protocol handler framework
│   ├── taproot/          # BIP-340/341 support
│   └── zk/               # 17 zero-knowledge proof systems
├── protocols/             # Protocol implementations
│   ├── cmp/              # CMP ECDSA (4-round signing, 7-round presign)
│   ├── frost/            # FROST Schnorr/EdDSA (2-round signing)
│   ├── lss/              # LSS dynamic resharing
│   ├── doerner/          # 2-of-2 optimized ECDSA
│   ├── ringtail/         # Post-quantum lattice-based
│   └── bls/              # BLS aggregate signatures
└── docs/                  # Documentation

Key Protocols

Protocol Algorithm Rounds Performance Features
CMP ECDSA 4 sign, 7 presign ~15ms Identifiable aborts
FROST Schnorr/EdDSA 2 ~8ms BIP-340 Taproot
LSS ECDSA Variable ~35ms reshare Dynamic resharing
Doerner ECDSA 2-party ~5ms Constant-time
Ringtail Lattice Variable - Post-quantum

Important Conventions

Naming Differences from Upstream

This fork uses different field naming from upstream taurusgroup/multi-party-sig:

  • Delta (public) instead of _Delta (private)
  • _KDelta instead of _K_Delta

When merging upstream, adapt their code to our conventions.

Security Parameters

Key constants in internal/params/params.go:

  • SecParam = 256 - Security parameter (bits)
  • OTParam = 128 - OT security parameter
  • StatParam = 80 - Statistical security
  • ZKModIterations = 128 - Paillier-Blum validation (increased from 12 for security)
  • BitsBlumPrime = 1024, BitsPaillier = 2048

Package Imports

Use luxfi packages exclusively:

import (
    "github.com/luxfi/threshold/pkg/..."
    "github.com/luxfi/threshold/internal/..."
    "github.com/luxfi/threshold/protocols/..."
)

Never use ava-labs packages. Use luxfi/crypto, luxfi/log, luxfi/zmq.

Recent Changes (December 2024)

Upstream Merge

  • Increased ZKModIterations from 12 to 128 (security fix)
  • Improved Extended OT monochrome check (based on paper revision)
  • Added doubleFieldElement type for proper GF(2^k) multiplication
  • New functions: randFe, pluckColumnToFieldElement, transposeToFieldSizeElements, adjustBatchSize

Cleanup

  • Renamed Avalanche references to Lux throughout
  • Removed obsolete .old and .bak files
  • Updated chain symbol from AVAX to LUX

Testing

# Run all tests
go test ./... -timeout 120s

# Protocol-specific
go test ./protocols/cmp/... -timeout 120s
go test ./protocols/lss/... -timeout 120s
go test ./internal/ot/... -timeout 120s

# With race detection
go test -race ./... -timeout 180s

Note: pkg/protocol has a known flaky test (TestHandler_WaitForResultTimeout) unrelated to core functionality.

Blockchain Support

Tier 1 (Full Native): XRPL, Ethereum, Bitcoin, Solana, TON, Cardano Tier 2 (Ready): Cosmos, Polkadot, Lux, BSC, NEAR, Aptos, Sui, Tezos, Algorand, Stellar, Hedera, Flow, Kadena, Mina

EVM chains use protocols/lss/adapters/evm.go with chain config in GetChainConfig().

Performance Benchmarks

Operation 3-of-5 5-of-9 7-of-11 10-of-15
Key Gen 12ms 28ms 45ms 82ms
Signing 8ms 15ms 24ms 40ms
Resharing 20ms 35ms 52ms 75ms
Verification 2ms 2ms 2ms 2ms

Common Tasks

Adding a New Chain Adapter

  1. Add chain constant in protocols/lss/adapters/evm.go or appropriate file
  2. Add config in GetChainConfig()
  3. Update protocols/lss/factory.go with chain info
  4. Add to SupportedChains() list
  5. Update tests in full_coverage_test.go

Merging Upstream

git remote add upstream https://github.com/taurusgroup/multi-party-sig.git
git fetch upstream
git log --oneline upstream/main ^main  # Check new commits
# Manually apply changes adapting naming conventions

Dependencies

Core:

  • github.com/cronokirby/saferith - Constant-time arithmetic
  • github.com/zeebo/blake3 - Fast hashing
  • github.com/fxamacker/cbor/v2 - Binary serialization

Lux:

  • github.com/luxfi/crypto
  • github.com/luxfi/log
  • github.com/luxfi/zmq/v4

References