types

type Ceremony ¶

type Ceremony struct {
	ID         CeremonyID
	Kind       CeremonyKind
	State      CeremonyState
	Round      uint8 // 1..N, valid only when State is Round1 or Round2
	Threshold  uint16
	Total      uint16 // total participants
	StartEpoch uint64
	Subject    [32]byte // certificate_subject the ceremony binds into
	// PayloadArena is the per-ceremony buffer that all share payloads
	// index into via (offset, len). Owned by the host chain; the
	// substrate never allocates.
	PayloadArena []byte
}

Ceremony describes a single threshold ceremony on either chain.

Ceremony is a pure data type. State transitions are produced by Transition() in this package; the host chain (M-Chain or F-Chain) drives transitions on its own block ticks.

func (c Ceremony) Transition(next CeremonyState) (Ceremony, error)

Registered -> Round1
Round1     -> Round2
Round2     -> Finalized
*          -> Aborted   (always permitted)

func (c *Ceremony) Validate() error

type CeremonyID ¶

type CeremonyID [32]byte

CeremonyID is the canonical identifier for a ceremony, derived from the Quasar 3.0 round descriptor and the ceremony kind. It is the 32-byte hash that ties shares, proofs, and cert subjects together.

type CeremonyKind ¶

type CeremonyKind uint8

CeremonyKind names the protocol the ceremony executes. The kind determines which CertLane the finalized artifact uses and which verifier validates each round's payload. Adding a new kind appends here and adds a CertLane in cert/lane.go — never reorders.

const (
	KindUnknown       CeremonyKind = 0
	KindCGGMP21       CeremonyKind = 1 // M-Chain: ECDSA threshold
	KindFROST         CeremonyKind = 2 // M-Chain: Schnorr/EdDSA threshold
	KindRingtailGen   CeremonyKind = 3 // M-Chain: PQ general-purpose threshold
	KindTFHEKeygen    CeremonyKind = 4 // M-Chain → F-Chain: TFHE bootstrap-key gen
	KindTFHECompute   CeremonyKind = 5 // F-Chain: encrypted compute attestation
	KindTFHEBootstrap CeremonyKind = 6 // F-Chain: blind-rotate / bootstrap proof
)

func (k CeremonyKind) IsFChain() bool

func (k CeremonyKind) IsHandoff() bool

func (k CeremonyKind) IsMChain() bool

type CeremonyRound ¶

type CeremonyRound struct {
	CeremonyID CeremonyID
	Round      uint8
	Shares     []Share // populated as each participant publishes
}

CeremonyRound is the per-round bag of share commitments for a single ceremony. The host chain accumulates these in memory while the ceremony is in Round1 / Round2 and finalizes them into a CertLane artifact at Finalize.

type CeremonyState ¶

type CeremonyState uint8

CeremonyState is the position of a ceremony in the shared state machine. The same machine is used by every protocol on M-Chain and F-Chain; only the per-round payload differs.

const (
	StateUnknown    CeremonyState = 0
	StateRegistered CeremonyState = 1 // participant set committed, no shares yet
	StateRound1     CeremonyState = 2 // round-1 commitments published
	StateRound2     CeremonyState = 3 // round-2 shares published
	StateFinalized  CeremonyState = 4 // cert artifact emitted, root advanced
	StateAborted    CeremonyState = 5 // identifiable abort (CGGMP21 etc.) or timeout
)

func (s CeremonyState) String() string

type CertLane ¶

type CertLane uint8

CertLane mirrors LP-134 §QuasarCertLane. We declare it here in the substrate because the share envelope is the wire form on which every chain's verifier dispatches. The values must match LP-134 exactly. New lanes append; values never move.

