gomel

package
v0.0.0-...-fc88c08 Latest Latest
Warning

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

 Go to latest Published: Mar 5, 2021 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package gomel defines all the interfaces representing basic components for executing the Aleph consensus protocol.

The main components defined in this package are:

  1. The unit and preunit representing the information produced by a single process in a single round of the protocol.
  2. The dag, containing all the units created by processes and representing the partial order between them.
  3. The random source interacting with the dag to generate randomness needed for the protocol.

Index

Constants

View Source 
const HashLength = 32

HashLength is the size of hashes of units.

Variables

This section is empty.

Functions

func Above 

func Above(u, v Unit) bool

Above checks if u is above v.

func BelowAny 

func BelowAny(u Unit, us []Unit) bool

BelowAny checks whether u is below any of the units in us.

func Dealing 

func Dealing(u Preunit) bool

Dealing checks if u is a dealing unit.

func Equal 

func Equal(u, v Preunit) bool

Equal checks if two units are the same.

func ID 

func ID(height int, creator uint16, epoch EpochID) uint64

ID is a tuple (Height, Creator, Epoch) encoded as a single number.

func LevelFromParents 

func LevelFromParents(parents []Unit) int

LevelFromParents calculates level of a unit having given set of parents.

func MinimalQuorum 

func MinimalQuorum(nProcesses uint16) uint16

MinimalQuorum is the minimal possible size of a subset forming a quorum within nProcesses.

func MinimalTrusted 

func MinimalTrusted(nProcesses uint16) uint16

MinimalTrusted is the minimal size of a subset of nProcesses, that guarantees that the subset contains at least one honest process.

func Nickname 

func Nickname(bu Preunit) string

Nickname of a unit is a short name, for the purpose of quick identification by a human.

func SigEq 

func SigEq(s, r Signature) bool

SigEq checks for signatures equality.

func ToPreblock 

func ToPreblock(round []Unit) *core.Preblock

ToPreblock produces a preblock from a slice of units containing a timing round. It assumes that the timing unit is the last unit in the slice, and that random source data of the timing unit starts with random bytes from the previous level.

func UnitID 

func UnitID(u Preunit) uint64

UnitID returns ID of the given Preunit.

Types

type Adder 

type Adder interface {
	// AddPreunits adds preunits received from the given process.
	AddPreunits(uint16, ...Preunit) []error
	// Close stops the Adder.
	Close()
}

Adder is a component that accepts incoming preunits.

type Alerter 

type Alerter interface {
	// NewFork raises an alert about newly detected fork.
	NewFork(Preunit, Preunit)
	// HandleIncoming handles the incoming connection.
	HandleIncoming(network.Connection)
	// Disambiguate which of the provided (forked) units is the right one to be the parent of the given preunit.
	Disambiguate([]Unit, Preunit) (Unit, error)
	// RequestCommitment that is missing in the given Preunit from the committee member with the given process ID.
	RequestCommitment(Preunit, uint16) error
	// ResolveMissingCommitment
	ResolveMissingCommitment(error, Preunit, uint16) error
	//IsForker checks whether the alerter knows that the given pid is a forker.
	IsForker(uint16) bool
	// AddForkObserver allows one to receive notifications in case a fork is discovered.
	AddForkObserver(func(Preunit, Preunit)) utils.ObserverManager
	// Lock the state for the given process ID.
	Lock(uint16)
	// Unlock the state for the given process ID.
	Unlock(uint16)
	// Start Alerter.
	Start()
	// Stop Alerter.
	Stop()
}

Alerter is responsible for raising alerts about forks and handling communication about commitments in case of fork.

func NopAlerter 

func NopAlerter() Alerter

NopAlerter is an alerter that does nothing.

type AmbiguousParents 

type AmbiguousParents struct {
	Units [][]Unit
}

AmbiguousParents is an error-like object used when trying to add a unit whose parents cannot be determined by pid and height. It contains all possible parents sliced by creator.

func NewAmbiguousParents 

func NewAmbiguousParents(units [][]Unit) *AmbiguousParents

NewAmbiguousParents constructs an AmbigousParents error for a given process.

func (*AmbiguousParents) Error 

