committee

README

Committee

The Committee represents the subset of Provisioners extracted at each Step in order to perform block hash voting. The Committee gets chosen according to a deterministic sortition.

Deterministic Sortition

Deterministic sortition is an optimization of cryptographic sortition introduced by Micali et al. It extends the functionality of cryptographic sortition in a Random Oracle setting in a non-interactive fashion, improving both the network throughput and space-efficiency.

Deterministic sortition is an algorithm that recursively hashes the public seed with situational parameters of each step, mapping the outcome to the current stakes of the Provisioners in order to extract a pseudo-random Committee, per step.

Values

NewProvisioner Event

| Field | Type | | opcode | uint8 | | PubKeyED | []byte | | PubKeyBLS | []byte | | stake | uint64 |

API

Committee is an interface that exposes the following functionalities:

- `IsMember([]byte, uint64, uint8)` bool: returns whether the ID of a provisioner (basically the `BLS Public Key`) is included in the committee
- `Quorum()` int: returns the number of Committee members needed to form a _quorum_. This quantity depends on the amount of available `Provisioners` but it is constant after a certain threshold

Additionally, the committee package exposes the NewExtractor function. It returns the basis for an implementation of the Committee interface, made up of a Store, and an Extractor.

Architecture

The Store is responsible for maintaining an up-to-date set of provisioners. The Extractor wraps around the Store, exposing functionality needed to create voting committees from this Store for any point in the consensus. The combination of the two provides a basis for other packages to create their own specific implementations of the Committee interface, so that the committee package may be re-used across the codebase.

Documentation

Index

• type Agreement
  • func NewAgreement(eventBroker wire.EventBroker, db database.DB) *Agreement
  • func (a *Agreement) IsMember(pubKeyBLS []byte, round uint64, step uint8) bool
  • func (a *Agreement) Pack(set sortedset.Set, round uint64, step uint8) uint64
  • func (a *Agreement) Quorum(round uint64) int
  • func (a *Agreement) Unpack(bitset uint64, round uint64, step uint8) sortedset.Set
• type Committee
• type Extractor
  • func NewExtractor(eventBroker wire.EventBroker, db database.DB) *Extractor
  • func (e *Extractor) UpsertCommitteeCache(round uint64, step uint8, size int) user.VotingCommittee
• type Foldable
• type Store
  • func (s *Store) AddProvisioner(m *bytes.Buffer) error
  • func (s *Store) Provisioners() *user.Provisioners
  • func (s *Store) RemoveExpiredProvisioners(m *bytes.Buffer) error
  • func (s *Store) RemoveProvisioner(m *bytes.Buffer) error

Types

type Agreement

type Agreement struct {
	*Extractor
}

func NewAgreement

func NewAgreement(eventBroker wire.EventBroker, db database.DB) *Agreement

func (*Agreement) IsMember

func (a *Agreement) IsMember(pubKeyBLS []byte, round uint64, step uint8) bool

IsMember checks if the BLS key belongs to one of the Provisioners in the committee

func (*Agreement) Pack

func (a *Agreement) Pack(set sortedset.Set, round uint64, step uint8) uint64

Pack creates a uint64 bitset representation of a Committee subset for a given round and step

func (*Agreement) Quorum

func (a *Agreement) Quorum(round uint64) int

Quorum returns the amount of votes to reach a quorum

func (*Agreement) Unpack

func (a *Agreement) Unpack(bitset uint64, round uint64, step uint8) sortedset.Set

Unpack the Committee subset from a uint64 bitset representation for a give round and step

type Committee

type Committee interface {
	IsMember([]byte, uint64, uint8) bool
	Quorum(uint64) int
}

Committee is the interface for operations depending on the set of Provisioners extracted for a given step

type Extractor

type Extractor struct {
	*Store
	// contains filtered or unexported fields
}

Extractor is a wrapper around the Store struct, and contains the phase-specific information, as well as a voting committee cache. It calls methods on the Store, passing its own parameters to extract the desired info for a specific phase.

func NewExtractor

func NewExtractor(eventBroker wire.EventBroker, db database.DB) *Extractor

NewExtractor returns a committee extractor which maintains its own store and cache.

func (*Extractor) UpsertCommitteeCache

func (e *Extractor) UpsertCommitteeCache(round uint64, step uint8, size int) user.VotingCommittee

UpsertCommitteeCache will return a voting committee for a given round, step and size. If the committee has not yet been produced before, it is put on the cache. If it has, it is simply retrieved and returned.

type Foldable

type Foldable interface {
	Committee
	Pack(sortedset.Set, uint64, uint8) uint64
	Unpack(uint64, uint64, uint8) sortedset.Set
}

Foldable represents a Committee which can be packed into a bitset, to drastically decrease the size needed for committee representation over the wire.

type Store

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

Store is the component that contains a set of provisioners, and provides access to this set, allowing clients to obtain consensus-related information. This struct is shared by Extractor structs in the node.

func (*Store) AddProvisioner

func (s *Store) AddProvisioner(m *bytes.Buffer) error

AddProvisioner will add a provisioner to the Store's Provisioners object.

func (*Store) Provisioners

func (s *Store) Provisioners() *user.Provisioners

Provisioners returns a copy of the user.Provisioners object maintained by the Store.

func (*Store) RemoveExpiredProvisioners

func (s *Store) RemoveExpiredProvisioners(m *bytes.Buffer) error

func (*Store) RemoveProvisioner

func (s *Store) RemoveProvisioner(m *bytes.Buffer) error

RemoveProvisioner will remove a provisioner from the Store's Provisioners objects.