selection

README

Selection Component

The Selector is the component appointed to collect the scores, verify the zero-knowledge proof thereto associated and to propagate the block hash associated with the highest score observed during a period of time denoted as timeLength. The block hash is then forwarded to the EventBus to be picked up by the Block Reducer

An abstract description of the Selection phase in the SBA* consensus protocol can be found here.

Values

Score Message

Field	Type
score	uint256
proof	proof
identity hash	uint256
seed	BLS signature
previous block hash	uint256
candidate block	block.Block

Architecture

The Selection component is implemented through the Phase struct. Internally, it carries a BlockGenerator in order to fully synchronize the creation of a candidate block and score, with the Selection phase. When the Selection component is called, the first thing it does is this block generation routine. Once finished (or if no block generator was actually initialized), queued events are flushed in order to catch up with any delays, and a listening loop is started. The selection component will listen on four channels:

• The internalScoreResult chan, on which it can receive a Score message from its own block generator - this message is then forwarded into the standard processing pipeline
• The evChan, which catches events coming from the network
• The timeOutChan, responsible for telling the Selection component when the time for the selection phase has ran out, and the component needs to wrap up its activites
• The ctx.Done chan, which notifies the Selection component of context cancellations, and allows for swift cleanup of the hanging goroutine

When an event comes through over the evChan, the following processing pipeline is followed:

1. Check if the event score is higher than the current bestEvent. If not, the flow ends here.
2. Verify the proof, included in the Score event. If the verification fails, the flow ends here.
3. The Score event is repropagated to the network.
4. The bestEvent field on the Selection component will now be set to the new Score event.

The purpose of this processing flow is to have the Score message with the highest score in memory when the timer expires. Once this timer expires, the message is returned and can be used to vote in the reduction step.

Documentation

Index

• Variables
• type Handler
• type Helper
  • func NewHelper(scoreToSpawn int) *Helper
  • func (h *Helper) RoundUpdate() consensus.RoundUpdate
  • func (h *Helper) Spawn() []message.Score
• type Phase
  • func New(next consensus.Phase, g blockgenerator.BlockGenerator, e *consensus.Emitter, ...) *Phase
  • func (p *Phase) Initialize(_ consensus.InternalPacket) consensus.PhaseFn
  • func (p *Phase) Run(parentCtx context.Context, queue *consensus.Queue, evChan chan message.Message, ...) consensus.PhaseFn
  • func (p *Phase) String() string
• type ScoreHandler
  • func NewScoreHandler(scoreVerifier transactions.Provisioner) *ScoreHandler
  • func (sh *ScoreHandler) LowerThreshold()
  • func (sh *ScoreHandler) Priority(first, second message.Score) bool
  • func (sh *ScoreHandler) ResetThreshold()
  • func (sh *ScoreHandler) Verify(ctx context.Context, round uint64, step uint8, m message.Score) error

Variables

var ProvisionerNr = 10

ProvisionerNr is the default amount of Provisioners utilized in the selection tests. This nr is just used to create the RoundUpdate and bares no importance in the selection step.

Types

type Handler

type Handler interface {
	Verify(context.Context, uint64, uint8, message.Score) error
	ResetThreshold()
	LowerThreshold()
	Priority(message.Score, message.Score) bool
}

Handler is an abstraction of the selection component event handler. It is primarily used for testing purposes, to bypass the zkproof verification.

type Helper

type Helper struct {
	*consensus.Emitter
	Round uint64
	Step  uint8

	P *user.Provisioners
	// contains filtered or unexported fields
}

Helper for reducing selection test boilerplate.

func NewHelper

func NewHelper(scoreToSpawn int) *Helper

NewHelper creates a Helper.

func (*Helper) RoundUpdate

func (h *Helper) RoundUpdate() consensus.RoundUpdate

RoundUpdate mocks a round update with the Round and Step embedded in the Helper.

func (*Helper) Spawn

func (h *Helper) Spawn() []message.Score

Spawn a number of score events.

type Phase

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

Phase is the implementation of the Selection step component.

func New

func New(next consensus.Phase, g blockgenerator.BlockGenerator, e *consensus.Emitter, timeout time.Duration, db database.DB) *Phase

New creates and launches the component which responsibility is to validate and select the best score among the blind bidders. The component publishes under the topic BestScoreTopic.

func (*Phase) Initialize

func (p *Phase) Initialize(_ consensus.InternalPacket) consensus.PhaseFn

Initialize returns the Phase state function for the next phase, and initializes it with the result from this phase.

func (*Phase) Run

func (p *Phase) Run(parentCtx context.Context, queue *consensus.Queue, evChan chan message.Message, r consensus.RoundUpdate, step uint8) consensus.PhaseFn

Run executes the logic for this phase. In this case the selection listens to new Score/Candidate messages.

func (*Phase) String

func (p *Phase) String() string

String as required by the interface PhaseFn.

type ScoreHandler

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

ScoreHandler manages the score threshold, performs verification of message.Score, keeps tab of the highest score so far.

func NewScoreHandler

func NewScoreHandler(scoreVerifier transactions.Provisioner) *ScoreHandler

NewScoreHandler returns a new instance if ScoreHandler.

func (*ScoreHandler) LowerThreshold

func (sh *ScoreHandler) LowerThreshold()

LowerThreshold lowers the threshold after a timespan when no BlockGenerator could send a valid score.

func (*ScoreHandler) Priority

func (sh *ScoreHandler) Priority(first, second message.Score) bool

Priority returns true if the first element has priority over the second, false otherwise.

func (*ScoreHandler) ResetThreshold

func (sh *ScoreHandler) ResetThreshold()

ResetThreshold resets the score threshold that sets the absolute minimum for a score to be eligible for sending.

func (*ScoreHandler) Verify

func (sh *ScoreHandler) Verify(ctx context.Context, round uint64, step uint8, m message.Score) error

Verify a score by delegating the ZK library to validate the proof.