timeoutcollector

Documentation

Index

• Variables
• type TimeoutCollector
  • func NewTimeoutCollector(log zerolog.Logger, view uint64, notifier hotstuff.TimeoutAggregationConsumer, ...) *TimeoutCollector
  • func (c *TimeoutCollector) AddTimeout(timeout *model.TimeoutObject) error
  • func (c *TimeoutCollector) View() uint64
• type TimeoutCollectorFactory
  • func NewTimeoutCollectorFactory(log zerolog.Logger, notifier hotstuff.TimeoutAggregationConsumer, ...) *TimeoutCollectorFactory
  • func (f *TimeoutCollectorFactory) Create(view uint64) (hotstuff.TimeoutCollector, error)
• type TimeoutObjectsCache
  • func NewTimeoutObjectsCache(view uint64) *TimeoutObjectsCache
  • func (vc *TimeoutObjectsCache) AddTimeoutObject(timeout *model.TimeoutObject) error
  • func (vc *TimeoutObjectsCache) All() []*model.TimeoutObject
  • func (vc *TimeoutObjectsCache) GetTimeoutObject(signerID flow.Identifier) (*model.TimeoutObject, bool)
  • func (vc *TimeoutObjectsCache) Size() int
  • func (vc *TimeoutObjectsCache) View() uint64
• type TimeoutProcessor
  • func NewTimeoutProcessor(log zerolog.Logger, committee hotstuff.Replicas, validator hotstuff.Validator, ...) (*TimeoutProcessor, error)
  • func (p *TimeoutProcessor) Process(timeout *model.TimeoutObject) error
• type TimeoutProcessorFactory
  • func NewTimeoutProcessorFactory(log zerolog.Logger, notifier hotstuff.TimeoutCollectorConsumer, ...) *TimeoutProcessorFactory
  • func (f *TimeoutProcessorFactory) Create(view uint64) (hotstuff.TimeoutProcessor, error)
• type TimeoutSignatureAggregator
  • func NewTimeoutSignatureAggregator(view uint64, ids flow.IdentityList, dsTag string) (*TimeoutSignatureAggregator, error)
  • func (a *TimeoutSignatureAggregator) Aggregate() ([]hotstuff.TimeoutSignerInfo, crypto.Signature, error)
  • func (a *TimeoutSignatureAggregator) TotalWeight() uint64
  • func (a *TimeoutSignatureAggregator) VerifyAndAdd(signerID flow.Identifier, sig crypto.Signature, newestQCView uint64) (totalWeight uint64, exception error)
  • func (a *TimeoutSignatureAggregator) View() uint64

Variables

var (
	// ErrRepeatedTimeout is emitted, when we receive an identical timeout object for the same block
	// from the same voter multiple times. This error does _not_ indicate
	// equivocation.
	ErrRepeatedTimeout            = errors.New("duplicated timeout")
	ErrTimeoutForIncompatibleView = errors.New("timeout for incompatible view")
)

Types

type TimeoutCollector

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

TimeoutCollector implements logic for collecting timeout objects. Performs deduplication, caching and processing of timeouts, delegating those tasks to underlying modules. Emits notifications about verified QCs and TCs, if their view is newer than any QC or TC previously known to the TimeoutCollector. This module is safe to use in concurrent environment.

func NewTimeoutCollector

func NewTimeoutCollector(log zerolog.Logger,
	view uint64,
	notifier hotstuff.TimeoutAggregationConsumer,
	processor hotstuff.TimeoutProcessor,
) *TimeoutCollector

NewTimeoutCollector creates new instance of TimeoutCollector

func (*TimeoutCollector) AddTimeout

func (c *TimeoutCollector) AddTimeout(timeout *model.TimeoutObject) error

AddTimeout adds a Timeout Object [TO] to the collector. When TOs from strictly more than 1/3 of consensus participants (measured by weight) were collected, the callback for partial TC will be triggered. After collecting TOs from a supermajority, a TC will be created and passed to the EventLoop. Expected error returns during normal operations:

• timeoutcollector.ErrTimeoutForIncompatibleView - submitted timeout for incompatible view

All other exceptions are symptoms of potential state corruption.

func (*TimeoutCollector) View

func (c *TimeoutCollector) View() uint64

View returns view which is associated with this timeout collector

type TimeoutCollectorFactory

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

TimeoutCollectorFactory implements hotstuff.TimeoutCollectorFactory, it is responsible for creating timeout collector for given view.

