lux/mpc

mirror of https://github.com/luxfi/mpc.git synced 2026-09-24 00:26:24 +00:00

Files

T

zeekay 3bb399cbdd mpc: deployment-mode flag + audit dispatcher for fund-private clusters

Adds the topology contract that lets a fund run mpcd as its own private
cluster — no Lux primary network registration, no shared M-Chain audit
ledger — using the same code path and the same operator surface.

Mode flag at cmd/mpcd/main.go:
  --network=primary|private              # registration target
  --audit-store=mchain|local-worm|...    # audit log destination
  --registrar-url, --registrar-auth      # primary-mode announcement
  --audit-worm-path, --audit-mchain-url  # backend selectors

pkg/audit:
  - Append-only Merkle hash chain. Tampering with any historical event
    invalidates every subsequent hash. Canonical bytes use fixed-order
    concatenation (json.Marshal map ordering is non-deterministic).
  - WORMDispatcher: NDJSON append, replay-on-start, fsync per Append.
  - MChainDispatcher: batched POST of (batchHash, fromSeq, toSeq) to a
    configurable anchor RPC.
  - compositeDispatcher: fan-out to multiple legs with per-leg sealing.
  - S3 Glacier Vault / Azure Immutable / GCS Object Lock dispatchers
    fail closed — wired into the flag surface but gated behind the
    cloud-audit build tag, no silent fallback.

pkg/identity/bootstrap.go: identity creation + (primary-mode only)
registrar announcement. Same on-disk format as the previous
loadOrGenerateIdentity (which is now removed); private mode is silent.

deployments/k8s-private: fund-only Kustomize overlay. Standalone
namespace, NetworkPolicy that blocks egress to anything outside the
fund's VPC, hardware-WORM PVC for the audit log, KMS-driven secret
template.

deployments/k8s-primary: env-var patch overlay on the existing lux-mpc
base. composite(local-worm,mchain) by default.

deployments/terraform/{aws,gcp,azure}: VPC + audit storage modules.
terraform validate passes; EKS/GKE/AKS + HSM modules are stubbed and
not yet plan-tested.

deployments/onprem/README.md: WORM storage + PKCS#11 HSM checklist.

Tests (14 total, all passing):
  pkg/audit:           6/6  (chain, WORM replay, MChain batching, composite,
                             cloud stubs fail loud, double-seal rejected)
  pkg/identity:        4/4  (private no-call, primary call, primary empty
                             URL no-op, primary registrar 503 surfaces)
  internal/privatemode: 4/4 (no registrar traffic, restart, tamper-detect,
                             cloud stubs fail loud)

Companion runbook in lux/papers/lux-private-mpc-deployment/
(LaTeX, 5 pages, tectonic-clean).

2025-12-28 16:20:40 -08:00

README.md

mpc: deployment-mode flag + audit dispatcher for fund-private clusters

2025-12-28 16:20:40 -08:00

README.md

On-prem deployment for fund-private mpcd

For funds that cannot use a public cloud. The deployment shape is the same as the cloud variants: a 3- or 5-replica StatefulSet, a hardware WORM volume for the audit log, an HSM provider for ZapDB password unwrap.

Required components

Kubernetes cluster — any conformant distribution. Tested with k3s 1.30+, vanilla 1.30+, OpenShift 4.16+. The cluster must support PersistentVolumes, NetworkPolicies, and Pod Security Admission at restricted level.
WORM storage class — the StatefulSet's volumeClaimTemplates request a storage class named worm-block-storage. Operators map this to NetApp SnapLock, Dell ECS retention, or a tape-backed CIFS mount. The mpcd daemon does not enforce immutability — the storage layer must.
HSM — PKCS#11-accessible. YubiHSM, SafeNet Luna, Thales Crypto Command Center, or a software HSM (SoftHSM2) for non-prod. Set MPC_HSM_PROVIDER=pkcs11 in the StatefulSet and mount the PKCS#11 bridge as a sidecar at app=fund-hsm-bridge.
Identity provider — for the dashboard's JWT issuer. Hanzo IAM if the fund is a Lux customer; the fund's existing OIDC IdP if not.
Time source — operators must point all nodes at chrony or PTP. The audit log timestamps drive compliance attestations; clock skew between nodes corrupts the chain order across replicas.

Deployment steps

# 1. Apply the Kustomize overlay against the cluster
kubectl apply -k ../k8s-private/

# 2. Populate mpc-secrets via the fund's KMS pipeline
kubectl create secret generic mpc-secrets -n fund-mpc \
  --from-literal=hsm-provider=pkcs11 \
  --from-literal=hsm-key-id=path-to-key \
  --from-literal=hsm-signer=local \
  --from-literal=jwt-secret=$(openssl rand -hex 32) \
  --from-literal=internal-api-key=$(openssl rand -hex 32) \
  --dry-run=client -o yaml | kubectl apply -f -

# 3. Wait for all 3 nodes to become Ready
kubectl rollout status -n fund-mpc statefulset/mpc-node

# 4. Run the key ceremony (see runbook §5)
mpc-key-ceremony --threshold 2 --participants node-0,node-1,node-2

# 5. Sign your first transaction (see runbook §6)

See the LaTeX runbook in papers/lux-private-mpc-deployment/ for the full operational procedures.