consensus

Documentation

Index

• type Compliance
• type MatchingCore
• type SealingCore
• type SealingObservation
• type SealingTracker

Types

type Compliance

type Compliance interface {
	component.Component

	// OnBlockProposal feeds a new block proposal into the processing pipeline.
	// Incoming proposals will be queued and eventually dispatched by worker.
	// This method is non-blocking.
	OnBlockProposal(proposal flow.Slashable[*messages.BlockProposal])

	// OnSyncedBlocks feeds a batch of blocks obtained from sync into the processing pipeline.
	// Implementors shouldn't assume that blocks are arranged in any particular order.
	// Incoming proposals will be queued and eventually dispatched by worker.
	// This method is non-blocking.
	OnSyncedBlocks(blocks flow.Slashable[[]*messages.BlockProposal])
}

Compliance defines the interface to the consensus logic that precedes hotstuff logic. It's responsible for processing incoming block proposals broadcast by other consensus nodes as well as blocks obtained via the sync protocol. Compliance logic performs validation of incoming blocks depending on internal implementation. Main consensus logic performs full validation by checking headers and payloads. Follower consensus logic checks header validity and by observing a valid QC can make a statement about payload validity of parent block. Compliance logic guarantees that only valid blocks are added to chain state, passed to hotstuff and other components. Implementation need to be non-blocking and concurrency safe.

type MatchingCore

type MatchingCore interface {
	// ProcessReceipt processes a new execution receipt in blocking way.
	// Returns:
	// * exception in case of unexpected error
	// * nil - successfully processed receipt
	ProcessReceipt(receipt *flow.ExecutionReceipt) error
	// OnBlockFinalization notifies the engine that a (potentially new) block was finalized.
	// Implementations are non-blocking.
	// Returns:
	// * exception in case of unexpected error
	// * nil - successfully processed finalized block
	OnBlockFinalization() error
}

MatchingCore collects inbound receipts from Execution Node for potential inclusion in future blocks. Implementations of MatchingCore are generally NOT concurrency safe.

type SealingCore

type SealingCore interface {
	// ProcessApproval processes approval in blocking way. Concurrency safe.
	// Returns:
	// * exception in case of unexpected error
	// * nil - successfully processed result approval
	ProcessApproval(approval *flow.ResultApproval) error
	// ProcessIncorporatedResult processes incorporated result in blocking way. Concurrency safe.
	// Returns:
	// * exception in case of unexpected error
	// * nil - successfully processed incorporated result
	ProcessIncorporatedResult(result *flow.IncorporatedResult) error
	// ProcessFinalizedBlock processes finalization events in blocking way. Concurrency safe.
	// Returns:
	// * exception in case of unexpected error
	// * nil - successfully processed finalized block
	ProcessFinalizedBlock(finalizedBlockID flow.Identifier) error
}

SealingCore processes incoming execution results and result approvals. Accepts `flow.IncorporatedResult` to start processing approvals for particular result. Whenever enough approvals are collected produces a candidate seal and adds it to the mempool. Implementations of SealingCore are _concurrency safe_.

type SealingObservation

type SealingObservation interface {

	// QualifiesForEmergencySealing captures whether sealing.Core has
	// determined that the incorporated result qualifies for emergency sealing.
	QualifiesForEmergencySealing(ir *flow.IncorporatedResult, emergencySealable bool)

	// ApprovalsMissing captures whether sealing.Core has determined that
	// some approvals are still missing for the incorporated result. Calling this
	// method with empty `chunksWithMissingApprovals` indicates that all chunks
	// have sufficient approvals.
	ApprovalsMissing(ir *flow.IncorporatedResult, chunksWithMissingApprovals map[uint64]flow.IdentifierList)

	// ApprovalsRequested captures the number of approvals that the business
	// logic has re-requested for the incorporated result.
	ApprovalsRequested(ir *flow.IncorporatedResult, requestCount uint)

	// Complete is supposed to be called when a single execution of the sealing logic
	// has been completed. It compiles the information about the incorporated results.
	Complete()
}

SealingObservation captures information about the progress of a _single_ go routine. Consequently, it is _not concurrency safe_, as SealingObservation is intended to be a thread-local structure. SealingObservation is supposed to track the status of various (unsealed) incorporated results, which sealing.Core processes (driven by that single goroutine).

type SealingTracker

type SealingTracker interface {

	// NewSealingObservation constructs a SealingObservation, which capture information
	// about the progress of a _single_ go routine. Consequently, SealingObservations
	// don't need to be concurrency safe, as they are supposed to be thread-local structure.
	NewSealingObservation(finalizedBlock *flow.Header, seal *flow.Seal, sealedBlock *flow.Header) SealingObservation
}

SealingTracker is an auxiliary component for tracking progress of the sealing logic (specifically sealing.Core). It has access to the storage, to collect data that is not be available directly from sealing.Core. The SealingTracker is immutable and therefore intrinsically thread safe.

The SealingTracker essentially acts as a factory for individual SealingObservations, which capture information about the progress of a _single_ go routine. Consequently, SealingObservations don't need to be concurrency safe, as they are supposed to be thread-local structure.