qbft

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Jul 7, 2022 License: GPL-3.0 Imports: 7 Imported by: 0

README

QBFT

Package qbft is an implementation of the "The Istanbul BFT Consensus Algorithm" by Henrique Moniz as referenced by the QBFT spec.

Features

  • Simple API, just a single function: qbft.Run.
  • Consensus on arbitrary data.
  • Transport abstracted and not provided.
  • Decoupled from process authentication and message signing (not provided).
  • No dependencies.
  • Explicit justifications.

TODO

  • Add specific Byzantium tests.
  • Add long-running tests. Workaround for now: while go test . -count=10 -timeout=5s; do; done

Documentation

Overview

Package qbft is an implementation of the https://arxiv.org/pdf/2002.03613.pdf paper referenced by the QBFT spec https://github.com/ConsenSys/qbft-formal-spec-and-verification.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run

func Run[I any, V comparable](ctx context.Context, d Definition[I, V], t Transport[I, V], instance I, process int64, inputValue V) (err error)

Run executes the consensus algorithm until the context closed. The generic type I is the instance of consensus and can be anything. The generic type V is the arbitrary data value being proposed; it only requires an Equal method.

Types

type Definition

type Definition[I any, V comparable] struct {
	// IsLeader is a deterministic leader election function.
	IsLeader func(instance I, round, process int64) bool
	// NewTimer returns a new timer channel and stop function for the round.
	NewTimer func(round int64) (<-chan time.Time, func())
	// Decide is called when consensus has been reached on a value.
	Decide func(ctx context.Context, instance I, value V, qcommit []Msg[I, V])
	// LogUponRule allows debug logging of triggered upon rules on message receipt.
	LogUponRule func(ctx context.Context, instance I, process, round int64, msg Msg[I, V], uponRule string)
	// Nodes is the total number of nodes/processes participating in consensus.
	Nodes int
	// FIFOLimit limits the amount of message buffered for each peer.
	FIFOLimit int
}

Definition defines the consensus system parameters that are external to the qbft algorithm. This remains constant across multiple instances of consensus (calls to Run).

func (Definition[I, V]) Faulty

func (d Definition[I, V]) Faulty() int

Faulty returns the maximum number of faulty/byzantium nodes supported in the system. See IBFT 2.0 paper for correct formula: https://arxiv.org/pdf/1909.10194.pdf

func (Definition[I, V]) Quorum

func (d Definition[I, V]) Quorum() int

Quorum returns the quorum count for the system. See IBFT 2.0 paper for correct formula: https://arxiv.org/pdf/1909.10194.pdf

type Msg

type Msg[I any, V comparable] interface {
	// Type of the message.
	Type() MsgType
	// Instance identifies the consensus instance.
	Instance() I
	// Source identifies the process that sent the message.
	Source() int64
	// Round the message pertains to.
	Round() int64
	// Value being proposed.
	Value() V
	// PreparedRound is the justified prepared round.
	PreparedRound() int64
	// PreparedValue is the justified prepared value.
	PreparedValue() V
	// Justification is the set of messages that explicitly justifies this message.
	Justification() []Msg[I, V]
}

Msg defines the inter process messages.

type MsgType

type MsgType int64

MsgType defines the QBFT message types.

const (
	MsgUnknown     MsgType = 0
	MsgPrePrepare  MsgType = 1
	MsgPrepare     MsgType = 2
	MsgCommit      MsgType = 3
	MsgRoundChange MsgType = 4
	MsgDecided     MsgType = 5
)

Note that message type ordering MUST not change, since it breaks backwards compatibility.

func (MsgType) String

func (i MsgType) String() string

func (MsgType) Valid

func (i MsgType) Valid() bool

type Transport

type Transport[I any, V comparable] struct {
	// Broadcast sends a message with the provided fields to all other
	// processes in the system (including this process).
	//
	// Note that a non-nil error exits the algorithm.
	Broadcast func(ctx context.Context, typ MsgType, instance I, source int64, round int64, value V, pr int64, pv V, justification []Msg[I, V]) error

	// Receive returns a stream of messages received
	// from other processes in the system (including this process).
	Receive <-chan Msg[I, V]
}

Transport abstracts the transport layer between processes in the consensus system.

Jump to

Keyboard shortcuts

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