func NewTimeoutCollectorFactory

func NewTimeoutCollectorFactory(log zerolog.Logger,
	notifier hotstuff.TimeoutAggregationConsumer,
	createProcessor hotstuff.TimeoutProcessorFactory,
) *TimeoutCollectorFactory

NewTimeoutCollectorFactory creates new instance of TimeoutCollectorFactory. No error returns are expected during normal operations.

func (*TimeoutCollectorFactory) Create

func (f *TimeoutCollectorFactory) Create(view uint64) (hotstuff.TimeoutCollector, error)

Create is a factory method to generate a TimeoutCollector for a given view Expected error returns during normal operations:

• model.ErrViewForUnknownEpoch if view is not yet pruned but no epoch containing the given view is known

All other errors should be treated as exceptions.

type TimeoutObjectsCache

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

TimeoutObjectsCache maintains a _concurrency safe_ cache of timeouts for one particular view. The cache memorizes the order in which the timeouts were received. Timeouts are de-duplicated based on the following rules:

• For each voter (i.e. SignerID), we store the _first_ timeout t0.
• For any subsequent timeout t, we check whether t.ID() == t0.ID(). If this is the case, we consider the timeout a duplicate and drop it. If t and t0 have different checksums, the voter is equivocating, and we return a model.DoubleTimeoutError.

func NewTimeoutObjectsCache

func NewTimeoutObjectsCache(view uint64) *TimeoutObjectsCache

NewTimeoutObjectsCache instantiates a TimeoutObjectsCache for the given view

func (*TimeoutObjectsCache) AddTimeoutObject

func (vc *TimeoutObjectsCache) AddTimeoutObject(timeout *model.TimeoutObject) error

AddTimeoutObject stores a timeout in the cache. The following errors are expected during normal operations:

• nil: if the timeout was successfully added
• model.DoubleTimeoutError is returned if the replica is equivocating
• RepeatedTimeoutErr is returned when adding an _identical_ timeout for the same view from the same voter multiple times.
• TimeoutForIncompatibleViewError is returned if the timeout is for a different view.

When AddTimeoutObject returns an error, the timeout is _not_ stored.

func (*TimeoutObjectsCache) All

func (vc *TimeoutObjectsCache) All() []*model.TimeoutObject

All returns all currently cached timeout objects. Concurrency safe.

func (*TimeoutObjectsCache) GetTimeoutObject

func (vc *TimeoutObjectsCache) GetTimeoutObject(signerID flow.Identifier) (*model.TimeoutObject, bool)

GetTimeoutObject returns the stored timeout for the given `signerID`. Returns:

• (timeout, true) if a timeout object from signerID is known
• (nil, false) no timeout object from signerID is known

func (*TimeoutObjectsCache) Size

func (vc *TimeoutObjectsCache) Size() int

Size returns the number of cached timeout objects

func (*TimeoutObjectsCache) View

func (vc *TimeoutObjectsCache) View() uint64

type TimeoutProcessor

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

TimeoutProcessor implements the hotstuff.TimeoutProcessor interface. It processes timeout objects broadcast by other replicas of the consensus committee. TimeoutProcessor collects TOs for one view, eventually when enough timeout objects are contributed TimeoutProcessor will create a timeout certificate which can be used to advance round. Concurrency safe.

func NewTimeoutProcessor

func NewTimeoutProcessor(log zerolog.Logger,
	committee hotstuff.Replicas,
	validator hotstuff.Validator,
	sigAggregator hotstuff.TimeoutSignatureAggregator,
	notifier hotstuff.TimeoutCollectorConsumer,
) (*TimeoutProcessor, error)

NewTimeoutProcessor creates new instance of TimeoutProcessor Returns the following expected errors for invalid inputs:

• model.ErrViewForUnknownEpoch if no epoch containing the given view is known

All other errors should be treated as exceptions.

func (*TimeoutProcessor) Process

func (p *TimeoutProcessor) Process(timeout *model.TimeoutObject) error

Process performs processing of timeout object in concurrent safe way. This function is implemented to be called by multiple goroutines at the same time. Design of this function is event driven, as soon as we collect enough weight to create a TC or a partial TC we will immediately do so and submit it via callback for further processing. Expected error returns during normal operations:

