Files
zeekay 6ee3729249 stop publishing, and say what actually runs
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.
2026-08-21 08:22:05 -07:00

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: --threshold now sets the CGGMP21 keygen polynomial degree (was silently degree 0 = 1-of-n). Startup log confirms keygenDegree=1 signersRequired=2 for 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 at threshold=1 on 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 CreateSignSession len<Threshold+1, and cmp CanSign→ValidThreshold(1,1)=false). General property pinned by luxfi/threshold protocols/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.provider is 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-bootstrap NATS 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 — abstract KV interface + KVPair type
  • pkg/infra/consensus_kv.go — Lux consensus-backed KV
  • pkg/infra/nats_kv.go — NATS JetStream KV
  • pkg/infra/consul_adapter.go — wraps Consul → KV interface
  • pkg/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 TaprootConfig crypto types have NO JSON marshalers -- MUST use CBOR via MarshalFROSTConfig()/UnmarshalFROSTConfig()
  • LSS lssConfig.Config same issue -- use CBOR via MarshalLSSConfig()/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> (note mpc.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 mpcd from PATH -- run go install ./cmd/mpcd && go install ./cmd/mpc after 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-config at /app/config.yaml
  • Identity: Secret mpcd-identity at /app/identity/ + /app/event_initiator.key

Key Architecture

  • Event initiator key (Ed25519): Signs all keygen/signing/reshare messages
    • Private key: K8s secret mpcd-identity key event_initiator.key (hex seed)
    • Public key: ConfigMap event_initiator_pubkey
    • Mounted at /app/event_initiator.key via subPath volumeMount
  • 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.json and {node}_pq_private.key via mpc generate-identity

Security Audit Findings (Jan 2026)

  1. 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
  2. Deduplication processing map grows unbounded -- needs TTL cleanup
  3. 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 FHEEngine interface (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