selection

README

Selection

Abstract

Block Generators (a role taken outside of the Provisioner) participate in a non-interactive lottery to be able to forge a candidate block. In order to decide which Block to select among the various candidates, the Block Generators propagate a score associated with their candidate block, which is the result of the lottery run in a non-interactive fashion. Together with the score, the Block Generators publish a zero-knowledge proof of correctness of the score computation according to the rules outlined in the Blind Bid algorithm (LINK HERE).

The Score 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

Values

Score Message

Field	Type
score	uint256
proof	proof
identity hash	uint256
bid list	[]byte (variable size)
seed	BLS signature
previous block hash	uint256
candidate block hash	uint256

Architecture

The Selector is triggered by a Generation message, which denotes the reset of the consensus loop. Upon receiving this message, the Selector will start a timer. Between the start and the expiry of the timer, the Selector will enable streaming of Score events. Any time a Score event is received, it goes through this processing flow:

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 will now be set to the new Score event.

The purpose of this processing flow is to have the Score event with the highest score in memory when the timer expires. Once this timer expires, the selector will pause event streaming, and publish this Score event internally, under the BestScore topic.

Documentation

Index

• type Factory
  • func NewFactory(bus eventbus.Broker, timeout time.Duration) *Factory
  • func (f *Factory) Instantiate() consensus.Component
• type Handler
• type Helper
  • func NewHelper(eb *eventbus.EventBus) *Helper
  • func (h *Helper) Initialize(ru consensus.RoundUpdate)
  • func (h *Helper) SendBatch(hash []byte)
  • func (h *Helper) SetHandler(handler Handler)
  • func (h *Helper) Spawn(hash []byte) []message.Score
  • func (h *Helper) StartSelection()
• type ScoreHandler
  • func NewScoreHandler(bidList user.BidList) *ScoreHandler
  • func (sh *ScoreHandler) LowerThreshold()
  • func (sh *ScoreHandler) Priority(first, second message.Score) bool
  • func (sh *ScoreHandler) ResetThreshold()
  • func (sh *ScoreHandler) Verify(m message.Score) error
• type Selector
  • func NewComponent(publisher eventbus.Publisher, timeout time.Duration) *Selector
  • func (s *Selector) CollectGeneration(packet consensus.InternalPacket) error
  • func (s *Selector) CollectScoreEvent(packet consensus.InternalPacket) error
  • func (s *Selector) Finalize()
  • func (s *Selector) ID() uint32
  • func (s *Selector) IncreaseTimeOut()
  • func (s *Selector) Initialize(eventPlayer consensus.EventPlayer, signer consensus.Signer, ...) []consensus.TopicListener

Types

type Factory

type Factory struct {
	Bus eventbus.Broker
	// contains filtered or unexported fields
}

Factory creates the selection component.

func NewFactory

func NewFactory(bus eventbus.Broker, timeout time.Duration) *Factory

NewFactory instantiates a Factory.

func (*Factory) Instantiate

func (f *Factory) Instantiate() consensus.Component

Instantiate a Selector and return it. Implements consensus.ComponentFactory.

type Handler

type Handler interface {
	Verify(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 {
	*Factory
	BidList  user.BidList
	Selector *Selector
	*consensus.SimplePlayer

	BestScoreChan chan message.Message
	// contains filtered or unexported fields
}

Helper for reducing selection test boilerplate

func NewHelper

func NewHelper(eb *eventbus.EventBus) *Helper

NewHelper creates a Helper

func (*Helper) Initialize

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

Initialize the selector with the given round update.

func (*Helper) SendBatch

func (h *Helper) SendBatch(hash []byte)

SendBatch generates a batch of score events and sends them to the selector.

func (*Helper) SetHandler

func (h *Helper) SetHandler(handler Handler)

SetHandler sets the handler on the Selector. Used for bypassing zkproof verification calls during tests.

func (*Helper) Spawn

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

Spawn a set of score events.

func (*Helper) StartSelection

func (h *Helper) StartSelection()

StartSelection forces the Selector to start the selection

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(bidList user.BidList) *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(m message.Score) error

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

type Selector

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

Selector is the component responsible for collecting score events and propagating the best one after a timeout.

func NewComponent

func NewComponent(publisher eventbus.Publisher, timeout time.Duration) *Selector

NewComponent 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 (*Selector) CollectGeneration

func (s *Selector) CollectGeneration(packet consensus.InternalPacket) error

CollectGeneration signals the selection start by triggering `EventPlayer.Play`

func (*Selector) CollectScoreEvent

func (s *Selector) CollectScoreEvent(packet consensus.InternalPacket) error

CollectScoreEvent checks the score of an incoming Event and, in case it has a higher score, verifies, propagates and saves it

func (*Selector) Finalize

func (s *Selector) Finalize()

Finalize pauses event streaming and stops the timer. Implements consensus.Component.

func (*Selector) ID

func (s *Selector) ID() uint32

ID returns the ID of the Score message Listener. Implements consensus.Component

func (*Selector) IncreaseTimeOut

func (s *Selector) IncreaseTimeOut()

IncreaseTimeOut increases the timeout after a failed selection

func (*Selector) Initialize

func (s *Selector) Initialize(eventPlayer consensus.EventPlayer, signer consensus.Signer, r consensus.RoundUpdate) []consensus.TopicListener

Initialize the Selector, by creating the handler and returning the needed Listeners. Implements consensus.Component.