• ErrTimeoutForIncompatibleView - submitted timeout for incompatible view
• model.InvalidTimeoutError - submitted invalid timeout(invalid structure or invalid signature)
• model.DuplicatedSignerError if a timeout from the same signer was previously already added It does _not necessarily_ imply that the timeout is invalid or the sender is equivocating.

All other errors should be treated as exceptions.

type TimeoutProcessorFactory

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

TimeoutProcessorFactory implements hotstuff.TimeoutProcessorFactory, it is responsible for creating timeout processor for given view.

func NewTimeoutProcessorFactory

func NewTimeoutProcessorFactory(
	log zerolog.Logger,
	notifier hotstuff.TimeoutCollectorConsumer,
	committee hotstuff.Replicas,
	validator hotstuff.Validator,
	domainSeparationTag string,
) *TimeoutProcessorFactory

NewTimeoutProcessorFactory creates new instance of TimeoutProcessorFactory. No error returns are expected during normal operations.

func (*TimeoutProcessorFactory) Create

func (f *TimeoutProcessorFactory) Create(view uint64) (hotstuff.TimeoutProcessor, error)

Create is a factory method to generate a TimeoutProcessor for a given view Expected error returns during normal operations:

• model.ErrViewForUnknownEpoch no epoch containing the given view is known

All other errors should be treated as exceptions.

type TimeoutSignatureAggregator

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

TimeoutSignatureAggregator implements consensus/hotstuff.TimeoutSignatureAggregator. It performs timeout specific BLS aggregation over multiple distinct messages. We perform timeout signature aggregation for some concrete view, utilizing the protocol specification that timeouts sign the message: hash(view, newestQCView), where newestQCView can have different values for different replicas. View and the identities of all authorized replicas are specified when the TimeoutSignatureAggregator is instantiated. Each signer is allowed to sign at most once. Aggregation uses BLS scheme. Mitigation against rogue attacks is done using Proof Of Possession (PoP). Implementation is only safe under the assumption that all proofs of possession (PoP) of the public keys are valid. This module does not perform the PoPs validity checks, it assumes verification was done outside the module. Implementation is thread-safe.

func NewTimeoutSignatureAggregator

func NewTimeoutSignatureAggregator(
	view uint64,
	ids flow.IdentityList,
	dsTag string,
) (*TimeoutSignatureAggregator, error)

NewTimeoutSignatureAggregator returns a multi message signature aggregator initialized with a predefined view for which we aggregate signatures, list of flow identities, their respective public keys and a domain separation tag. The identities represent the list of all authorized signers. The constructor does not verify PoPs of input public keys, it assumes verification was done outside this module. The constructor errors if: - the list of identities is empty - if one of the keys is not a valid public key.

A multi message sig aggregator is used for aggregating timeouts for a single view only. A new instance should be used for each signature aggregation task in the protocol.

func (*TimeoutSignatureAggregator) Aggregate

func (a *TimeoutSignatureAggregator) Aggregate() ([]hotstuff.TimeoutSignerInfo, crypto.Signature, error)

Aggregate aggregates the signatures and returns the aggregated signature. The resulting aggregated signature is guaranteed to be valid, as all individual signatures are pre-validated before their addition. Expected errors during normal operations:

• model.InsufficientSignaturesError if no signatures have been added yet

This function is thread-safe

func (*TimeoutSignatureAggregator) TotalWeight

func (a *TimeoutSignatureAggregator) TotalWeight() uint64

TotalWeight returns the total weight presented by the collected signatures. The function is thread-safe

func (*TimeoutSignatureAggregator) VerifyAndAdd

func (a *TimeoutSignatureAggregator) VerifyAndAdd(signerID flow.Identifier, sig crypto.Signature, newestQCView uint64) (totalWeight uint64, exception error)

VerifyAndAdd verifies the signature under the stored public keys and adds signature with corresponding newest QC view to the internal set. Internal set and collected weight is modified iff the signer ID is not a duplicate and signature _is_ valid. The total weight of all collected signatures (excluding duplicates) is returned regardless of any returned error. Expected errors during normal operations:

• model.InvalidSignerError if signerID is invalid (not a consensus participant)
• model.DuplicatedSignerError if the signer has been already added
• model.ErrInvalidSignature if signerID is valid but signature is cryptographically invalid

The function is thread-safe.

func (*TimeoutSignatureAggregator) View

func (a *TimeoutSignatureAggregator) View() uint64

View returns view for which aggregation happens The function is thread-safe