const (
	LaneBLS               CertLane = 0
	LaneRingtail          CertLane = 1
	LaneMLDSAGroth16      CertLane = 2
	LaneAChainAttest      CertLane = 3
	LaneBChainBridge      CertLane = 4
	LaneMChainCGGMP21     CertLane = 5
	LaneMChainFROST       CertLane = 6
	LaneMChainRingtailGen CertLane = 7
	LaneFChainTFHE        CertLane = 8
	LaneFChainBootstrap   CertLane = 9
)

func (l CertLane) IsFChain() bool

func (l CertLane) IsMChain() bool

type NodeID ¶

type NodeID [32]byte

NodeID identifies a Lux validator. Same definition as the rest of luxfi/node — 32 bytes, content-addressed.

type Participant ¶

type Participant struct {
	Node   NodeID
	Index  uint32 // canonical index inside the ParticipantSet (0..n-1)
	Weight uint64 // stake weight at selection time, for accounting only
}

Participant is one validator selected (via stake-weighted VRF) into the participant set of a ceremony. The substrate does not pick participants; the host chain (M-Chain or F-Chain) does, then hands the resulting set here.

type ParticipantSet ¶

type ParticipantSet struct {
	CeremonyID CeremonyID
	Members    []Participant // sorted ascending by NodeID; Index == position
}

ParticipantSet is the deterministic, ordered set of validators for one ceremony. The set is fixed at registration; resharing is a new ceremony with a new set, never an in-place mutation.

func NewParticipantSet(ceremonyID CeremonyID, members []Participant) (*ParticipantSet, error)

func (ps *ParticipantSet) Digest() [32]byte

func (ps *ParticipantSet) Lookup(node NodeID) (Participant, bool)

type Proof ¶

type Proof struct {
	CeremonyID CeremonyID
	Kind       CeremonyKind
	Lane       CertLane
	// Payload is the protocol-specific final artifact: a signature
	// for sign-oriented ceremonies, a TFHE evaluation key for keygen
	// ceremonies, etc.
	Payload []byte
	// Aggregate is the aggregate signature over the participant
	// commitments (used when the chain itself attests to the
	// ceremony before forwarding to Quasar).
	Aggregate [64]byte
}

Proof is the verification artifact emitted at ceremony Finalize. It is consumed by Quasar 3.0's cert pipeline (LP-020) and bound into certificate_subject (LP-134).

The substrate defines the envelope; the per-protocol payload (the actual signature, group public key, FHE key, etc.) is opaque bytes indexed by Lane. Verifiers in cert/lane.go decode it.

func (p Proof) Empty() bool

type Selector ¶

type Selector interface {
	Select(ceremonyID CeremonyID, total uint16, seed [32]byte) (*ParticipantSet, error)
}

Selector is implemented by the host chain (M-Chain or F-Chain). The substrate consumes a Selector to produce a ParticipantSet at ceremony registration time.

Selectors must be:

• deterministic: same input -> same output, byte for byte
• permissionless: any validator with stake delegated to the chain is eligible (no allowlist)
• stake-weighted: probability of selection is proportional to stake delegated to the chain at the cutoff epoch

The substrate does not implement Selector; M-Chain and F-Chain each provide one wired to their stake delegation.

type Share ¶

type Share struct {
	CeremonyID    CeremonyID
	ParticipantID uint32   // index into ParticipantSet.Members
	Round         uint8    // 1..N, ceremony-kind specific
	Lane          CertLane // dispatches to the per-protocol verifier
	PayloadOffset uint32
	PayloadLen    uint32
	Signature     [64]byte // BLS or ML-DSA over (CeremonyID, Round, payload)
}

Share is the per-participant, per-round share envelope.

The envelope is fixed; per-protocol payload is carried via (PayloadOffset, PayloadLen) indirection into a Ceremony's PayloadArena. This matches the QuasarCertIngress wire ABI from LP-132 §drain_cert_lane: the verifier never decodes the share itself, only the payload window it points at.

func (s Share) PayloadFrom(arena []byte) ([]byte, error)

func (s Share) Validate(set *ParticipantSet) error