consensus

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jul 30, 2025 License: BSD-3-Clause Imports: 8 Imported by: 0

README

Lux Consensus

Welcome to Lux Consensus—the world's first unified quantum-secure consensus engine. By replacing Avalanche's complex Snowman++ with a streamlined Nova + Ringtail PQ architecture, Lux achieves both classical AND quantum finality in the same number of rounds that Avalanche needs for classical finality alone.

🏆 Revolutionary Achievement

Quasar = Nova + Ringtail PQ = Classical + Quantum Finality in k+2 rounds

While Avalanche needs k+3 rounds for classical finality (Nova + Snowball + Snowman + P-Chain callback), Lux achieves both classical AND quantum finality in just k+2 rounds:

  • Mainnet: Nova (k rounds) + Ringtail (2 rounds) = Quantum finality in <1s
  • Testnet: Nova (k rounds) + Ringtail (2 rounds) = Quantum finality in <800ms
  • Local: Nova only = Classical finality in <400ms

🌟 Overview

The Problem with Snowman++

Avalanche's C-Chain uses a complex multi-stage process:

  1. Nova/DAG: Assigns chits via k-peer sampling, builds confidence d(T)
  2. Snowball wrap: Once confidence crosses β, vertex becomes "preferred"
  3. Snowman linearizer: Converts DAG decisions into a linear chain
  4. P-Chain callback: Validates against stake registry

Result: Multiple extra rounds, complex callbacks, no quantum security.

The Quasar Solution

Lux replaces this entire stack with one elegant engine:

  1. Nova/DAG: Unchanged - same k-peer sampling and confidence building
  2. Ringtail PQ: 2-phase lattice protocol on top of Nova's confidence
  3. Q-blocks: Embedded as P-Chain internal transactions

Result: Same total rounds, but with quantum security included!

📦 Unified Architecture

nova/       # DAG consensus (unchanged from Avalanche)
ringtail/   # 2-phase PQ overlay
  phase1/     # Propose frontier
  phase2/     # Commit frontier
quasar/     # Unified engine combining Nova + Ringtail
  engine.go   # Main Quasar engine
  qblock.go   # Q-block structure
pchain/     # P-Chain with embedded Q-blocks

🔬 How Quasar Works

1. Nova DAG (Unchanged)
// Standard Avalanche DAG consensus
vertex := nova.NewVertex(txs)
nova.Add(vertex)
confidence := nova.GetConfidence(vertex)
if confidence > beta {
    // Vertex ready for finalization
}
2. Ringtail PQ Overlay
// Phase I: Propose (1 round)
frontier := nova.GetHighestConfidenceFrontier()
proposal := ringtail.Propose(frontier)
proposals := p2p.GossipProposal(proposal, k)

// Phase II: Commit (1 round)
if CountAgreement(proposals) > alphaCommit {
    qblock := ringtail.Commit(frontier)
    // Quantum finality achieved!
}
3. P-Chain Integration
// Q-blocks embedded as internal transactions
type PChainBlock struct {
    Transactions []Tx
    QBlocks     []QBlock  // Embedded quantum finality
}

// All chains watch P-Chain for finality
func (chain *AnyChain) IsFinalized(tx) bool {
    return pchain.HasQBlock(tx)
}

🎯 Key Innovation: Monotonic Lattice

Why Ringtail works in just 2 phases on top of Nova:

  1. Nova provides monotonicity: Confidence d(T) only increases
  2. Metastable property: High confidence vertices stay high
  3. Network convergence: All nodes see same high-confidence frontier

The Ringtail lattice leverages these properties:

    Q[n+1] (new Q-block)
   /   |   \
F[a]  F[b]  F[c] (possible frontiers)
   \   |   /
    Q[n] (previous Q-block)

Once Q[n+1] commits to frontier F[b], the lattice structure ensures all future Q-blocks build on F[b].

🔄 Consensus Flow

graph LR
    TX[Transaction] --> Nova[Nova DAG<br/>k rounds]
    Nova --> R1[Ringtail Phase I<br/>Propose]
    R1 --> R2[Ringtail Phase II<br/>Commit]
    R2 --> QB[Q-Block]
    QB --> PC[P-Chain<br/>Embedded]
    PC --> F[Universal Finality]

