user

README

Provisioners and Sortition

This package implements the data structure which holds the Provisioner committee, and implements methods on top of this committee in order to be able to extract voting committees which are eligible to decide on blocks during the SBA* consensus protocol.

Abstract

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.

Documentation

Index

• Constants
• func MarshalProvisioners(r *bytes.Buffer, p *Provisioners) error
• type Member
  • func (m *Member) AddStake(stake Stake)
  • func (m *Member) Copy() *Member
  • func (m *Member) RemoveStake(idx int)
  • func (m *Member) SubtractFromStake(value uint64) uint64
• type Provisioners
  • func NewProvisioners() *Provisioners
  • func UnmarshalProvisioners(r *bytes.Buffer) (Provisioners, error)
  • func (p *Provisioners) Add(pubKeyBLS []byte, value, reward, counter, eligibility uint64) error
  • func (p Provisioners) Copy() Provisioners
  • func (p Provisioners) CreateVotingCommittee(seed []byte, round uint64, step uint8, size int) VotingCommittee
  • func (p Provisioners) Format(f fmt.State, c rune)
  • func (p Provisioners) GenerateCommittees(seed []byte, round uint64, amount, step uint8, size int) []VotingCommittee
  • func (p Provisioners) GetMember(pubKeyBLS []byte) *Member
  • func (p Provisioners) GetRawPublicKeyBLS(pubKeyBLS []byte) []byte
  • func (p Provisioners) GetStake(pubKeyBLS []byte) (uint64, error)
  • func (p Provisioners) MarshalJSON() ([]byte, error)
  • func (p Provisioners) MemberAt(i int) (*Member, error)
  • func (p Provisioners) SubsetSizeAt(round uint64) int
  • func (p *Provisioners) TotalWeight() (totalWeight uint64)
• type Stake
  • func (s Stake) Format(f fmt.State, c rune)
• type VotingCommittee
  • func (v VotingCommittee) Equal(other *VotingCommittee) bool
  • func (v VotingCommittee) Format(f fmt.State, c rune)
  • func (v VotingCommittee) IsMember(pubKeyBLS []byte) bool
  • func (v VotingCommittee) MarshalJSON() ([]byte, error)
  • func (v VotingCommittee) MemberKeys() [][]byte
  • func (v VotingCommittee) Size() int

Constants

const BlsKeySize = 96

BlsKeySize size of public key.

const DUSK = uint64(100000000)

DUSK is one whole unit of DUSK. This is duplicated from wallet since otherwise we get into an import cycle including the transactions and users packages.

Functions

func MarshalProvisioners

func MarshalProvisioners(r *bytes.Buffer, p *Provisioners) error

MarshalProvisioners ...

Types

type Member

type Member struct {
	PublicKeyBLS    []byte  `json:"bls_key"`
	RawPublicKeyBLS []byte  `json:"raw_bls_key"`
	Stakes          []Stake `json:"stakes"`
}

Member contains the bytes of a provisioner's Ed25519 public key, the bytes of his BLS public key, and how much he has staked.

func (*Member) AddStake

func (m *Member) AddStake(stake Stake)

AddStake appends a stake to the stake set.

func (*Member) Copy

func (m *Member) Copy() *Member

Copy deep a Member.

func (*Member) RemoveStake

func (m *Member) RemoveStake(idx int)

RemoveStake removes a Stake (most likely because it expired). Note: At the moment there's a 1-to-1 relationship between provisioner and stake. In the future this could potentially change. See also github.com/dusk-network/rusk/issues/579.

func (*Member) SubtractFromStake

func (m *Member) SubtractFromStake(value uint64) uint64

SubtractFromStake detracts an amount `value` from the Stake of a Provisioner.

type Provisioners

type Provisioners struct {
	Set     sortedset.Set      `json:"set"`
	Members map[string]*Member `json:"members"`
}

Provisioners is a map of Members, and makes up the current set of provisioners.

func NewProvisioners

func NewProvisioners() *Provisioners

NewProvisioners instantiates the Provisioners sortedset of members.

func UnmarshalProvisioners

func UnmarshalProvisioners(r *bytes.Buffer) (Provisioners, error)

UnmarshalProvisioners unmarshal provisioner set from a buffer.

