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

• func MarshalScore(r *bytes.Buffer, ev wire.Event) error
• func MockSelectionEventBuffer(hash []byte) *bytes.Buffer
• func UnmarshalScore(r *bytes.Buffer, ev wire.Event) error
• 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) GenerateEd25519Fields(ev consensus.Event) []byte
  • 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) []consensus.Event
  • func (h *Helper) StartSelection()
• type Score
  • func MockSelectionEvent(hash []byte) *Score
  • func (e Score) Equal(ev wire.Event) bool
  • func (e Score) Sender() []byte
• type ScoreHandler
  • func NewScoreHandler(bidList user.BidList) *ScoreHandler
  • func (sh *ScoreHandler) LowerThreshold()
  • func (sh *ScoreHandler) Priority(first, second Score) bool
  • func (sh *ScoreHandler) ResetThreshold()
  • func (sh *ScoreHandler) Verify(m Score) error
• type Selector
  • func NewComponent(publisher eventbus.Publisher, timeout time.Duration) *Selector
  • func (s *Selector) CollectGeneration(e consensus.Event) error
  • func (s *Selector) CollectScoreEvent(e consensus.Event) 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

Functions

func MarshalScore

func MarshalScore(r *bytes.Buffer, ev wire.Event) error

MarshalScore the buffer into a committee Event Field order is the following: * Blind Bid Fields [Score, Proof, Z, BidList, Seed, Candidate Block Hash]

func MockSelectionEventBuffer

func MockSelectionEventBuffer(hash []byte) *bytes.Buffer

MockSelectionEventBuffer mocks a Selection event, marshals it, and returns the resulting buffer.

func UnmarshalScore

func UnmarshalScore(r *bytes.Buffer, ev wire.Event) error

UnmarshalScore unmarshals the buffer into a Score Event Field order is the following: * Score Payload [score, proof, Z, BidList, Seed, Block Candidate Hash]

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(Score) error
	ResetThreshold()
	LowerThreshold()
	Priority(Score, 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 bytes.Buffer
	// 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) GenerateEd25519Fields

func (h *Helper) GenerateEd25519Fields(ev consensus.Event) []byte

GenerateEd25519Fields will return the Ed25519 header fields for a given consensus event.

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) []consensus.Event

Spawn a set of score events.

func (*Helper) StartSelection

func (h *Helper) StartSelection()

StartSelection forces the Selector to start the selection

type Score

type Score struct {
	Score         []byte
	Proof         []byte
	Z             []byte
	BidListSubset []byte
	PrevHash      []byte
	Seed          []byte
	VoteHash      []byte
}

Score represents the Score Message with the fields consistent with the Blind Bid data structure

func MockSelectionEvent

func MockSelectionEvent(hash []byte) *Score

MockSelectionEvent mocks a Selection event and returns it.

func (Score) Equal

func (e Score) Equal(ev wire.Event) bool

Equal as specified in the Event interface

func (Score) Sender

func (e Score) Sender() []byte

Sender of a Score event is the anonymous Z

type ScoreHandler

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

func NewScoreHandler

func NewScoreHandler(bidList user.BidList) *ScoreHandler

func (*ScoreHandler) LowerThreshold

func (sh *ScoreHandler) LowerThreshold()

func (*ScoreHandler) Priority

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

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

func (*ScoreHandler) ResetThreshold

func (sh *ScoreHandler) ResetThreshold()

func (*ScoreHandler) Verify

func (sh *ScoreHandler) Verify(m Score) error

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(e consensus.Event) error

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

func (*Selector) CollectScoreEvent

func (s *Selector) CollectScoreEvent(e consensus.Event) 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.