consensus

package
v1.13.19 Latest Latest
Warning

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

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

README

Lux Consensus Framework

Overview

The Lux consensus framework provides a family of consensus protocols for building distributed systems. The framework has been reorganized to use descriptive names that clearly indicate the purpose and functionality of each component.

Directory Structure

consensus/
├── binaryvote/      # Binary voting consensus primitive
├── linear/          # Linear chain consensus for blockchains
│   ├── poll/        # Voting and poll management
│   └── bootstrap/   # Chain bootstrapping logic
├── graph/           # DAG consensus for UTXO transactions
└── common/          # Shared interfaces and utilities
    └── choices/     # Decision states (Unknown, Processing, Accepted, Rejected)

Consensus Protocols

Binary Vote Consensus (binaryvote)

The fundamental building block of Lux consensus. It implements binary decision-making through repeated sampling and voting. Key features:

  • Binary decisions: Each node votes between two conflicting options
  • Metastability: The protocol amplifies small preferences into strong consensus
  • Confidence counters: Tracks consecutive rounds of agreement to build confidence
Linear Consensus (linear)

Extends binary voting for linear blockchain consensus. Used by all chains in the Lux network (X-Chain, C-Chain, P-Chain). Key features:

  • Linear ordering: Ensures blocks form a single chain
  • Block finality: Irreversible acceptance once consensus is reached
  • Efficient bootstrapping: Quickly syncs new nodes to the current state
Graph Consensus (graph)

Implements consensus for directed acyclic graph structures, used for UTXO transactions on the X-Chain. Key features:

  • Parallel transactions: Multiple transactions can be accepted simultaneously
  • Conflict resolution: Handles double-spend attempts through voting
  • Vertex-based structure: Transactions organized in a DAG of vertices

Key Components

Choices (common/choices)

Defines the possible states for any consensus decision:

  • Unknown: Initial state, no decision made
  • Processing: Currently being evaluated by consensus
  • Accepted: Irreversibly accepted by the network
  • Rejected: Irreversibly rejected by the network
Poll Management (linear/poll)

Handles the voting process:

  • Tracks votes from validators
  • Implements early termination when outcome is certain
  • Manages vote aggregation and result calculation
Bootstrap (linear/bootstrap)

Manages node synchronization:

  • Fetches historical blocks from other nodes
  • Verifies block validity during sync
  • Transitions to normal consensus once caught up

Usage

The consensus protocols are used by the Lux Virtual Machines (VMs) to achieve agreement on state transitions. Each blockchain selects the appropriate consensus protocol:

  • Linear consensus: Used by X-Chain, C-Chain, and P-Chain for block acceptance
  • DAG consensus: Fast massively parallelizable consensus X-Chain transactions
  • Binary vote: Core primitive used internally by other protocols

Migration from Snow Terminology

For developers familiar with the previous "Snow" naming:

  • confidence → binaryvote
  • snowman → linear
  • snowstorm → graph
  • avalanche → graph (vertex definitions merged)
  • snow/choices → consensus/common/choices

This restructuring provides clearer semantics while maintaining full compatibility with the existing consensus algorithms.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrUnknownState = errors.New("unknown state")

Functions

This section is empty.

Types

type Acceptor 

type Acceptor interface {
	// Accept must be called before [containerID] is committed to the VM as
	// accepted.
	//
	// If the returned error is non-nil, the chain associated with [ctx] should
	// shut down and not commit [container] or any other container to its
	// database as accepted.
	Accept(ctx *Context, containerID ids.ID, container []byte) error
}

Acceptor is implemented when a struct is monitoring if a message is accepted

type AcceptorGroup 

type AcceptorGroup interface {
	// Calling Accept() calls all of the registered acceptors for the relevant
	// chain.
	Acceptor

	// RegisterAcceptor causes [acceptor] to be called every time an operation
	// is accepted on chain [chainID].
	// If [dieOnError], chain [chainID] stops if Accept returns a non-nil error.
	RegisterAcceptor(chainID ids.ID, acceptorName string, acceptor Acceptor, dieOnError bool) error

	// DeregisterAcceptor removes an acceptor from the group.
	DeregisterAcceptor(chainID ids.ID, acceptorName string) error
}

func NewAcceptorGroup 

func NewAcceptorGroup(log logging.Logger) AcceptorGroup

type Context 

