consensus

Documentation

Overview

Package consensus provides a Quasar consensus adapter for pubsub.

Quasar uses two independent cryptographic layers (BLS + PQ), each verifiable in parallel. All inter-node communication uses ZAP (Zero-copy Application Protocol) — no dependency on github.com/luxfi/p2p.

Index

• Constants
• type Config
• type FinalizedOp
• type Op
• type OpType
• type Quasar
  • func New(cfg Config) (*Quasar, error)
  • func (q *Quasar) ConnectPeer(addr string) error
  • func (q *Quasar) IsFinalized(hash string) bool
  • func (q *Quasar) ReceiveVote(hash string, validatorID string, sig *QuasarSignature) bool
  • func (q *Quasar) Start(ctx context.Context) error
  • func (q *Quasar) Status() Status
  • func (q *Quasar) Stop()
  • func (q *Quasar) Submit(ctx context.Context, op Op) (string, error)
• type QuasarConsensus
• type QuasarSignature
• type Status

Constants

const (
	OpPropose   uint16 = 0x20 // broadcast pending op for signing
	OpVote      uint16 = 0x21 // QuasarSignature back to proposer
	OpFinalized uint16 = 0x22 // announce PQ finality to all peers
	OpSyncReq   uint16 = 0x23 // request missed finalized ops
	OpSyncResp  uint16 = 0x24 // return finalized ops
)

ZAP opcodes for consensus P2P messages (0x20 range).

Types

type Config

type Config struct {
	Threshold    int
	ValidatorIDs []string
	ValidatorID  string
	MaxFinalized int

	// ZAP transport
	ZAPPort     int
	ZAPPeers    []string
	ZAPDiscover bool

	// Store enables consensus state persistence.
	Store *store.Store

	Logger *slog.Logger
}

Config configures the Quasar consensus adapter.

type FinalizedOp

type FinalizedOp struct {
	Hash        string `json:"hash"`
	Height      uint64 `json:"height"`
	FinalizedAt int64  `json:"finalized_at"`
}

FinalizedOp is an operation that achieved PQ finality.

type Op

type Op struct {
	Type      OpType `json:"type"`
	Stream    string `json:"stream"`
	Subject   string `json:"subject,omitempty"`
	Payload   []byte `json:"payload,omitempty"`
	Timestamp int64  `json:"ts"` // set automatically on submit
}

Op represents a stream operation submitted for PQ consensus.

type OpType

type OpType uint8

OpType identifies the kind of stream operation.

const (
	OpStreamCreate OpType = iota + 1
	OpStreamDelete
	OpMessagePublish
)

type Quasar

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

Quasar wraps the Lux consensus signer for pubsub stream operations. All P2P communication uses ZAP.

func New

func New(cfg Config) (*Quasar, error)

New creates a new Quasar consensus adapter with ZAP transport.

func (*Quasar) ConnectPeer

func (q *Quasar) ConnectPeer(addr string) error

ConnectPeer adds a static peer by address (host:port).

func (*Quasar) IsFinalized

func (q *Quasar) IsFinalized(hash string) bool

IsFinalized checks whether an operation has achieved PQ finality.

func (*Quasar) ReceiveVote

func (q *Quasar) ReceiveVote(hash string, validatorID string, sig *QuasarSignature) bool

ReceiveVote records a validator's signature for a pending operation.

func (*Quasar) Start

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

Start begins the ZAP consensus transport and background routines.

func (*Quasar) Status

func (q *Quasar) Status() Status

Status returns the current Quasar consensus status.

func (*Quasar) Stop

func (q *Quasar) Stop()

Stop shuts down the ZAP transport and persists state.

func (*Quasar) Submit

func (q *Quasar) Submit(ctx context.Context, op Op) (string, error)

Submit submits a stream operation for PQ consensus.

type QuasarConsensus

type QuasarConsensus = quasar.Quasar

Type aliases to the upstream consensus quasar primitives.

type QuasarSignature

type QuasarSignature = quasar.QuasarSig

Type aliases to the upstream consensus quasar primitives.

type Status

type Status struct {
	Enabled    bool     `json:"enabled"`
	Height     uint64   `json:"height"`
	Pending    int      `json:"pending"`
	Finalized  int      `json:"finalized"`
	Validators int      `json:"validators"`
	Threshold  int      `json:"threshold"`
	Peers      []string `json:"peers"`
	NodeID     string   `json:"node_id"`
}

Status reports the current state of the Quasar consensus layer.