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

Files

T

zeekay e032ec4b05 feat(thresholdvm): stage design docs and protocol scaffolding

Stages the ThresholdVM engineering record under chains/thresholdvm/:

Docs (engineering record, 502 LOC):
- DESIGN.md, LLM.md, README.md
- docs/ARCHITECTURE.md, docs/F_CHAIN_INTEGRATION.md, docs/M_CHAIN_INTEGRATION.md

Source scaffolding (1289 LOC):
- cert/      — QuasarCertLane registration + subject binding (M/F shared)
- types/     — ceremony, participant, proof, share substrate types
- protocol/  — package surfaces for cggmp21, frost, corona_general, tfhe_keygen
- runtime/   — F-chain and M-chain adapters

All Go files carry the Lux license header. Nothing here is generated or
fixture data; this is the signed-off design surface for the ThresholdVM
library used by M-chain and F-chain.

2026-04-28 09:17:47 -07:00

4.9 KiB

Raw Blame History

ThresholdVM

ThresholdVM is a Go library, not a chain.

It is the shared substrate that M-Chain (MPC ceremonies) and F-Chain (FHE compute) build on. Both chains import this package; neither chain is this package.

                    +--------------------------------+
                    |         ThresholdVM            |
                    |  (ceremony state machine,      |
                    |   share envelope, lane API,    |
                    |   subject binding)             |
                    +----------------+---------------+
                                     |
                 +-------------------+-------------------+
                 |                                       |
        +--------v--------+                     +--------v--------+
        |     M-Chain     |                     |     F-Chain     |
        |  (MPC: CGGMP21, |                     | (FHE: TFHE,     |
        |   FROST,        |                     |  bootstrap-key  |
        |   Corona-gen) |  --bootstrap key--> |  gen, encrypted |
        |                 |                     |  EVM)           |
        +-----------------+                     +-----------------+
        ceremony_root:                          ceremony_root:
        mchain_ceremony_root                    fchain_fhe_root
        block time ~500ms                       block time ~2s
        sign-oriented                           compute-oriented

What this directory contains

Path	Role
`types/`	Ceremony, Participant, Share, Proof — pure data types, no chain logic
`protocol/`	Protocol-specific verifier interfaces (impl ships with the chain that uses it)
`cert/`	QuasarCertLane integration: lane registration + certificate-subject binding
`runtime/`	`MChainAdapter` and `FChainAdapter` interfaces the two chains implement
`docs/`	Architecture + per-chain integration notes

What this directory is not

Not a Lux VM. There is no factory.go exposed to chains.Manager.
Not a chain ID. M-Chain and F-Chain are the chains; they have their own validator sets, ceremony roots, and block cadence.
Not a registry of secrets, keys, or signed material. State lives on M-Chain or F-Chain, never here.

Why split

LP-134 deprecates LP-5013 ("T-Chain MPC Custody"). T-Chain previously mixed MPC ceremonies and FHE compute under one validator set, one ceremony root, one block cadence. Sign-oriented (sub-second, latency critical) and compute-oriented (multi-second, throughput critical) workloads have incompatible scaling profiles. Splitting them lets each scale on its own validator set.

The substrate stays one piece because the ceremony state machine is identical across both: registered participants → round 1 commitments → round 2 shares → finalized cert. Only the per-protocol payload (carried by (offset, len) indirection in the share envelope) differs.

Permissionless participation

Both M-Chain and F-Chain inherit P-Chain's permissionless validator model. Anyone with stake on P-Chain can delegate to the M-Chain or F-Chain validator subset (or both). No allowlist. No central authority. Bitcoin-like decentralization carries through — the threshold scheme itself enforces honest-majority safety, the chain enforces liveness.

Cross-chain handoff

When M-Chain finishes a ceremony whose output feeds F-Chain (e.g., a TFHE bootstrap key generated by FROST DKG on M-Chain), the output crosses via a CertLane artifact:

M-Chain finalizes ceremony, emits cert with lane MChainFROST and mchain_ceremony_root updated.
F-Chain consumes the artifact via its FChainBootstrap lane, binds it into fchain_fhe_root.
Quasar 3.0's certificate_subject binds both roots in the same round, making cross-chain replay structurally impossible.

The handoff envelope is defined in cert/lane.go; the typed adapter in runtime/.

Migration from T-Chain

LP-5013 is deprecated. The legacy chain at chains/thresholdvm/ (this directory's vm.go, block.go, factory.go, fhe/, cmd/) hosts the migration shims that route legacy TChain* cert lanes to the appropriate MChain* / FChain* verifiers during the one-epoch grace window. After the grace window closes, the shims are removed and only the substrate (this README's directory tree) remains.

Activation

ThresholdVM substrate activates with Quasar 3.0 on 2025-12-25, alongside the M-Chain and F-Chain genesis events. Versions before that date target the legacy T-Chain layout.

References

LP	Topic
LP-019	Threshold MPC for Bridge Signing (M-Chain protocols)
LP-013	FHE on GPU (F-Chain compute)
LP-076	Universal Threshold Cryptography Framework
LP-134	Lux Chain Topology — defines the M/F split
LP-132	QuasarGPU Execution Adapter — lane verifiers run here
LP-020	Quasar Consensus 3.0 — certificate_subject binding

4.9 KiB Raw Blame History