agreement

README

Agreement component

This package implements the component which performs the Agreement Phase of the consensus.

Values

Block Agreement Event

Field	Type
Aggregated public keys*	BLS APK
Committee bit-representation*	uint64
Aggregated signatures*	BLS Signature
Signature of all fields	BLS Signature

* These fields appear twice, once for each step of Reduction.

Architecture

The Agreement component is implemented within the Loop struct, found in step.go. This struct contains all the data and logic that the agreement component needs to do its job. Unlike the other consensus components, the Loop struct implements ControlFn, as the component works slightly differently to the others - it needs to be started concurrently to the other components, and not in sequence.

The agreement component is given access to the DB, and has an instance of a candidate.Requestor, which can be used to request certain pending blocks from the network.

Main component

When the agreement component starts up (with the Run function), it flushes all queued agreement events for the given round, and passes them directly to the processing function (collectEvent). Afterwards, the component starts listening on three different channels:

• The agreementChan, which transports agreement events from the eventbus to the agreement component
• The CollectedVotesChan, which collects final results from the accumulator
• The ctx.Done channel, which notifies the agreement component of context cancellations

Events sent through the agreementChan will go immediately to the processing function, collectEvent. This sends the event off to the local Accumulator.

Once a final result is received through the CollectedVotesChan, the agreement component checks the DB to see if a candidate for the resulting block hash exists. If not, it makes use of its own candidate.Requestor to fetch it from the network, instead. The winning block is then returned, and the agreement component will stop running.

Accumulator

For each call to the Run function, the agreement component instantiates a new Accumulator. This component is responsible for sorting agreement events by step, and keeps track of how many times an event is seen for a given step. Internally, it uses a handler which has access to the consensus committee - allowing the Accumulator to perform verification, as well as keep track of how close a given step is to quorum. Once a step reaches said quorum, the Accumulator sends back the collected votes for this step, through the CollectedVotesChan, sending it back directly to the main agreement component.

Under the hood, the Accumulator makes use of a thread pool in order to parallelize event verification and storage. The amount of workers is configurable, but is standardly set to 4.

To store events, the Accumulator uses a store, which is a thread-safe wrapper around a map.

Documentation

Index

• Constants
• Variables
• func AggregatePks(p *user.Provisioners, subcommittee sortedset.Set) ([]byte, error)
• func NewHandler(keys key.Keys, p user.Provisioners, seed []byte) *handler
• type Accumulator
  • func (a *Accumulator) Accumulate()
  • func (a *Accumulator) CreateWorkers(amount int)
  • func (a *Accumulator) Process(ev message.Agreement)
  • func (a *Accumulator) Stop()
• type Handler
• type Helper
  • func NewHelper(provisioners int) *Helper
  • func (hlp *Helper) RoundUpdate(hash []byte) consensus.RoundUpdate
  • func (hlp *Helper) Spawn(hash []byte) []message.Agreement
• type Loop
  • func New(e *consensus.Emitter, db database.DB, requestor *candidate.Requestor) *Loop
  • func (s *Loop) GetControlFn() consensus.ControlFn
  • func (s *Loop) Run(ctx context.Context, roundQueue *consensus.Queue, ...) consensus.Results

Constants

const MaxCommitteeSize = 64

MaxCommitteeSize represents the maximum size of the committee for an Agreement quorum.

Variables

var WorkerAmount = 4

WorkerAmount sets the number of concurrent workers to concurrently verify Agreement messages.

Functions

func AggregatePks

func AggregatePks(p *user.Provisioners, subcommittee sortedset.Set) ([]byte, error)

AggregatePks reconstructs an aggregated BLS public key from a subcommittee.

func NewHandler

func NewHandler(keys key.Keys, p user.Provisioners, seed []byte) *handler

NewHandler returns an initialized handler.

Types

type Accumulator

type Accumulator struct {
	CollectedVotesChan chan []message.Agreement
	// contains filtered or unexported fields
}

Accumulator is an event accumulator, that will accumulate events until it reaches a certain threshold.

func (*Accumulator) Accumulate

func (a *Accumulator) Accumulate()

Accumulate agreements per block hash until a quorum is reached or a stop is detected (by closing the internal event channel). Supposed to run in a goroutine.

func (*Accumulator) CreateWorkers

func (a *Accumulator) CreateWorkers(amount int)

CreateWorkers creates an amount of workers that verify Agreement messages concurrently.

func (*Accumulator) Process

func (a *Accumulator) Process(ev message.Agreement)

Process a received Event, by passing it to a worker in the worker pool (if the event sender is part of the voting committee).

func (*Accumulator) Stop

func (a *Accumulator) Stop()

Stop kills the thread pool and shuts down the Accumulator.

type Handler

type Handler interface {
	AmMember(uint64, uint8) bool
	IsMember([]byte, uint64, uint8) bool
	Committee(uint64, uint8) user.VotingCommittee
	Quorum(uint64) int
	VotesFor([]byte, uint64, uint8) int
	Verify(message.Agreement) error
}

Handler interface is handy for tests.

type Helper

type Helper struct {
	*consensus.Emitter
	P                *user.Provisioners
	Nr               int
	ProvisionersKeys []key.Keys
	Round            uint64
}

Helper is a struct that facilitates sending semi-real Events with minimum effort.

func NewHelper

func NewHelper(provisioners int) *Helper

NewHelper creates a Helper.

func (*Helper) RoundUpdate

func (hlp *Helper) RoundUpdate(hash []byte) consensus.RoundUpdate

RoundUpdate creates a valid RoundUpdate for the current round, based on the information passed to this Helper (i.e. round, Provisioners).

func (*Helper) Spawn

func (hlp *Helper) Spawn(hash []byte) []message.Agreement

Spawn a number of different valid events to the Agreement component bypassing the EventBus.

type Loop

type Loop struct {
	*consensus.Emitter
	// contains filtered or unexported fields
}

Loop is the struct holding the state of the Agreement phase which does not change during the consensus loop.

func New

func New(e *consensus.Emitter, db database.DB, requestor *candidate.Requestor) *Loop

New creates a round-specific agreement step.

func (*Loop) GetControlFn

func (s *Loop) GetControlFn() consensus.ControlFn

GetControlFn is a factory method for the ControlFn. It makes it possible for the consensus loop to mock the agreement.

func (*Loop) Run

func (s *Loop) Run(ctx context.Context, roundQueue *consensus.Queue, agreementChan <-chan message.Message, aggrAgreementChan <-chan message.Message, r consensus.RoundUpdate) consensus.Results

Run the agreement step loop.