consensus

Documentation

Index

• type ExecForkActor
  • func LogForkAndCrash(log zerolog.Logger) ExecForkActor
• type ExecForkSuppressor
  • func NewExecStateForkSuppressor(seals mempool.IncorporatedResultSeals, onExecFork ExecForkActor, db *badger.DB, ...) (*ExecForkSuppressor, error)
  • func (s *ExecForkSuppressor) Add(newSeal *flow.IncorporatedResultSeal) (bool, error)
  • func (s *ExecForkSuppressor) All() []*flow.IncorporatedResultSeal
  • func (s *ExecForkSuppressor) ByID(identifier flow.Identifier) (*flow.IncorporatedResultSeal, bool)
  • func (s *ExecForkSuppressor) Clear()
  • func (s *ExecForkSuppressor) Limit() uint
  • func (s *ExecForkSuppressor) PruneUpToHeight(height uint64) error
  • func (s *ExecForkSuppressor) Remove(id flow.Identifier) bool
  • func (s *ExecForkSuppressor) Size() uint
• type ExecutionTree
  • func NewExecutionTree() *ExecutionTree
  • func (et *ExecutionTree) AddReceipt(receipt *flow.ExecutionReceipt, block *flow.Header) (bool, error)
  • func (et *ExecutionTree) AddResult(result *flow.ExecutionResult, block *flow.Header) error
  • func (et *ExecutionTree) HasReceipt(receipt *flow.ExecutionReceipt) bool
  • func (et *ExecutionTree) LowestHeight() uint64
  • func (et *ExecutionTree) PruneUpToHeight(limit uint64) error
  • func (et *ExecutionTree) ReachableReceipts(resultID flow.Identifier, blockFilter mempool.BlockFilter, ...) ([]*flow.ExecutionReceipt, error)
  • func (et *ExecutionTree) Size() uint
• type IncorporatedResultSeals
  • func NewIncorporatedResultSeals(mempool mempool.IncorporatedResultSeals, receiptsDB storage.ExecutionReceipts) *IncorporatedResultSeals
  • func (ir *IncorporatedResultSeals) Add(seal *flow.IncorporatedResultSeal) (bool, error)
  • func (ir *IncorporatedResultSeals) All() []*flow.IncorporatedResultSeal
  • func (ir *IncorporatedResultSeals) ByID(id flow.Identifier) (*flow.IncorporatedResultSeal, bool)
  • func (ir *IncorporatedResultSeals) Clear()
  • func (ir *IncorporatedResultSeals) Limit() uint
  • func (ir *IncorporatedResultSeals) PruneUpToHeight(height uint64) error
  • func (ir *IncorporatedResultSeals) Remove(id flow.Identifier) bool
  • func (ir *IncorporatedResultSeals) Size() uint
• type ReceiptsOfSameResult
  • func NewReceiptsOfSameResult(result *flow.ExecutionResult, block *flow.Header) (*ReceiptsOfSameResult, error)
  • func (rsr *ReceiptsOfSameResult) AddReceipt(receipt *flow.ExecutionReceipt) (uint, error)
  • func (rsr *ReceiptsOfSameResult) AddReceipts(receipts ...*flow.ExecutionReceipt) (uint, error)
  • func (rsr *ReceiptsOfSameResult) Has(receiptID flow.Identifier) bool
  • func (rsr *ReceiptsOfSameResult) Level() uint64
  • func (rsr *ReceiptsOfSameResult) Parent() (flow.Identifier, uint64)
  • func (rsr *ReceiptsOfSameResult) Size() uint
  • func (rsr *ReceiptsOfSameResult) VertexID() flow.Identifier

Types

type ExecForkActor

type ExecForkActor func([]*flow.IncorporatedResultSeal)

func LogForkAndCrash

func LogForkAndCrash(log zerolog.Logger) ExecForkActor

type ExecForkSuppressor

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

ExecForkSuppressor is a wrapper around a conventional mempool.IncorporatedResultSeals mempool. It implements the following mitigation strategy for execution forks:

• In case two conflicting results are considered sealable for the same block, sealing should halt. Specifically, two results are considered conflicting, if they differ in their start or end state.
• Even after a restart, the sealing should not resume.
• We rely on human intervention to resolve the conflict.

The ExecForkSuppressor implements this mitigation strategy as follows:

• For each candidate seal inserted into the mempool, indexes seal by respective blockID, storing all seals in the internal map `sealsForBlock`.
• Whenever client perform any query, we check if there are conflicting seals.
• We pick first seal available for a block and check whether the seal has the same state transition as other seals included for same block.
• If conflicting state transitions for the same block are detected, ExecForkSuppressor sets an internal flag and thereafter reports the mempool as empty, which will lead to the respective consensus node not including any more seals.
• Evidence for an execution fork stored in a database (persisted across restarts).

Implementation is concurrency safe.

func NewExecStateForkSuppressor

func NewExecStateForkSuppressor(seals mempool.IncorporatedResultSeals, onExecFork ExecForkActor, db *badger.DB, log zerolog.Logger) (*ExecForkSuppressor, error)

