consensus

README

Consensus

This package implements all needed components to run the SBA* consensus algorithm in isolation. This means, that all the "pieces" of the consensus are housed within this package, including communication infrastructure and testing frameworks. However, it still needs to be put together in order to have a fully running consensus. This code is defined in the loop package in this repo.

Values

Message Header

Field	Type
pubkeyBLS	BLS Signature
round	uint64
step	uint64
blockhash	uint256

Documentation

Index

• func InitAcceptedBlockUpdate(subscriber eventbus.Subscriber) (chan block.Block, uint32)
• func MockMember(keys key.Keys) *user.Member
• func MockNewBlockMsg(t *testing.T, hdr *header.Header) message.Message
• func MockProvisioners(amount int) (*user.Provisioners, []key.Keys)
• func WithFields(round uint64, step uint8, eventName string, hash, blsPubKey []byte, ...) *log.Entry
• type CandidateVerificationFunc
• type ControlFn
• type Controller
• type Emitter
  • func MockEmitter(consTimeout time.Duration) *Emitter
  • func StupidEmitter() (*Emitter, *user.Provisioners)
  • func (e *Emitter) Gossip(msg message.Message) error
  • func (e *Emitter) Kadcast(msg message.Message) error
  • func (e *Emitter) Republish(msg message.Message) error
  • func (e *Emitter) Sign(h header.Header) ([]byte, error)
• type ExecuteTxsFunc
• type InternalPacket
• type Phase
  • func MockPhase(cb func(ctx context.Context) bool) Phase
• type PhaseFn
• type Publisher
  • func NewPublisher(publisher eventbus.Publisher) *Publisher
  • func (p *Publisher) Process(srcPeerID string, msg message.Message) ([]bytes.Buffer, error)
• type Queue
  • func NewQueue() *Queue
  • func (eq *Queue) Clear(round uint64)
  • func (eq *Queue) Flush(round uint64) []message.Message
  • func (eq *Queue) GetEvents(round uint64, step uint8) []message.Message
  • func (eq *Queue) PutEvent(round uint64, step uint8, m message.Message)
• type Results
• type RoundUpdate
  • func MockRoundUpdate(round uint64, p *user.Provisioners) RoundUpdate
  • func (r RoundUpdate) Copy() payload.Safe
• type TestCallback
• type TestPhase
  • func NewTestPhase(t *testing.T, callback TestCallback, streamer *eventbus.GossipStreamer) *TestPhase
  • func (t *TestPhase) Initialize(sv InternalPacket) PhaseFn
  • func (t *TestPhase) Run(_ context.Context, queue *Queue, _ chan message.Message, _ RoundUpdate, ...) PhaseFn
  • func (t *TestPhase) String() string

Functions

func InitAcceptedBlockUpdate

func InitAcceptedBlockUpdate(subscriber eventbus.Subscriber) (chan block.Block, uint32)

InitAcceptedBlockUpdate init listener to get updates about lastly accepted block in the chain.

func MockMember

func MockMember(keys key.Keys) *user.Member

MockMember mocks a Provisioner.

func MockNewBlockMsg

func MockNewBlockMsg(t *testing.T, hdr *header.Header) message.Message

MockNewBlockMsg ...

func MockProvisioners

func MockProvisioners(amount int) (*user.Provisioners, []key.Keys)

MockProvisioners mock a Provisioner set.

func WithFields

func WithFields(round uint64, step uint8, eventName string, hash,
	blsPubKey []byte, sVotingCommittee *user.VotingCommittee,
	sVotedCommittee *sortedset.Cluster, p *user.Provisioners) *log.Entry

WithFields builds a list of common Consensus logging fields. It also adds extra fields for TraceLevel only.

Types

type CandidateVerificationFunc

type CandidateVerificationFunc func(block.Block) error

CandidateVerificationFunc is a callback used to verify candidate blocks after the conclusion of the first reduction step.

type ControlFn

type ControlFn func(context.Context, *Queue, <-chan message.Message, <-chan message.Message, RoundUpdate) Results

ControlFn represents the asynchronous loop controlling the commencement of the Phase transition.

type Controller

type Controller interface {
	// GetControlFn returns a ControlFn.
	GetControlFn() ControlFn
}

Controller is a factory for the ControlFn. It basically relates to the Agreement, which needs a different execution each round.

type Emitter

type Emitter struct {
	EventBus    *eventbus.EventBus
	RPCBus      *rpcbus.RPCBus
	Keys        key.Keys
	TimerLength time.Duration
}

Emitter is a simple struct to pass the communication channels that the steps should be able to emit onto.

func MockEmitter

func MockEmitter(consTimeout time.Duration) *Emitter

MockEmitter is a utility to quickly wire up an emitter in tests.

func StupidEmitter

func StupidEmitter() (*Emitter, *user.Provisioners)

StupidEmitter ...

func (*Emitter) Gossip

func (e *Emitter) Gossip(msg message.Message) error