func (e *AmbiguousParents) Error() string

type ComplianceError 

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

ComplianceError is raised when encountering a unit that does not follow compliance rules. Indicates a problem with both the process providing the data and the unit's creator.

func NewComplianceError 

func NewComplianceError(msg string) *ComplianceError

NewComplianceError constructs a ComplianceError from a given msg.

func (*ComplianceError) Error 

func (e *ComplianceError) Error() string

Error returns a string description of a ComplianceError.

type ConfigError 

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

ConfigError is returned when a provided configuration can not be parsed.

func NewConfigError 

func NewConfigError(msg string) *ConfigError

NewConfigError constructs a ConfigError from a given msg.

func (*ConfigError) Error 

func (e *ConfigError) Error() string

type Crown 

type Crown struct {
	Heights     []int
	ControlHash Hash
}

Crown represents nProc units created by different processes in a condensed form. It contains heights of the units and a combined hash of the units - the ControlHash. Any missing unit is represented by height -1, and ZeroHash.

func CrownFromParents 

func CrownFromParents(parents []Unit) *Crown

CrownFromParents returns a crown consisting of the given slice of units. It assumes that the given slice of parents is of the length nProc, and the i-th unit is created by the i-th process.

func EmptyCrown 

func EmptyCrown(nProc uint16) *Crown

EmptyCrown is a crown with all the units missing.

func NewCrown 

func NewCrown(heights []int, hash *Hash) *Crown

NewCrown returns a crown with given slice of heights, and given control hash.

type Dag 

type Dag interface {
	// EpochID is a unique identifier of the epoch for this dag instance.
	EpochID() EpochID
	// DecodeParents returns a slice of parents of the given preunit, if the control hash matches.
	DecodeParents(Preunit) ([]Unit, error)
	// BuildUnit constructs a new unit from the preunit and the slice of parents.
	BuildUnit(Preunit, []Unit) Unit
	// Check runs on the given unit a series of UnitChechers added to the dag with AddCheck.
	Check(Unit) error
	// Insert puts a unit into the dag.
	Insert(Unit)
	// UnitsOnLevel returns all units on a given level of the dag.
	UnitsOnLevel(int) SlottedUnits
	// MaximalUnitsPerProcess returns a collection of units containing, for each process, all maximal units created by that process.
	MaximalUnitsPerProcess() SlottedUnits
	// UnitsAbove returns all units present in dag with heights higher than given slice of heights (of length NProc).
	UnitsAbove([]int) []Unit
	// GetUnit returns a unit with the given hash, if present in the dag, or nil otherwise.
	GetUnit(*Hash) Unit
	// GetUnits returns slice of units associated with given hashes, in the same order.
	// If no unit with a particular hash exists in the dag, the result contains a nil at that position.
	GetUnits([]*Hash) []Unit
	// GetByID returns the units associated with the given ID. There will be more than one only in the case of forks.
	GetByID(uint64) []Unit
	// IsQuorum checks if the given number of processes is enough to form a quorum.
	IsQuorum(uint16) bool
	// NProc returns the number of processes that shares this dag.
	NProc() uint16
	// AddCheck extends the list of UnitCheckers that are used by this dag during adding a unit.
	AddCheck(UnitChecker)
	// BeforeInsert adds an action to perform before insert.
	BeforeInsert(InsertHook)
	// AfterInsert adds an action to perform after insert.
	AfterInsert(InsertHook)
}

Dag is the main data structure of the Aleph consensus protocol. It is built of units partially ordered by "is-parent-of" relation.

type DagInfo 

type DagInfo struct {
	Epoch   EpochID
	Heights []int
}

DagInfo contains information about heights of the most recent units in a Dag.

func MaxView 

func MaxView(dag Dag) *DagInfo

MaxView returns the current DagInfo for the given Dag.

type DataError 

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

DataError represents incorrect data received from a process. Indicates a problem with the process providing the data.

func NewDataError 

func NewDataError(msg string) *DataError

NewDataError constructs a DataError from a given msg.

func (*DataError) Error 

func (e *DataError) Error() string

Error returns a string description of a DataError.

type DuplicatePreunit 