type Context struct {
	NetworkID       uint32
	SubnetID        ids.ID
	ChainID         ids.ID
	NodeID          ids.NodeID
	PublicKey       *bls.PublicKey
	NetworkUpgrades upgrade.Config

	XChainID   ids.ID
	CChainID   ids.ID
	LUXAssetID ids.ID

	Log logging.Logger
	// Deprecated: This lock should not be used unless absolutely necessary.
	// This lock will be removed in a future release once it is replaced with
	// more granular locks.
	//
	// Warning: This lock is not correctly implemented over the rpcchainvm.
	Lock         sync.RWMutex
	SharedMemory atomic.SharedMemory
	BCLookup     ids.AliaserReader
	Metrics      metrics.MultiGatherer

	WarpSigner warp.Signer

	// chain++ attributes
	ValidatorState validators.State // interface for P-Chain validators
	// Chain-specific directory where arbitrary data can be written
	ChainDataDir string

	// PrimaryAlias is the primary alias of the chain this context exists
	// within.
	PrimaryAlias string

	// Registers all consensus metrics.
	Registerer Registerer

	// BlockAcceptor is the callback that will be fired whenever a VM is
	// notified that their block was accepted.
	BlockAcceptor Acceptor

	// TxAcceptor is the callback that will be fired whenever a VM is notified
	// that their transaction was accepted.
	TxAcceptor Acceptor

	// VertexAcceptor is the callback that will be fired whenever a vertex was
	// accepted.
	VertexAcceptor Acceptor

	// State indicates the current state of this consensus instance.
	State utils.Atomic[EngineState]

	// True iff this chain is executing transactions as part of bootstrapping.
	Executing utils.Atomic[bool]

	// True iff this chain is currently state-syncing
	StateSyncing utils.Atomic[bool]
}

Context is information about the current execution. [NetworkID] is the ID of the network this context exists within. [ChainID] is the ID of the chain this context exists within. [NodeID] is the ID of this node

type ContextInitializable 

type ContextInitializable interface {
	// InitCtx initializes an object provided a *Context object
	InitCtx(ctx *Context)
}

ContextInitializable represents an object that can be initialized given a *Context object

type Decidable added in v0.15.6 

type Decidable interface {
	// ID returns a unique ID for this element.
	//
	// Typically, this is implemented by using a cryptographic hash of a
	// binary representation of this element. An element should return the same
	// IDs upon repeated calls.
	ID() ids.ID

	// Accept this element.
	//
	// This element will be accepted by every correct node in the network.
	Accept(context.Context) error

	// Reject this element.
	//
	// This element will not be accepted by any correct node in the network.
	Reject(context.Context) error
}

Decidable represents element that can be decided.

Decidable objects are typically thought of as either transactions, blocks, or vertices.

type EngineState 

type EngineState struct {
	Type  p2p.EngineType
	State State
}

type Registerer 

type Registerer interface {
	prometheus.Registerer
	prometheus.Gatherer
}

Expose gatherer interface for unit testing.

type State 

type State uint8
const (
	Initializing State = iota
	StateSyncing
	Bootstrapping
	NormalOp
)

func (State) String added in v0.15.6 

func (st State) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package engine is a generated GoMock package.
 Package engine is a generated GoMock package.
appsender
chain
chain/ancestor
chain/block
chain/block/blockmock
Package blockmock is a generated GoMock package.
 Package blockmock is a generated GoMock package.
chain/block/blocktest
chain/bootstrap
chain/bootstrap/interval
chain/getter
chain/job
Package job provides a Scheduler to manage and execute Jobs with dependencies.
 Package job provides a Scheduler to manage and execute Jobs with dependencies.
chain/syncer
dag
dag/bootstrap
dag/bootstrap/queue
dag/getter
dag/state
Package state manages the meta-data required by consensus for an lux dag.
 Package state manages the meta-data required by consensus for an lux dag.
dag/vertex
dag/vertex/vertex_impl
dag/vertex/vertex_impl/vertexmock
Package vertexmock is a generated GoMock package.
 Package vertexmock is a generated GoMock package.
dag/vertex/vertex_impl/vertextest
dag/vertex/vertexmock
Package vertexmock is a generated GoMock package.
 Package vertexmock is a generated GoMock package.
dag/vertex/vertextest
enginetest
tracker
bootstrapper
chainmock
Package linearmock is a generated GoMock package.
 Package linearmock is a generated GoMock package.
chaintest
poll
networking
benchlist
handler
handler/handlermock
Package handlermock is a generated GoMock package.
 Package handlermock is a generated GoMock package.
router
router/routermock
Package routermock is a generated GoMock package.
 Package routermock is a generated GoMock package.
sender
sender/sendermock
Package sendermock is a generated GoMock package.
 Package sendermock is a generated GoMock package.
sender/sendertest
timeout
timeout/timeoutmock
Package timeoutmock is a generated GoMock package.
 Package timeoutmock is a generated GoMock package.
tracker
tracker/trackermock
Package trackermock is a generated GoMock package.
 Package trackermock is a generated GoMock package.
uptimemock
Package uptimemock is a generated GoMock package.
 Package uptimemock is a generated GoMock package.
gvalidators
validatorsmock
Package validatorsmock is a generated GoMock package.
 Package validatorsmock is a generated GoMock package.
validatorstest

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.