committee

Documentation

Overview

(c) 2020 Dapper Labs - ALL RIGHTS RESERVED

(c) 2020 Dapper Labs - ALL RIGHTS RESERVED

Index

• func New(protocolState protocol.State, blockTranslator BlockTranslator, ...) hotstuff.Committee
• func NewMainConsensusCommitteeState(protocolState protocol.State, myID flow.Identifier, ...) (hotstuff.Committee, error)
• func WeightedRandomSelection(seed []byte, count int, weights []uint64) ([]int, error)
• type BlockTranslator
  • func NewBlockTranslator(b blockTranslatorFunc) BlockTranslator
• type Committee
  • func (c *Committee) DKG(blockID flow.Identifier) (hotstuff.DKG, error)
  • func (c *Committee) Identities(blockID flow.Identifier, selector flow.IdentityFilter) (flow.IdentityList, error)
  • func (c *Committee) Identity(blockID flow.Identifier, participantID flow.Identifier) (*flow.Identity, error)
  • func (c *Committee) LeaderForView(view uint64) (flow.Identifier, error)
  • func (c *Committee) Self() flow.Identifier
• type CommitteeMetricsWrapper
  • func NewMetricsWrapper(committee hotstuff.Committee, metrics module.HotstuffMetrics) *CommitteeMetricsWrapper
  • func (w CommitteeMetricsWrapper) DKG(blockID flow.Identifier) (hotstuff.DKG, error)
  • func (w CommitteeMetricsWrapper) Identities(blockID flow.Identifier, selector flow.IdentityFilter) (flow.IdentityList, error)
  • func (w CommitteeMetricsWrapper) Identity(blockID flow.Identifier, participantID flow.Identifier) (*flow.Identity, error)
  • func (w CommitteeMetricsWrapper) LeaderForView(view uint64) (flow.Identifier, error)
  • func (w CommitteeMetricsWrapper) Self() flow.Identifier
• type LeaderSelection
  • func ComputeLeaderSelectionFromSeed(epochStartView uint64, seed []byte, count int, identities flow.IdentityList) (*LeaderSelection, error)
  • func (l LeaderSelection) LeaderIndexForView(view uint64) (int, error)
• type Static
  • func NewStaticCommittee(participants flow.IdentityList, myID flow.Identifier, ...) (*Static, error)
  • func (s Static) DKG(_ flow.Identifier) (hotstuff.DKG, error)
  • func (s Static) Identities(_ flow.Identifier, selector flow.IdentityFilter) (flow.IdentityList, error)
  • func (s Static) Identity(_ flow.Identifier, participantID flow.Identifier) (*flow.Identity, error)
  • func (s Static) LeaderForView(_ uint64) (flow.Identifier, error)
  • func (s Static) Self() flow.Identifier

Functions

func New

func New(
	protocolState protocol.State,
	blockTranslator BlockTranslator,
	myID flow.Identifier,
	membersFilter flow.IdentityFilter,
	epochParticipants flow.IdentifierList,
	leaderSelection *LeaderSelection,
) hotstuff.Committee

New creates HotStuff committee. This is the generic constructor covering all potential cases. It requires:

• protocolState: the protocol state for the entire network
• blockTranslator: translates a block from the current HotStuff committee to a block of the main consensus committee to determine legitimacy of nodes
• myID: ID of the current node. CAUTION: this does not make the current node part of the HotStuff committee
• membersFilter: filter which retains only legitimate participants for the current consensus instance. It must filter for: node role, non-zero stake, and potentially the collector cluster (if applicable)
• epochParticipants: all nodes that were part of the initially released list of participants for this HotStuff instance. All participants for the current Epoch retain their spot as primaries for the respective views (even if they are slashed!)

While you can use this constructor to generate a committee state for the main consensus, the function `NewMainConsensusCommitteeState` provides a more concise API.

func NewMainConsensusCommitteeState

func NewMainConsensusCommitteeState(protocolState protocol.State, myID flow.Identifier, leaderSelection *LeaderSelection) (hotstuff.Committee, error)

NewMainConsensusCommitteeState creates HotStuff committee consisting of the MAIN CONSENSUS NODES. It requires:

• protocolState: the protocol state for the entire network
• myID: ID of the current node. CAUTION: this does not make the current node part of the HotStuff committee

For constructing committees for other HotStuff instances (such as collector HotStuff instances), please use the generic `New` function.

func WeightedRandomSelection

func WeightedRandomSelection(seed []byte, count int, weights []uint64) ([]int, error)

WeightedRandomSelection - given a seed and a given count, pre-generate the indexs of leader. The chance to be selected as leader is proportional to its weight. If an identity has 0 stake (weight is 0), it won't be selected as leader. This algorithm is essentially Fitness proportionate selection: See https://en.wikipedia.org/wiki/Fitness_proportionate_selection

Types

type BlockTranslator

type BlockTranslator interface {

	// Translate returns the ID of the block on the main chain that should be
	// used as a reference point when assessing validity of the input block.
	// For consensus nodes, this is the identity function, since the main
	// consensus chain directly contains all staking information. For collector
	// clusters, this returns the reference block ID from the cluster block's
	// payload (ideally the most recently finalized block on the main chain).
	Translate(blockID flow.Identifier) (flow.Identifier, error)
}

BlockTranslator is a support component for determining a reference point in the protocol state to use when assessing validity of a block.

func NewBlockTranslator

func NewBlockTranslator(b blockTranslatorFunc) BlockTranslator

NewBlockTranslator returns a block translator that simply uses the input function.

NOTE: for convenience in testing and within this package.

type Committee

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