type DuplicatePreunit struct {
	Pu Preunit
}

DuplicatePreunit is an error-like object used when encountering a unit that is already known. Usually not a problem.

func NewDuplicatePreunit 

func NewDuplicatePreunit(pu Preunit) *DuplicatePreunit

NewDuplicatePreunit constructs a DuplicatePreunit error for the given preunit.

func (*DuplicatePreunit) Error 

func (e *DuplicatePreunit) Error() string

Error returns a (fixed) string description of a DuplicatePreunit.

type DuplicateUnit 

type DuplicateUnit struct {
	Unit Unit
}

DuplicateUnit is an error-like object used when encountering a unit that is already known. Usually not a problem.

func NewDuplicateUnit 

func NewDuplicateUnit(unit Unit) *DuplicateUnit

NewDuplicateUnit constructs a DuplicateUnit error for the given unit.

func (*DuplicateUnit) Error 

func (e *DuplicateUnit) Error() string

Error returns a (fixed) string description of a DuplicateUnit.

type EpochID 

type EpochID uint32

EpochID is used as a unique identifier of an epoch.

func DecodeID 

func DecodeID(id uint64) (int, uint16, EpochID)

DecodeID that is a single number into a tuple (Height, Creator, Epoch).

type Hash 

type Hash [HashLength]byte

Hash is a type storing hash values, usually used to identify units. 

var ZeroHash Hash

ZeroHash is a hash containing zeros at all 32 positions.

func CombineHashes 

func CombineHashes(hashes []*Hash) *Hash

CombineHashes computes hash from sequence of hashes.

func ToHashes 

func ToHashes(units []Unit) []*Hash

ToHashes converts a list of units to a list of hashes.

func XOR 

func XOR(h *Hash, k *Hash) *Hash

XOR returns xor of two hashes.

func (*Hash) LessThan 

func (h *Hash) LessThan(k *Hash) bool

LessThan checks if h is less than k in lexicographic order. This is used to create a linear order on hashes.

func (*Hash) Short 

func (h *Hash) Short() string

Short returns a shortened version of the hash for easy viewing.

func (*Hash) XOREqual 

func (h *Hash) XOREqual(k *Hash)

XOREqual updates hash to be a xor with given argument.

type InsertHook 

type InsertHook func(Unit)

InsertHook is a function that performs some additional action on a unit before or after Insert.

type Orderer 

type Orderer interface {
	// AddPreunits sends to orderer preunits received from other committee member.
	AddPreunits(uint16, ...Preunit) []error
	// UnitsByID finds units with given IDs in Orderer.
	// Returns nil on the corresponding position if the requested unit is not present.
	// In case of forks returns all known units with a particular ID.
	UnitsByID(...uint64) []Unit
	// UnitsByHash finds units with given IDs in Orderer.
	// Returns nil on the corresponding position if the requested unit is not present.
	UnitsByHash(...*Hash) []Unit
	// MaxUnits returns maximal units per process for the given epoch. Returns nil if epoch not known.
	MaxUnits(EpochID) SlottedUnits
	// GetInfo returns DagInfo of the newest epoch.
	GetInfo() [2]*DagInfo
	// Delta returns all the units present in orderer that are above heights indicated by provided DagInfo.
	// That includes also all units from newer epochs.
	Delta([2]*DagInfo) []Unit
	// Start starts the orderer using provided RandomSourceFactory, Syncer, and Alerter.
	Start(RandomSourceFactory, Syncer, Alerter)
	Stop()
}

Orderer orders ordered orders into ordered order.

type PreblockMaker 

type PreblockMaker func([]Unit)

PreblockMaker is a function that is called on a slice of units forming a timing round that was produced by Orderer.

type Preunit 

type Preunit interface {
	// EpochID is used a unique identifier of a set of creators who participate in creation of a dag to which this unit belongs.
	EpochID() EpochID
	// Creator is the id of the process that created this unit.
	Creator() uint16
	// Signature of this unit.
	Signature() Signature
	// Hash value of this unit.
	Hash() *Hash
	// Height of a unit is the length of the path between this unit and a dealing unit in the (induced) sub-dag containing all units produced by the same creator.
	Height() int
	// View returns the crown of the dag below the unit.
	View() *Crown
	// Data is the slice of data contained in the unit.
	Data() core.Data
	// RandomSourceData is data contained in the unit needed to maintain
	// the common random source among processes.
	RandomSourceData() []byte
}