func (*ExecForkSuppressor) Add

func (s *ExecForkSuppressor) Add(newSeal *flow.IncorporatedResultSeal) (bool, error)

Add adds the given seal to the mempool. Return value indicates whether seal was added to the mempool. Internally indexes every added seal by blockID. Expects that underlying mempool never eject items. Error returns:

• engine.InvalidInputError (sentinel error) In case a seal fails one of the required consistency checks;

func (*ExecForkSuppressor) All

func (s *ExecForkSuppressor) All() []*flow.IncorporatedResultSeal

All returns all the IncorporatedResultSeals in the mempool. Note: This call might crash if the block of the seal has multiple seals in mempool for conflicting incorporated results.

func (*ExecForkSuppressor) ByID

func (s *ExecForkSuppressor) ByID(identifier flow.Identifier) (*flow.IncorporatedResultSeal, bool)

ByID returns an IncorporatedResultSeal by its ID. The IncorporatedResultSeal's ID is the same as IncorporatedResult's ID, so this call essentially is to find the seal for the incorporated result in the mempool. Note: This call might crash if the block of the seal has multiple seals in mempool for conflicting incorporated results. Usually the builder will call this method to find a seal for an incorporated result, so the builder might crash if multiple conflicting seals exist.

func (*ExecForkSuppressor) Clear

func (s *ExecForkSuppressor) Clear()

Clear removes all entities from the pool. The wrapper clears the internal state as well as its local (additional) state.

func (*ExecForkSuppressor) Limit

func (s *ExecForkSuppressor) Limit() uint

Limit returns the size limit of the mempool

func (*ExecForkSuppressor) PruneUpToHeight

func (s *ExecForkSuppressor) PruneUpToHeight(height uint64) error

PruneUpToHeight remove all seals for blocks whose height is strictly smaller that height. Note: seals for blocks at height are retained.

func (*ExecForkSuppressor) Remove

func (s *ExecForkSuppressor) Remove(id flow.Identifier) bool

Remove removes the IncorporatedResultSeal with id from the mempool

func (*ExecForkSuppressor) Size

func (s *ExecForkSuppressor) Size() uint

Size returns the number of items in the mempool

type ExecutionTree

type ExecutionTree struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

ExecutionTree is a mempool holding receipts, which is aware of the tree structure formed by the results. The mempool supports pruning by height: only results descending from the latest sealed and finalized result are relevant. Hence, we can prune all results for blocks _below_ the latest block with a finalized seal. Results of sufficient height for forks that conflict with the finalized fork are retained. However, such orphaned forks do not grow anymore and their results will be progressively flushed out with increasing sealed-finalized height.

Safe for concurrent access. Internally, the mempool utilizes the LevelledForrest. For an in-depth discussion of the core algorithm, see ./Fork-Aware_Mempools.md

func NewExecutionTree

func NewExecutionTree() *ExecutionTree

NewExecutionTree instantiates a ExecutionTree

func (*ExecutionTree) AddReceipt

func (et *ExecutionTree) AddReceipt(receipt *flow.ExecutionReceipt, block *flow.Header) (bool, error)

AddReceipt adds the given execution receipt to the memory pool. Requires height of the block the receipt is for. We enforce data consistency on an API level by using the block header as input.

func (*ExecutionTree) AddResult

func (et *ExecutionTree) AddResult(result *flow.ExecutionResult, block *flow.Header) error

AddResult adds an Execution Result to the Execution Tree (without any receipts), in case the result is not already stored in the tree. This is useful for crash recovery: After recovering from a crash, the mempools are wiped and the sealed results will not be stored in the Execution Tree anymore. Adding the result to the tree allows to create a vertex in the tree without attaching any Execution Receipts to it.

func (*ExecutionTree) HasReceipt

func (et *ExecutionTree) HasReceipt(receipt *flow.ExecutionReceipt) bool

func (*ExecutionTree) LowestHeight

func (et *ExecutionTree) LowestHeight() uint64

LowestHeight returns the lowest height, where results are still stored in the mempool.

func (*ExecutionTree) PruneUpToHeight

func (et *ExecutionTree) PruneUpToHeight(limit uint64) error

PruneUpToHeight prunes all results for all blocks with height up to but NOT INCLUDING `newLowestHeight`. Errors if newLowestHeight is lower than the previous value (as we cannot recover previously pruned results).

func (*ExecutionTree) ReachableReceipts

func (et *ExecutionTree) ReachableReceipts(resultID flow.Identifier, blockFilter mempool.BlockFilter, receiptFilter mempool.ReceiptFilter) ([]*flow.ExecutionReceipt, error)

ReachableReceipts returns a slice of ExecutionReceipt, whose result is computationally reachable from resultID. Context:

• Conceptually, the Execution results form a tree, which we refer to as Execution Tree. A fork in the execution can be due to a fork in the main chain. Furthermore, the execution forks if ENs disagree about the result for the same block.
• As the ID of an execution result contains the BlockID, which the result for, all Execution Results with the same ID necessarily are for the same block. All Execution Receipts committing to the same result from an equivalence class and can be represented as one vertex in the Execution Tree.
• An execution result r1 points (field ExecutionResult.ParentResultID) to its parent result r0 , whose end state was used as the starting state to compute r1. Formally, we have an edge r0 -> r1 in the Execution Tree, if a result r1 is stored in the mempool, whose ParentResultID points to r0.