Committee accounts for the fact that we might have multiple HotStuff instances (collector committees and main consensus committee). Each hostuff instance is supposed to have a dedicated Committee state. A Committee provides subset of the protocol.State, which is restricted to exactly those nodes that participate in the current HotStuff instance: the state of all legitimate HotStuff participants for the specified block. Legitimate HotStuff participants have NON-ZERO STAKE.

The intended use case is to support collectors running HotStuff within Flow. Specifically, the collectors produced their own blocks, independently of the Consensus Nodes (aka the main consensus). Given a collector block, some logic is required to find the main consensus block for determining the valid collector-HotStuff participants.

func (*Committee) DKG

func (c *Committee) DKG(blockID flow.Identifier) (hotstuff.DKG, error)

DKG returns the DKG info for the given block.

func (*Committee) Identities

func (c *Committee) Identities(blockID flow.Identifier, selector flow.IdentityFilter) (flow.IdentityList, error)

Identities returns a IdentityList with legitimate HotStuff participants for the specified block. The list of participants is filtered by the provided selector. The returned list of HotStuff participants

• contains nodes that are allowed to sign the specified block (legitimate participants with NON-ZERO STAKE)
• is ordered in the canonical order
• contains no duplicates.

The list of all legitimate HotStuff participants for the specified block can be obtained by using `filter.Any`

func (*Committee) Identity

func (c *Committee) Identity(blockID flow.Identifier, participantID flow.Identifier) (*flow.Identity, error)

Identity returns the full Identity for specified HotStuff participant. The node must be a legitimate HotStuff participant with NON-ZERO STAKE at the specified block. ERROR conditions:

• ErrInvalidSigner if participantID does NOT correspond to a _staked_ HotStuff participant at the specified block.

func (*Committee) LeaderForView

func (c *Committee) LeaderForView(view uint64) (flow.Identifier, error)

LeaderForView returns the identity of the leader for a given view. CAUTION: per liveness requirement of HotStuff, the leader must be fork-independent.

Therefore, a node retains its proposer view slots even if it is slashed.
Its proposal is simply considered invalid, as it is not from a legitimate participant.

Can error if view is in a future Epoch for which the HotStuff committee hasn't been determined yet.

func (*Committee) Self

func (c *Committee) Self() flow.Identifier

Self returns our own node identifier. TODO: ultimately, the own identity of the node is necessary for signing.

Ideally, we would move the method for checking whether an Identifier refers to this node to the signer.
This would require some refactoring of EventHandler (postponed to later)

type CommitteeMetricsWrapper

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

CommitteeMetricsWrapper implements the hotstuff.Committee interface. It wraps a hotstuff.Committee instance and measures the time which the HotStuff's core logic spends in the hotstuff.Committee component, i.e. the time determining consensus committee relations. The measured time durations are reported as values for the CommitteeProcessingDuration metric.

func NewMetricsWrapper

func NewMetricsWrapper(committee hotstuff.Committee, metrics module.HotstuffMetrics) *CommitteeMetricsWrapper

func (CommitteeMetricsWrapper) DKG

func (w CommitteeMetricsWrapper) DKG(blockID flow.Identifier) (hotstuff.DKG, error)

func (CommitteeMetricsWrapper) Identities

func (w CommitteeMetricsWrapper) Identities(blockID flow.Identifier, selector flow.IdentityFilter) (flow.IdentityList, error)

func (CommitteeMetricsWrapper) Identity

func (w CommitteeMetricsWrapper) Identity(blockID flow.Identifier, participantID flow.Identifier) (*flow.Identity, error)

func (CommitteeMetricsWrapper) LeaderForView

func (w CommitteeMetricsWrapper) LeaderForView(view uint64) (flow.Identifier, error)

func (CommitteeMetricsWrapper) Self

func (w CommitteeMetricsWrapper) Self() flow.Identifier

type LeaderSelection

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

LeaderSelection caches the pre-generated leader selections for a certain number of views starting from the epoch start view.

func ComputeLeaderSelectionFromSeed

func ComputeLeaderSelectionFromSeed(epochStartView uint64, seed []byte, count int, identities flow.IdentityList) (*LeaderSelection, error)

ComputeLeaderSelectionFromSeed pre-generates a certain number of leader selections, and returns a leader selection instance for querying the leader indexes for certain views. epochStartView - the start view of the epoch, the generated leader selections start from this view. seed - the random seed for leader selection count - the number of leader selections to be pre-generated and cached. identities - the identities that contain the stake info, which is used as weight for the chance of

the identity to be selected as leader.

func (LeaderSelection) LeaderIndexForView

func (l LeaderSelection) LeaderIndexForView(view uint64) (int, error)

LeaderIndexForView returns the leader index for given view. If the view is smaller than the epochStartView, an error will be returned.

type Static

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

Static represents a committee with a static participant set. It is used for bootstrapping purposes.

func NewStaticCommittee

func NewStaticCommittee(participants flow.IdentityList, myID flow.Identifier, dkgParticipants map[flow.Identifier]flow.DKGParticipant, dkgGroupKey crypto.PublicKey) (*Static, error)

NewStaticCommittee returns a new committee with a static participant set.

func (Static) DKG

func (s Static) DKG(_ flow.Identifier) (hotstuff.DKG, error)

func (Static) Identities

func (s Static) Identities(_ flow.Identifier, selector flow.IdentityFilter) (flow.IdentityList, error)

func (Static) Identity

func (s Static) Identity(_ flow.Identifier, participantID flow.Identifier) (*flow.Identity, error)

func (Static) LeaderForView

func (s Static) LeaderForView(_ uint64) (flow.Identifier, error)

func (Static) Self

func (s Static) Self() flow.Identifier