quasar

package
v1.22.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 12, 2025 License: BSD-3-Clause Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrQuasarNotStarted     = errors.New("quasar not started")
	ErrPChainNotConnected   = errors.New("P-Chain not connected")
	ErrQChainNotConnected   = errors.New("Q-Chain not connected")
	ErrRingtailNotConnected = errors.New("Ringtail coordinator not connected")
	ErrInsufficientWeight   = errors.New("insufficient validator weight")
	ErrInsufficientSigners  = errors.New("insufficient Ringtail signers")
	ErrFinalityFailed       = errors.New("hybrid finality verification failed")
	ErrBLSFailed            = errors.New("BLS aggregation failed")
	ErrRingtailFailed       = errors.New("Ringtail threshold signing failed")
)
View Source
var (
	ErrRingtailNotInitialized = errors.New("ringtail not initialized")
	ErrRingtailRound1Failed   = errors.New("ringtail round 1 failed")
	ErrRingtailRound2Failed   = errors.New("ringtail round 2 failed")
	ErrRingtailVerifyFailed   = errors.New("ringtail signature verification failed")
	ErrRingtailMACFailed      = errors.New("ringtail MAC verification failed")
)

Functions

This section is empty.

Types

type FinalityEvent added in v1.16.56

type FinalityEvent struct {
	Height     uint64
	BlockID    ids.ID
	Validators []ValidatorState
	Timestamp  time.Time
}

FinalityEvent represents a P-Chain finality event

type PChainProvider added in v1.16.56

type PChainProvider interface {
	GetFinalizedHeight() uint64
	GetValidators(height uint64) ([]ValidatorState, error)
	SubscribeFinality() <-chan FinalityEvent
}

PChainProvider provides P-Chain state and finality events

type QuantumFinality added in v1.16.56

type QuantumFinality struct {
	BlockID         ids.ID
	PChainHeight    uint64
	QChainHeight    uint64
	BLSProof        []byte       // Aggregated BLS signature (96 bytes)
	RingtailProof   []byte       // Serialized Ringtail threshold signature
	SignerBitset    []byte       // Which validators signed BLS
	RingtailSigners []ids.NodeID // Which validators participated in Ringtail
	TotalWeight     uint64
	SignerWeight    uint64
	BLSLatency      time.Duration
	RingtailLatency time.Duration
	Timestamp       time.Time
}

QuantumFinality represents a block that achieved hybrid quantum finality

type QuantumSignerFallback added in v1.16.56

type QuantumSignerFallback interface {
	SignMessage(msg []byte) ([]byte, error)
}

QuantumSignerFallback provides fallback single-signer quantum signatures

type Quasar added in v1.16.56

type Quasar struct {
	// contains filtered or unexported fields
}

Quasar binds P-Chain and Q-Chain consensus into hybrid quantum finality

func NewQuasar added in v1.16.56

func NewQuasar(log log.Logger, threshold int, quorumNum, quorumDen uint64) (*Quasar, error)

NewQuasar creates a new Quasar consensus hub

func (*Quasar) CheckQuorum added in v1.16.56

func (q *Quasar) CheckQuorum(signerWeight, totalWeight uint64) bool

CheckQuorum verifies quorum is met (exported for testing)

func (*Quasar) ConnectPChain added in v1.16.56

func (q *Quasar) ConnectPChain(p PChainProvider)

ConnectPChain connects the P-Chain finality provider

func (*Quasar) ConnectQuantumFallback added in v1.16.56

func (q *Quasar) ConnectQuantumFallback(f QuantumSignerFallback)

ConnectQuantumFallback connects the quantum signer fallback

func (*Quasar) ConnectRingtail added in v1.16.56

func (q *Quasar) ConnectRingtail(rc *RingtailCoordinator)

ConnectRingtail connects the Ringtail threshold coordinator

func (*Quasar) CreateMessage added in v1.16.56

func (q *Quasar) CreateMessage(event FinalityEvent) []byte