ReachableReceipts traverses the Execution Tree from the provided resultID. Execution Receipts are traversed in a parent-first manner, meaning that a receipt committing to the parent result is traversed first _before_ the receipt committing to the derived result. The algorithm only traverses to results, for which there exists a sequence of interim result in the mempool without any gaps.

Error returns: * UnknownExecutionResultError (sentinel) if resultID is unknown * all other error are unexpected and potential indicators of corrupted internal state

func (*ExecutionTree) Size

func (et *ExecutionTree) Size() uint

Size returns the number of receipts stored in the mempool

type IncorporatedResultSeals

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

IncorporatedResultSeals implements the incorporated result seals memory pool of the consensus nodes. ATTENTION: this is a temporary wrapper for `mempool.IncorporatedResultSeals` to enforce that there are at least 2 receipts from _different_ ENs committing to the same incorporated result. This wrapper should only be used with `Core`.

func NewIncorporatedResultSeals

func NewIncorporatedResultSeals(mempool mempool.IncorporatedResultSeals, receiptsDB storage.ExecutionReceipts) *IncorporatedResultSeals

NewIncorporatedResultSeals creates a mempool for the incorporated result seals

func (*IncorporatedResultSeals) Add

func (ir *IncorporatedResultSeals) Add(seal *flow.IncorporatedResultSeal) (bool, error)

Add adds an IncorporatedResultSeal to the mempool

func (*IncorporatedResultSeals) All

func (ir *IncorporatedResultSeals) All() []*flow.IncorporatedResultSeal

All returns all the items in the mempool

func (*IncorporatedResultSeals) ByID

func (ir *IncorporatedResultSeals) ByID(id flow.Identifier) (*flow.IncorporatedResultSeal, bool)

ByID gets an IncorporatedResultSeal by IncorporatedResult ID

func (*IncorporatedResultSeals) Clear

func (ir *IncorporatedResultSeals) Clear()

Clear removes all entities from the pool.

func (*IncorporatedResultSeals) Limit

func (ir *IncorporatedResultSeals) Limit() uint

Limit returns the size limit of the mempool

func (*IncorporatedResultSeals) PruneUpToHeight

func (ir *IncorporatedResultSeals) PruneUpToHeight(height uint64) error

PruneUpToHeight remove all seals for blocks whose height is strictly smaller that height. Note: seals for blocks at height are retained.

func (*IncorporatedResultSeals) Remove

func (ir *IncorporatedResultSeals) Remove(id flow.Identifier) bool

Remove removes an IncorporatedResultSeal from the mempool

func (*IncorporatedResultSeals) Size

func (ir *IncorporatedResultSeals) Size() uint

Size returns the number of items in the mempool

type ReceiptsOfSameResult

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

ReceiptsOfSameResult represents a set of ExecutionReceipt all committing to the same ExecutionResult. As an ExecutionResult contains the Block ID, all results with the same ID must be for the same block. For optimized storage, we only store the result once. Mathematically, a ReceiptsOfSameResult struct represents an Equivalence Class of Execution Receipts. Implements LevelledForest's Vertex interface.

func NewReceiptsOfSameResult

func NewReceiptsOfSameResult(result *flow.ExecutionResult, block *flow.Header) (*ReceiptsOfSameResult, error)

NewReceiptsOfSameResult instantiates an empty Equivalence Class (without any receipts)

func (*ReceiptsOfSameResult) AddReceipt

func (rsr *ReceiptsOfSameResult) AddReceipt(receipt *flow.ExecutionReceipt) (uint, error)

AddReceipt adds the receipt to the ReceiptsOfSameResult (if not already stored). Returns:

• uint: number of receipts added (consistent API with AddReceipts()), Possible values: 0 or 1
• error in case of unforeseen problems

func (*ReceiptsOfSameResult) AddReceipts

func (rsr *ReceiptsOfSameResult) AddReceipts(receipts ...*flow.ExecutionReceipt) (uint, error)

AddReceipts adds the receipts to the ReceiptsOfSameResult (the ones not already stored). Returns:

• uint: number of receipts added
• error in case of unforeseen problems

func (*ReceiptsOfSameResult) Has

func (rsr *ReceiptsOfSameResult) Has(receiptID flow.Identifier) bool

func (*ReceiptsOfSameResult) Level

func (rsr *ReceiptsOfSameResult) Level() uint64

func (*ReceiptsOfSameResult) Parent

func (rsr *ReceiptsOfSameResult) Parent() (flow.Identifier, uint64)

func (*ReceiptsOfSameResult) Size

func (rsr *ReceiptsOfSameResult) Size() uint

Size returns the number of receipts in the equivalence class (i.e. the number of receipts known for that particular result)

func (*ReceiptsOfSameResult) VertexID

func (rsr *ReceiptsOfSameResult) VertexID() flow.Identifier