func (*Provisioners) Add

func (p *Provisioners) Add(pubKeyBLS []byte, value, reward, counter, eligibility uint64) error

Add a Member to the Provisioners by using the bytes of a BLS public key.

func (Provisioners) Copy

func (p Provisioners) Copy() Provisioners

Copy deeply a set of Provisioners.

func (Provisioners) CreateVotingCommittee

func (p Provisioners) CreateVotingCommittee(seed []byte, round uint64, step uint8, size int) VotingCommittee

CreateVotingCommittee will run the deterministic sortition function, which determines who will be in the committee for a given step and round. TODO: running this with weird setup causes infinite looping (to reproduce, hardcode `3` on MockProvisioners when calling agreement.NewHelper in the agreement tests).

func (Provisioners) Format

func (p Provisioners) Format(f fmt.State, c rune)

Format implements fmt.Formatter interface. Prints all members and its stakes.

func (Provisioners) GenerateCommittees

func (p Provisioners) GenerateCommittees(seed []byte, round uint64, amount, step uint8, size int) []VotingCommittee

GenerateCommittees pre-generates an `amount` of VotingCommittee of a specified `size` from a given `step`.

func (Provisioners) GetMember

func (p Provisioners) GetMember(pubKeyBLS []byte) *Member

GetMember returns a member of the provisioners from its BLS public key.

func (Provisioners) GetRawPublicKeyBLS

func (p Provisioners) GetRawPublicKeyBLS(pubKeyBLS []byte) []byte

GetRawPublicKeyBLS returns a member uncompressed BLS public key. Returns nil if member not found.

func (Provisioners) GetStake

func (p Provisioners) GetStake(pubKeyBLS []byte) (uint64, error)

GetStake will find a certain provisioner in the committee by BLS public key, and return their stake.

func (Provisioners) MarshalJSON

func (p Provisioners) MarshalJSON() ([]byte, error)

MarshalJSON allows to print Provisioners list in JSONFormatter.

func (Provisioners) MemberAt

func (p Provisioners) MemberAt(i int) (*Member, error)

MemberAt returns the Member at a certain index.

func (Provisioners) SubsetSizeAt

func (p Provisioners) SubsetSizeAt(round uint64) int

SubsetSizeAt returns how many provisioners are active on a given round. This function is used to determine the correct committee size for sortition in the case where one or more provisioner stakes have not yet become active, or have just expired. Note that this function will only give an accurate result if the round given is either identical or close to the current block height, as stakes are removed soon after they expire.

func (*Provisioners) TotalWeight

func (p *Provisioners) TotalWeight() (totalWeight uint64)

TotalWeight is the sum of all stakes of the provisioners.

type Stake

type Stake struct {
	Value       uint64 `json:"value"`
	Reward      uint64 `json:"reward"`
	Counter     uint64 `json:"counter"`
	Eligibility uint64 `json:"eligibility"`
}

Stake represents the Provisioner's stake.

func (Stake) Format

func (s Stake) Format(f fmt.State, c rune)

Format implements fmt.Formatter interface.

type VotingCommittee

type VotingCommittee struct {
	sortedset.Cluster
}

VotingCommittee represents a set of provisioners with voting rights at a certain point in the consensus. The set is sorted by the int value of the public key in increasing order (higher last).

func (VotingCommittee) Equal

func (v VotingCommittee) Equal(other *VotingCommittee) bool

Equal checks if two VotingCommittees are the same.

func (VotingCommittee) Format

func (v VotingCommittee) Format(f fmt.State, c rune)

Format implements fmt.Formatter interface.

func (VotingCommittee) IsMember

func (v VotingCommittee) IsMember(pubKeyBLS []byte) bool

IsMember checks if `pubKeyBLS` is within the VotingCommittee.

func (VotingCommittee) MarshalJSON

func (v VotingCommittee) MarshalJSON() ([]byte, error)

MarshalJSON ...

func (VotingCommittee) MemberKeys

func (v VotingCommittee) MemberKeys() [][]byte

MemberKeys returns the BLS public keys of all the members in a VotingCommittee.

func (VotingCommittee) Size

func (v VotingCommittee) Size() int

Size returns how many members there are in a VotingCommittee.