Preunit defines the most general interface for units. It describes unit "in a vacuum", without references to its parents.

type PrivateKey 

type PrivateKey interface {
	// Sign computes and returns a signature of a preunit.
	Sign(*Hash) Signature
	// Encode encodes the private key in base 64.
	Encode() string
}

PrivateKey used for signing units.

type PublicKey 

type PublicKey interface {
	// Verify checks if a preunit has a correct signature.
	Verify(Preunit) bool
	// Encode encodes the public key in base 64.
	Encode() string
}

PublicKey used for signature checking.

type RandomSource 

type RandomSource interface {
	// RandomBytes returns random bytes for a given process and level.
	RandomBytes(uint16, int) []byte
	// DataToInclude returns data which should be included in a unit based on its level and parents.
	DataToInclude([]Unit, int) ([]byte, error)
}

RandomSource represents a source of randomness needed to run the protocol. It specifies what kind of data should be included in units, and can use this data to generate random bytes.

type RandomSourceFactory 

type RandomSourceFactory interface {
	// NewRandomSource produces a randomness source for the provided dag.
	NewRandomSource(Dag) RandomSource
	// DealingData returns random source data that should be included in the dealing unit for the given epoch.
	DealingData(EpochID) ([]byte, error)
}

RandomSourceFactory produces RandomSource for the given dag

type Signature 

type Signature []byte

Signature of a unit.

type SlottedUnits 

type SlottedUnits interface {
	// Get all units in this container created by the process with the given id.
	// Note that in the main implementation, for efficiency reasons,
	// MODIFYING THE RETURNED VALUE DIRECTLY RESULTS IN UNDEFINED BEHAVIOUR!
	// Please avoid doing that.
	Get(uint16) []Unit
	// Set replaces all units in this container created by the process with the given id with given units.
	Set(uint16, []Unit)
	// Iterate through all units in this container, in chunks corresponding to different creator ids, until the given function returns false.
	Iterate(func([]Unit) bool)
}

SlottedUnits defines a container for storing slices of units and accessing them using their creator's id.

type Syncer 

type Syncer interface {
	// RequestGossip with the given committee member.
	RequestGossip(uint16)
	// RequestFetch send a request to the given committee member for units with given IDs.
	RequestFetch(uint16, []uint64)
	// Multicast a unit.
	Multicast(Unit)
	// Start syncer.
	Start()
	// Stop syncer.
	Stop()
}

Syncer syncs.

type Unit 

type Unit interface {
	Preunit
	// Parents of this unit.
	Parents() []Unit
	// Level of this unit in the dag, as defined in the Aleph protocol whitepaper.
	Level() int
	// AboveWithinProc checks if this unit is above the given unit produced by the same creator.
	AboveWithinProc(Unit) bool
	// Floor returns a slice of maximal units created by the given process that are strictly below this unit.
	Floor(uint16) []Unit
}

Unit is the main interface for unit that knows the list of its parents.

func MaximalByPid 

func MaximalByPid(parents []Unit, pid uint16) []Unit

MaximalByPid computes all maximal units produced by pid present in parents and their floors.

func Predecessor 

func Predecessor(u Unit) Unit

Predecessor of a unit is one of its parents, the one created by the same process as the given unit.

type UnitChecker 

type UnitChecker func(Unit, Dag) error

UnitChecker is a function that performs a check on Unit before Prepare.

type UnknownParents 

type UnknownParents struct {
	Amount int
}

UnknownParents is an error-like object used when trying to add a unit whose parents are not in the dag.

func NewUnknownParents 

func NewUnknownParents(howMany int) *UnknownParents

NewUnknownParents constructs a UnknownParents error for the given unit.

func (*UnknownParents) Error 

func (e *UnknownParents) Error() string

Error returns a (fixed) string description of a UnknownParents.

Source Files

View all Source files

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.