Compare to Snowman++:

graph LR
    TX[Transaction] --> Nova[Nova DAG<br/>k rounds]
    Nova --> SB[Snowball<br/>+1 round]
    SB --> SM[Snowman<br/>+1 round]
    SM --> CB[P-Chain Callback<br/>+1 round]
    CB --> F[Classical Finality Only]

📊 Performance Comparison

Consensus Rounds to Classical Rounds to Quantum Total Time Complexity
Snowman++ k+3 N/A ~1.2s High (4 stages)
Quasar k+2 k+2 ~1.0s Low (2 stages)

Quasar achieves quantum security in fewer rounds than Snowman++ needs for classical!

🚀 Usage

All Chains Use Same Engine
// Every chain (C, X, M, Z) uses identical Quasar engine
type Chain struct {
    quasar *QuasarEngine
}

func (c *Chain) ProcessBlock(block *Block) {
    // Add to Quasar (handles Nova + Ringtail internally)
    qblock := c.quasar.Process(block.Transactions)
    
    // Finality determined by P-Chain Q-blocks
    block.QBlockRef = qblock.ID
}
Smart Contract Access
interface IQuasar {
    function isFinalized(bytes32 txHash) external view returns (bool);
    function getQBlock(bytes32 txHash) external view returns (QBlock);
}

contract SecureTransfer {
    IQuasar quasar = IQuasar(0x0...001F);
    
    function transfer(uint amount) external {
        bytes32 txHash = keccak256(abi.encode(msg.sender, amount));
        require(quasar.isFinalized(txHash), "Awaiting Quasar finality");
        // Transfer is quantum-secure!
    }
}

🔧 Configuration

type QuasarParams struct {
    // Nova (unchanged from Avalanche)
    K    int  // Sample size (21 for mainnet)
    Beta int  // Confidence threshold (18 for mainnet)
    
    // Ringtail (new)
    AlphaPropose int  // Phase I threshold (13)
    AlphaCommit  int  // Phase II threshold (18)
    
    // Q-Chain
    QBlockInterval time.Duration  // 100ms
}

📖 Summary

Quasar represents a fundamental breakthrough in consensus design:

  1. Replaces Snowman++ entirely - No more complex multi-stage process
  2. Same rounds, better security - Quantum finality in k+2 rounds
  3. Universal engine - All chains use identical Quasar protocol
  4. Elegant simplicity - Nova + 2-phase Ringtail = done

The photonic journey is complete:

  • Photon: Transactions enter as light
  • Wave: K-sampling creates interference
  • Nova: Confidence explodes
  • Quasar: Ringtail focuses into quantum beam
  • Q-Chain: Beam recorded on P-Chain forever

Welcome to the age of unified quantum consensus. Welcome to Quasar.

📝 License

BSD 3‑Clause — free for academic & commercial use.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Acceptor

type Acceptor interface {
	Accept(ctx *Context, containerID ids.ID, container []byte) error
}

Acceptor is something that can accept a piece of data

type AcceptorGroup

type AcceptorGroup interface {
	RegisterAcceptor(chainID ids.ID, name string, acceptor Acceptor, persist bool) error
	DeregisterAcceptor(chainID ids.ID, name string) error
	Accept(ctx *Context, containerID ids.ID, container []byte) error
}

AcceptorGroup manages multiple acceptors

func NewAcceptorGroup

func NewAcceptorGroup(log log.Logger) AcceptorGroup

NewAcceptorGroup creates a new acceptor group

type BCLookup

type BCLookup interface {
	Lookup(alias string) (ids.ID, error)
	PrimaryAlias(id ids.ID) (string, error)
}

BCLookup is the interface for looking up chain IDs by alias

type Context