CreateMessage creates the finality message to sign (exported for testing)

func (*Quasar) GetConfig added in v1.16.56

func (q *Quasar) GetConfig() (threshold int, quorumNum, quorumDen uint64)

GetConfig returns quorum configuration (exported for testing)

func (*Quasar) GetFinality added in v1.16.56

func (q *Quasar) GetFinality(blockID ids.ID) (*QuantumFinality, bool)

GetFinality returns finality for a block

func (*Quasar) GetFinalized added in v1.16.56

func (q *Quasar) GetFinalized(blockID ids.ID) (*QuantumFinality, bool)

GetFinalized retrieves a finality record (exported for testing)

func (*Quasar) GetHybrid added in v1.16.56

func (q *Quasar) GetHybrid() *quasar.Hybrid

GetHybrid returns the underlying hybrid engine for testing

func (*Quasar) GetRingtail added in v1.16.56

func (q *Quasar) GetRingtail() *RingtailCoordinator

GetRingtail returns the Ringtail coordinator

func (*Quasar) InitializeRingtail added in v1.16.56

func (q *Quasar) InitializeRingtail(validators []ids.NodeID) error

InitializeRingtail initializes the Ringtail coordinator with validators

func (*Quasar) IsRunning added in v1.16.56

func (q *Quasar) IsRunning() bool

IsRunning returns whether the Quasar is currently running (exported for testing)

func (*Quasar) SetFinalized added in v1.16.56

func (q *Quasar) SetFinalized(blockID ids.ID, finality *QuantumFinality)

SetFinalized adds a finality record (exported for testing/benchmarking)

func (*Quasar) Start added in v1.16.56

func (q *Quasar) Start(ctx context.Context) error

Start begins the quasar consensus loop

func (*Quasar) Stats added in v1.16.56

func (q *Quasar) Stats() QuasarStats

Stats returns quasar statistics

func (*Quasar) Stop added in v1.16.56

func (q *Quasar) Stop()

Stop halts the quasar

func (*Quasar) Subscribe added in v1.16.56

func (q *Quasar) Subscribe() <-chan *QuantumFinality

Subscribe returns channel for finality events

func (*Quasar) TotalWeight added in v1.16.56

func (q *Quasar) TotalWeight(validators []ValidatorState) uint64

TotalWeight calculates total validator weight (exported for testing)

func (*Quasar) Verify added in v1.16.56

func (q *Quasar) Verify(finality *QuantumFinality) error

Verify verifies a hybrid finality proof

type QuasarStats added in v1.16.56

type QuasarStats struct {
	PChainHeight      uint64
	QChainHeight      uint64
	FinalizedBlocks   int
	Threshold         int
	QuorumNum         uint64
	QuorumDen         uint64
	Running           bool
	RingtailParties   int
	RingtailThreshold int
	RingtailReady     bool
}

QuasarStats contains quasar statistics

type RingtailConfig added in v1.16.56

type RingtailConfig struct {
	NumParties int // Total number of parties (validators)
	Threshold  int // Minimum signers required (typically 2/3 + 1)
}

RingtailConfig holds configuration for Ringtail threshold signatures

type RingtailCoordinator added in v1.16.56

type RingtailCoordinator struct {

	// Public parameters (shared by all parties)
	A structs.Matrix[ring.Poly]
	B structs.Vector[ring.Poly]
	// contains filtered or unexported fields
}

RingtailCoordinator manages the threshold signing protocol

func NewRingtailCoordinator added in v1.16.56

func NewRingtailCoordinator(log log.Logger, config RingtailConfig) (*RingtailCoordinator, error)

NewRingtailCoordinator creates a new Ringtail threshold coordinator

func (*RingtailCoordinator) Finalize added in v1.22.6

func (rc *RingtailCoordinator) Finalize(
	combinerNodeID ids.NodeID,
	zShares map[ids.NodeID]structs.Vector[ring.Poly],
) (*RingtailSignature, error)