Gossip concatenates the topic, the header and the payload, and gossips it to the rest of the network.

func (*Emitter) Kadcast

func (e *Emitter) Kadcast(msg message.Message) error

Kadcast propagates a message in Kadcast network.

func (*Emitter) Republish

func (e *Emitter) Republish(msg message.Message) error

Republish reroutes message propagation to either Gossip or Kadcast network.

func (*Emitter) Sign

func (e *Emitter) Sign(h header.Header) ([]byte, error)

Sign a header.

type ExecuteTxsFunc

type ExecuteTxsFunc func(ctx context.Context, txs []transactions.ContractCall, blockHeight uint64) ([]transactions.ContractCall, []byte, error)

ExecuteTxsFunc is a callback used to retrieve a valid set of txs.

type InternalPacket

type InternalPacket interface {
	payload.Safe
	State() header.Header
}

InternalPacket is a specialization of the Payload of message.Message. It is used to unify messages used by the consensus, which need to carry the header.Header for consensus specific operations.

type Phase

type Phase interface {
	// Initialize accepts as an
	// argument an interface, usually a message or the result  of the state
	// function execution. It provides the capability to create a closure of sort.
	Initialize(InternalPacket) PhaseFn
}

Phase is used whenever an instantiation is needed.

func MockPhase

func MockPhase(cb func(ctx context.Context) bool) Phase

MockPhase mocks up a consensus phase. It accepts a (recursive) function which returns a boolean indicating whether the consensus loop needs to return, or an error. If function returns true, it halts the consensus loop. An error indicates unrecoverable situation.

type PhaseFn

type PhaseFn interface {
	// Run the phase function.
	Run(context.Context, *Queue, chan message.Message, RoundUpdate, uint8) PhaseFn

	// String returns the description of this phase function.
	String() string
}

PhaseFn represents the recursive consensus state function.

type Publisher

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

Publisher is used to direct consensus messages from the peer.MessageProcessor to the consensus components.

func NewPublisher

func NewPublisher(publisher eventbus.Publisher) *Publisher

NewPublisher returns an initialized Publisher.

func (*Publisher) Process

func (p *Publisher) Process(srcPeerID string, msg message.Message) ([]bytes.Buffer, error)

Process incoming consensus messages. Satisfies the peer.ProcessorFunc interface.

type Queue

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

Queue is a Queue of Events grouped by rounds and steps. It is thread-safe through a sync.RWMutex. TODO: entries should become buntdb instead.

func NewQueue

func NewQueue() *Queue

NewQueue creates a new Queue. It is primarily used by Collectors to temporarily store messages not yet relevant to the collection process.

func (*Queue) Clear

func (eq *Queue) Clear(round uint64)

Clear the queue. This method swaps the internal `entries` map, to avoid a situation where memory is continuously allocated and never freed.

func (*Queue) Flush

func (eq *Queue) Flush(round uint64) []message.Message

Flush all events stored for a specific round from the queue, and return them Messages are sorted giving priority to AggrAgreement and then to their step.

func (*Queue) GetEvents

func (eq *Queue) GetEvents(round uint64, step uint8) []message.Message

GetEvents returns the events for a round and step.

func (*Queue) PutEvent

func (eq *Queue) PutEvent(round uint64, step uint8, m message.Message)

PutEvent stores an Event at a given round and step.

type Results

type Results struct {
	Blk block.Block
	Err error
}

Results carries the eventual consensus results.

type RoundUpdate

type RoundUpdate struct {
	Round           uint64
	P               user.Provisioners
	Seed            []byte
	Hash            []byte
	LastCertificate *block.Certificate
}

RoundUpdate carries the data about the new Round, such as the active Provisioners, the BidList, the Seed and the Hash.

func MockRoundUpdate

func MockRoundUpdate(round uint64, p *user.Provisioners) RoundUpdate

MockRoundUpdate mocks a round update.

func (RoundUpdate) Copy

func (r RoundUpdate) Copy() payload.Safe

Copy complies with message.Safe interface. It returns a deep copy of the message safe to publish to multiple subscribers.

type TestCallback

type TestCallback func(*require.Assertions, InternalPacket, *eventbus.GossipStreamer)

TestCallback is a callback to allow for table testing based on step results.

type TestPhase

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

TestPhase is the phase to inject in the step under test to allow for table testing. It treats the packet injected through the Fn method as the result to test.

func NewTestPhase

func NewTestPhase(t *testing.T, callback TestCallback, streamer *eventbus.GossipStreamer) *TestPhase

NewTestPhase returns a Phase implementation suitable for testing steps.

func (*TestPhase) Initialize

func (t *TestPhase) Initialize(sv InternalPacket) PhaseFn

Initialize is used by the step under test to provide its result.

func (*TestPhase) Run

func (t *TestPhase) Run(_ context.Context, queue *Queue, _ chan message.Message, _ RoundUpdate, step uint8) PhaseFn

Run does nothing else than delegating to the specified callback.

func (*TestPhase) String

func (t *TestPhase) String() string