This repo wrapped ghcr.io/luxfi/mpc under a Hanzo tag. The ring never used it: all three nodes pull the upstream image, and the one object naming this one is at 0 replicas labelled legacy. The tag LLM.md advertised as live, 1.17.15, 404s — it was never built. Newest that exists is 1.17.12. Removing hanzo.yml, which is what made the repo contradict itself: it told platform to keep publishing an image on every tag push while DEPRECATED.md said development had moved. Correcting LLM.md's deployment claims and DEPRECATED.md's version and its 'archived as mpc-v1' line, which named a repo that never existed. The threshold proof in LLM.md stays. That work was real and was done on the ring.
14 KiB
MPC Signer - LLM Context
Overview
Threshold signing service. Pluggable signer backend for Hanzo KMS.
- ECDSA (secp256k1): CGGMP21 protocol -- Bitcoin, Ethereum, EVM, XRPL, Lux
- ECDSA (secp256k1) Taproot: FROST protocol -- Bitcoin Taproot
- EdDSA (Ed25519): FROST (Taproot mode) -- Solana/TON partial support
- LSS: Dynamic resharing (change T-of-N without key reconstruction)
- Threshold: default t = floor(n/2) + 1
Deployment status — nothing here ships
The ring in ns hanzo-mpc (do-sfo3-hanzo-k8s, 3 nodes) runs
ghcr.io/luxfi/mpc straight from upstream, not an image built here.
charts/app/values/hanzo-mpc/node.yaml in hanzo/universe is its declaration.
This repo's own image is not running anywhere in any cluster. The one object
that names it — statefulset/hanzo-mpc in ns hanzo — sits at 0 replicas
carrying deprecated.hanzo.ai/status=legacy, pinned to 1.2.9.
An earlier version of this file claimed ghcr.io/hanzoai/mpc:1.17.15 was
serving those 3 nodes. That tag returns 404 — it was never published. The
wrapping Dockerfile was written and committed, but no build ever produced it;
the newest tag that exists is 1.17.12. The claim recorded an intention as if
it were a fact, and the note below repeats the mistake for v0.4.3.
The threshold work described next is real and was proven on the ring. Read it as cryptography, not as a description of what this repo deploys.
- CRITICAL fix live:
--thresholdnow sets the CGGMP21 keygen polynomial degree (was silently degree 0 = 1-of-n). Startup log confirmskeygenDegree=1 signersRequired=2for hanzo's--threshold=2→ genuine 2-of-3 (degree = threshold-1). Pre-fix, every hanzo wallet (incl. hanzo-dao) was keyed at degree 0 — a single node could forge a sig. - PROOF (fresh wallet
hanzo-threshold-proof-v1, EVM 0xfcdb945bc51aeac746b209f379f5f2f94249153b, pubkey 030d61780ff5a35e2a901f4a21d8c268087b1d7d8c6c66f75fe9e4b3d1466c9f8d): ring keyed it atthreshold=1on all 3 nodes; a real 3-party sign produced an ECDSA signature that VERIFIES against the pubkey (digest 152f8560…); a 1-of-3 subset is refused (node CreateSignSessionlen<Threshold+1, and cmpCanSign→ValidThreshold(1,1)=false). General property pinned by luxfi/thresholdprotocols/cmp/degree2_proof_test.go. - Existing pre-fix wallets keep their degree-0 keys (and addresses) until re-keyed — re-keying is a per-wallet migration (changes the address), NOT done by the image roll.
- hanzo/kms (ns hanzo):
ghcr.io/luxfi/kms:1.11.9, NO master key, NO MPC-backing. Safe to upgrade to v1.12.3 (no REK → the /v1/sdk consensus authorizer never fires, no fail-closed blocker); enable MPC-backing with MPC_VAULT_ID=hanzo + MPC_ADDR=…hanzo-mpc…:9653. STAGED (not rolled) — coordinate with the KMS workstream.
Architecture
KMS (Control Plane): Policy, Approvals, Audit, Key Registry, Unified Signing API
|
+-- HSM Signer
+-- MPC Signer (this project) -- DKG, threshold signing, reshare
+-- Software Signer
+-- Remote Signer
Project Structure
mpc/
cmd/mpcd/ Main node binary
cmd/mpc/ CLI tools
pkg/
mpc/ TSS implementation (CGGMP21, FROST, LSS)
kvstore/ BadgerDB storage (AES-256 encrypted)
messaging/ NATS JetStream (pub/sub + P2P)
identity/ Ed25519 node identity (Age encrypted)
client/ Go client library
policy/ Policy engine (signers, limits, whitelist, FHE)
threshold/ ThresholdVM (policy enforcement in signing)
storage/ BadgerDB store + S3 backup client
eventconsumer/ Event processing
contracts/ ThresholdPolicy.sol (on-chain policy)
deploy/ compose.yml with full stack
e2e/ End-to-end tests
Quick Start
make build
mpc generate-peers -n 3
mpc register-peers
mpc generate-initiator
mpc generate-identity --node node0
mpcd start -n node0
Config
environment: development
kv_backend: consensus # "consensus" (default), "nats", or "consul"
consensus:
chain_id: m-chain # "m-chain", "t-chain", or custom
nats:
url: nats://localhost:4222
kv_bucket: mpc-state # only used when kv_backend: nats
consul: # only used when kv_backend: consul (legacy)
address: localhost:8500
badger_password: "secure-password"
event_initiator_pubkey: "hex-encoded-pubkey"
Env vars: HANZO_MPC_CONFIG (config path), HANZO_MPC_BACKUP (backup ID).
KV Backend Architecture (Mar 2026)
All MPC cluster state (peers, key info, API keys, wallet owners) goes through an
abstract infra.KV interface. Three backends are available:
| Backend | Config | Transport | Finality | Use Case |
|---|---|---|---|---|
consensus |
kv_backend: consensus |
NATS + Lux Quasar | Post-quantum (<100ms) | Production (blockchain-native) |
nats |
kv_backend: nats |
NATS JetStream KV | JetStream replication | Dev/staging |
consul |
kv_backend: consul |
Consul HTTP | Raft | Legacy / parity testing |
ConsensusKV (Private MPC Blockchain, Dual-Certificate)
- MPC nodes run their own private BFT blockchain — no external chain needed
- Dual-certificate finality (same model as Lux Quasar):
- Classical: Ed25519 (64-byte sig, fast)
- Post-quantum: ML-DSA-65 (FIPS 204, NIST Level 3, 3,309-byte sig)
- Block finalized ONLY when BOTH signature types reach t-of-n threshold
- If quantum computers break Ed25519, ML-DSA certs still valid
- If ML-DSA has a flaw, Ed25519 certs still hold
- t-of-n threshold finality (same t as MPC threshold, e.g. 2-of-3)
- Protocol: propose → broadcast → dual-sign vote → threshold met → finalize
- KV mutations batched into blocks, applied deterministically on all nodes
- NATS provides transport between validators
- Keys stored in KMS/HSM when
hsm.provideris configured - Can optionally register as Lux subnet (M-Chain/T-Chain) for network integration
- State sync via snapshot for new node joins
- Bootstrap: peers discovered from
mpc-bootstrapNATS KV bucket
ML-DSA-65 Key Sizes (FIPS 204)
| Component | Size |
|---|---|
| Public key | 1,952 bytes |
| Private key | 4,032 bytes |
| Signature | 3,309 bytes |
| Security level | NIST Level 3 (192-bit) |
| Package | github.com/luxfi/crypto/mldsa |
Files
pkg/infra/kv.go— abstractKVinterface +KVPairtypepkg/infra/consensus_kv.go— Lux consensus-backed KVpkg/infra/nats_kv.go— NATS JetStream KVpkg/infra/consul_adapter.go— wraps Consul → KV interfacepkg/infra/consul.go— raw Consul client (kept for backward compat)
Deploy Stack (deploy/compose.yml)
| Service | Port | Purpose |
|---|---|---|
| mpcd-{0,1,2} | 6000-6002 | MPC nodes (consensus validators) |
| hanzo-kms | 8080 | Key management |
| nats | 4222 | Message broker + consensus transport |
| s3 | 9000 | Hanzo S3 backup storage |
Testing
make test # Unit tests
make test-coverage # With coverage
make e2e-test # End-to-end
Critical Gotchas (Debugged Jan 2026)
Serialization
- Protocol messages MUST use
MarshalBinary/UnmarshalBinary, NOT JSON (loses SSID, RoundNumber) - FROST
TaprootConfigcrypto types have NO JSON marshalers -- MUST use CBOR viaMarshalFROSTConfig()/UnmarshalFROSTConfig() - LSS
lssConfig.Configsame issue -- use CBOR viaMarshalLSSConfig()/UnmarshalLSSConfig()
Protocol Behavior
- Party IDs must be sorted consistently (
GetReadyPeersIncludeSelf()handles this) - "Handler cannot accept message" warnings are NORMAL (nodes receiving own broadcasts)
- FROST signing returns
taproot.Signature(64-byte[]byte), NOT*frost.Signature - BIP-340 format (R_x || s) needs no conversion
Result Publishing
- Sessions must NOT publish success to result queue -- handler publishes combined ECDSA+EdDSA result
- Sessions publish FAILURE directly for immediate notification
- Sessions send success via
externalFinishChan; always send (even empty on error) to prevent blocking - Dual keygen runs ECDSA (CGGMP21) and EdDSA (FROST) in parallel via goroutines+WaitGroup
NATS Topics
- Keygen:
mpc.mpc_keygen_result.<walletID>(notempc.mpc_prefix) - Signing:
mpc.mpc_signing_result.<walletID> - Stream pattern:
mpc.mpc_*_result.* - Consensus blocks:
mpc.consensus.<chainID>.blocks - Consensus proposals:
mpc.consensus.<chainID>.proposals
E2E Tests
- Tests use
mpcdfrom PATH -- rungo install ./cmd/mpcd && go install ./cmd/mpcafter code changes
Production Deployment — superseded, kept for shape only
Stale. statefulset/mpcd with ghcr.io/hanzoai/mpc:v0.4.3 in ns hanzo is not
what the cluster runs; see "Deployment status" above for what does. The port,
peer and threshold shape below still describes how a ring is wired.
Cluster: hanzo-k8s (do-sfo3)
- Namespace:
hanzo - StatefulSet:
mpcd(3 replicas) - Image:
ghcr.io/hanzoai/mpc:v0.4.3 - API:
mpc.hanzo.ai(port 8080, IAM auth via hanzo.id) - Node peers: mpcd-{0,1,2}
- Threshold: 2-of-3
Infrastructure
- NATS:
nats://nats.hanzo.svc.cluster.local:4222(JetStream + consensus transport) - KV Backend:
consensus(M-Chain) — Consul deprecated, kept for parity testing - Config: ConfigMap
mpcd-configat/app/config.yaml - Identity: Secret
mpcd-identityat/app/identity/+/app/event_initiator.key
Key Architecture
- Event initiator key (Ed25519): Signs all keygen/signing/reshare messages
- Private key: K8s secret
mpcd-identitykeyevent_initiator.key(hex seed) - Public key: ConfigMap
event_initiator_pubkey - Mounted at
/app/event_initiator.keyvia subPath volumeMount
- Private key: K8s secret
- Node identity keys: Per-node Ed25519 keys in identity secret
mpcd-{N}_private.key+mpcd-{N}_identity.json
- MPC key shards: BadgerDB at
/data/mpc/db/mpcd-{N}/(PVC)
Message Flow (verified working Feb 24 2026)
API → MPCClient.CreateWallet(walletID)
→ Ed25519 sign(GenerateKeyMessage)
→ JetStream publish to mpc.keygen_request.<walletID>
→ KeygenConsumer → PubSub mpc:generate
→ EventConsumer.VerifyInitiatorMessage() ✓
→ CGGMP21 DKG protocol (3 rounds) → ~16s
→ Result → mpc.mpc_keygen_result.<walletID>
→ WalletStore.handleKeygenResult() → status: active
TODO: KMS-First Key Management
- Store event_initiator private key in KMS (kms.hanzo.ai)
- Store Ed25519 + ML-DSA-65 consensus signing keys in KMS
- Each node authenticates to KMS with Machine Identity
- Fetch key shards + dual consensus keys at runtime (never plaintext on disk)
- HSM abstraction (PKCS#11) for AWS CloudHSM / Azure HSM
- Node identity keys (Ed25519 + ML-DSA-65) also in KMS with encrypted backups
- Generate
{node}_pq_identity.jsonand{node}_pq_private.keyviampc generate-identity
Security Audit Findings (Jan 2026)
- Protocol messages between nodes are NOT signed (Ed25519 code exists but disabled) UPDATE (Mar 2026): ConsensusKV now signs all blocks and votes with Ed25519 identity keys
- Deduplication
processingmap grows unbounded -- needs TTL cleanup - No timeout on protocol handlers -- needs context with deadline
Policy Engine (pkg/policy/)
Fireblocks/Utila-style transaction governance:
- Signers and roles (ADMIN, SIGNER, VIEWER)
- Spending limits (per-tx, daily, monthly by asset)
- Whitelist/blacklist, time windows, rate limiting
- ThresholdVM (
pkg/threshold/policy_vm.go): evaluates policies before signature shares - FHE private policies via pluggable
FHEEngineinterface (compatible with luxfi/fhe)
TFHE Integration (pkg/mpc/tfhe_session.go)
Threshold FHE via luxfi/fhe v1.7.6:
Key Types
tfhe-uint{8,16,32,64,128,256},tfhe-bool,tfhe-address
Sessions
- tfheKeygenSession: Trusted-dealer DKG → distributes key shares to MPC nodes
- tfheComputeSession: Load config → encrypt/decrypt/compute on encrypted data
TFHE Policy Opcodes (ThresholdVM)
| Opcode | Name | Description |
|---|---|---|
| 0x80 | PrivateAmountLT | Encrypted amount < encrypted threshold |
| 0x81 | PrivateAmountGT | Encrypted amount > encrypted threshold |
| 0x82 | PrivateCumulative | Encrypted cumulative spending check |
| 0x83 | PrivateWhitelist | Encrypted address whitelist check |
Encrypted Policy State
EncryptedPolicyState {
CumulativeDaily EncryptedUint64 // 24h spending (encrypted)
CumulativeMonthly EncryptedUint64 // monthly spending (encrypted)
LastTxTime EncryptedUint64 // last tx timestamp (encrypted)
VestedAmount EncryptedUint64 // vesting state (encrypted)
StreamedAmount EncryptedUint64 // streaming state (encrypted)
}
KMS-MPC-TFHE Integration (2026-03-11)
A new TFHE-KMS bridge was added to Hanzo KMS (backend/src/services/tfhe/):
- KMS stores TFHE key metadata + public key references
- Bridge triggers MPC keygen via NATS JetStream (
mpc.keygen_request.*) - MPC nodes run TFHE DKG, store shares in BadgerDB
- KMS receives public key via result queue
- Encryption uses public key (KMS-side, no MPC needed)
- Decryption requires t-of-n shares (MPC threshold decryption)
- Private policy evaluation runs on encrypted data (no plaintext exposure)
- Integrates with T-Chain precompile (
0x0700...0080) for on-chain FHE
T-Chain FHE Architecture
C-Chain (Contracts) → Smart contracts with encrypted operations
↓ (emit DecryptionRequested)
T-Chain (Threshold) → MPC nodes with TFHE/threshold protocols
↓ (callback with plaintext)
C-Chain (Results) → Finality via contract callback
Blockchain Support
| Chain | Curve | Protocol | Status |
|---|---|---|---|
| Bitcoin (Legacy/SegWit) | secp256k1 | CGGMP21/LSS | Full |
| Bitcoin (Taproot) | secp256k1 | FROST | Full |
| Ethereum/EVM | secp256k1 | CGGMP21/LSS | Full |
| XRPL | secp256k1 | CGGMP21/LSS | Full |
| Lux Network | secp256k1 | CGGMP21/LSS | Full |
| Solana | Ed25519 | FROST (Taproot) | Partial -- needs native Ed25519 FROST |
| TON | Ed25519 | FROST (Taproot) | Partial -- needs native Ed25519 FROST |