Finalize combines partial signatures into the final threshold signature

func (*RingtailCoordinator) GetPublicParams added in v1.22.6

func (rc *RingtailCoordinator) GetPublicParams() (structs.Matrix[ring.Poly], structs.Vector[ring.Poly])

GetPublicParams returns the public parameters (A, B) for external verification

func (*RingtailCoordinator) Initialize added in v1.16.56

func (rc *RingtailCoordinator) Initialize(validators []ids.NodeID) error

Initialize generates keys and distributes shares to all parties This is the "trusted dealer" phase - in production this would be DKG

func (*RingtailCoordinator) IsInitialized added in v1.16.56

func (rc *RingtailCoordinator) IsInitialized() bool

IsInitialized returns whether the coordinator has been initialized

func (*RingtailCoordinator) ParallelSignRound1 added in v1.22.6

func (rc *RingtailCoordinator) ParallelSignRound1(message []byte) (map[ids.NodeID]*RingtailRound1Result, time.Duration, error)

ParallelSignRound1 executes round 1 for all parties in parallel

func (*RingtailCoordinator) ParallelSignRound2 added in v1.22.6

func (rc *RingtailCoordinator) ParallelSignRound2(
	message string,
	round1Results map[ids.NodeID]*RingtailRound1Result,
) (map[ids.NodeID]structs.Vector[ring.Poly], time.Duration, error)

ParallelSignRound2 executes round 2 for all parties in parallel

func (*RingtailCoordinator) SignRound1 added in v1.22.6

func (rc *RingtailCoordinator) SignRound1(nodeID ids.NodeID, message []byte) (*RingtailRound1Result, error)

SignRound1 executes round 1 of the signing protocol for a party

func (*RingtailCoordinator) SignRound2 added in v1.22.6

func (rc *RingtailCoordinator) SignRound2(
	nodeID ids.NodeID,
	message string,
	round1Results map[ids.NodeID]*RingtailRound1Result,
) (structs.Vector[ring.Poly], error)

SignRound2 executes round 2 of the signing protocol

func (*RingtailCoordinator) Stats added in v1.16.56

func (rc *RingtailCoordinator) Stats() RingtailStats

Stats returns coordinator statistics

func (*RingtailCoordinator) Verify added in v1.16.56

func (rc *RingtailCoordinator) Verify(message string, sig *RingtailSignature) bool

Verify verifies a Ringtail threshold signature

type RingtailParty added in v1.22.6

type RingtailParty struct {
	ID      int
	Party   *sign.Party
	SkShare structs.Vector[ring.Poly]
	Seeds   map[int][][]byte
	MACKeys map[int][]byte
	Lambda  ring.Poly // Lagrange coefficient
}

RingtailParty represents a validator's Ringtail signing state

type RingtailRound1Result added in v1.22.6

type RingtailRound1Result struct {
	PartyID int
	NodeID  ids.NodeID
	D       structs.Matrix[ring.Poly]
	MACs    map[int][]byte
}

RingtailRound1Result holds the output of round 1 for a party

type RingtailSignature added in v1.16.56

type RingtailSignature struct {
	C       ring.Poly
	Z       structs.Vector[ring.Poly]
	Delta   structs.Vector[ring.Poly]
	Signers []ids.NodeID
}

RingtailSignature represents a complete threshold signature

type RingtailStats added in v1.16.56

type RingtailStats struct {
	NumParties    int
	Threshold     int
	SessionID     int
	Initialized   bool
	ActiveParties int
}

RingtailStats contains coordinator statistics

type ValidatorState added in v1.16.56

type ValidatorState struct {
	NodeID      ids.NodeID
	Weight      uint64
	BLSPubKey   []byte // BLS public key for aggregate signatures
	RingtailKey []byte // Ringtail public key share for threshold sigs
	Active      bool
}

ValidatorState represents a validator's current state Each validator has BOTH BLS and Ringtail keys

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL