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 MockProvisioners(amount int) (*user.Provisioners, []key.Keys)
• func MockScoreMsg(t *testing.T, hdr *header.Header) message.Message
• type CandidateVerificationFunc
• type ControlFn
• type Controller
• type Emitter
  • func MockEmitter(consTimeout time.Duration, proxy transactions.Proxy) *Emitter
  • func StupidEmitter() (*Emitter, *user.Provisioners)
  • func (e *Emitter) Gossip(msg message.Message) error
  • func (e *Emitter) Sign(h header.Header) ([]byte, error)
• 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
• type Threshold
  • func NewThreshold() *Threshold
  • func (t *Threshold) Exceeds(score []byte) bool
  • func (t *Threshold) Lower()
  • func (t *Threshold) Reset()

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 MockProvisioners

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

MockProvisioners mock a Provisioner set.

func MockScoreMsg

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

MockScoreMsg ...

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, 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
	Proxy       transactions.Proxy
	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, proxy transactions.Proxy) *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) Sign

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

Sign a header.

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.

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.

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

type Threshold

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

Threshold is a number which proof scores should be compared against. If a proof score does not exceed the Threshold value, it should be discarded.

func NewThreshold

func NewThreshold() *Threshold

NewThreshold returns an initialized Threshold.

func (*Threshold) Exceeds

func (t *Threshold) Exceeds(score []byte) bool

Exceeds checks whether the Threshold exceeds a given score.

func (*Threshold) Lower

func (t *Threshold) Lower()

Lower the Threshold by cutting it in half.

func (*Threshold) Reset

func (t *Threshold) Reset()

Reset the Threshold to its normal lower limit.