type Context struct {
	// NetworkID is the ID of the network this node is connected to.
	NetworkID uint32

	// ChainID is the chain this engine is working on.
	ChainID ids.ID

	// SubnetID is the subnet this engine is working on.
	SubnetID ids.ID

	// NodeID is the ID of this node.
	NodeID ids.NodeID

	// BCLookup maps aliases to chain IDs.
	BCLookup BCLookup

	// Registerer for registering metrics.
	Registerer Registerer

	// Log is used for logging messages.
	Log Logger

	// Lock is used to synchronize access to shared resources.
	Lock sync.Locker

	// ValidatorSet contains the validators for this subnet.
	ValidatorSet validators.Set

	// ValidatorState provides access to validator information.
	ValidatorState ValidatorState

	// Sender is used to send messages to other nodes.
	Sender Sender

	// Bootstrappers are the nodes that are used to bootstrap this chain.
	Bootstrappers []ids.NodeID

	// StartTime is the time this engine started.
	StartTime time.Time

	// RequestID is used to create unique request IDs.
	RequestID *RequestID

	// LUXAssetID is the ID of the LUX asset.
	LUXAssetID ids.ID

	// State represents the current consensus state
	State *EngineState
}

Context contains the state that is used by consensus engines.

type ContextInitializable

type ContextInitializable interface {
	InitCtx(ctx *Context)
}

ContextInitializable defines an interface for objects that need context initialization

type Engine

type Engine struct{}

Engine represents the Lux consensus engine This is a stub implementation when the external consensus package is not available

func NewEngine

func NewEngine(network string) (*Engine, error)

NewEngine creates a new Lux consensus engine

func NewEngineWithParams

func NewEngineWithParams(params interface{}) (*Engine, error)

NewEngineWithParams creates a new engine with custom parameters

func NewTestEngine

func NewTestEngine(params interface{}) (*Engine, error)

NewTestEngine creates a new engine for testing

type EngineState

type EngineState struct {
	State State
}

EngineState represents the state of the consensus engine

func (*EngineState) Get

func (s *EngineState) Get() *EngineState

Get gets the engine state

func (*EngineState) Set

func (s *EngineState) Set(state EngineState)

Set sets the engine state

type Logger

type Logger log.Logger

For missing imports

type Registerer

type Registerer prometheus.Registerer

For missing imports

type RequestID

type RequestID struct{}

For missing imports

type Sender

type Sender interface{}

For missing imports

type State

type State uint32

State represents the current state of the consensus engine

const (
	// Bootstrapping state
	Bootstrapping State = iota
	// NormalOp represents normal operation state
	NormalOp
	// StateSyncing state
	StateSyncing
)

type ValidatorState

type ValidatorState interface {
	// GetMinimumHeight returns the minimum height of the P-chain.
	GetMinimumHeight(ctx context.Context) (uint64, error)

	// GetCurrentHeight returns the current height of the P-chain.
	GetCurrentHeight(ctx context.Context) (uint64, error)

	// GetSubnetID returns the subnet ID for the given chain ID.
	GetSubnetID(ctx context.Context, chainID ids.ID) (ids.ID, error)

	// GetValidatorSet returns the validators of the given subnet at the
	// given P-chain height.
	GetValidatorSet(
		ctx context.Context,
		height uint64,
		subnetID ids.ID,
	) (map[ids.NodeID]*validators.GetValidatorOutput, error)
}

ValidatorState provides access to validator information

Directories

Path Synopsis
crypto
bls
dag
dag/vertex/vertexmock
Package vertexmock is a generated GoMock package.
Package vertexmock is a generated GoMock package.
engines
networking
router/routermock
Package routermock is a generated GoMock package.
Package routermock is a generated GoMock package.
tracker/trackermock
Package trackermock is a generated GoMock package.
Package trackermock is a generated GoMock package.
SPDX-License-Identifier: BUSL-1.1
SPDX-License-Identifier: BUSL-1.1
ringtail
Package ringtail provides placeholder implementations for the Ringtail cryptographic library
Package ringtail provides placeholder implementations for the Ringtail cryptographic library
uptimemock
Package uptimemock is a generated GoMock package.
Package uptimemock is a generated GoMock package.
validatorsmock
Package validatorsmock is a generated GoMock package.
Package validatorsmock is a generated GoMock package.

Jump to

Keyboard shortcuts

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