forks

Documentation

Index

• type BlockContainer
  • func ToBlockContainer2(block *model.Block) *BlockContainer
  • func (b *BlockContainer) Block() *model.Block
  • func (b *BlockContainer) Level() uint64
  • func (b *BlockContainer) Parent() (flow.Identifier, uint64)
  • func (b *BlockContainer) VertexID() flow.Identifier
• type Forks
  • func New(trustedRoot *model.CertifiedBlock, finalizationCallback module.Finalizer, ...) (*Forks, error)
  • func (f *Forks) AddCertifiedBlock(certifiedBlock *model.CertifiedBlock) error
  • func (f *Forks) AddValidatedBlock(proposal *model.Block) error
  • func (f *Forks) EnsureBlockIsValidExtension(block *model.Block) error
  • func (f *Forks) FinalityProof() (*hotstuff.FinalityProof, bool)
  • func (f *Forks) FinalizedBlock() *model.Block
  • func (f *Forks) FinalizedView() uint64
  • func (f *Forks) GetBlock(blockID flow.Identifier) (*model.Block, bool)
  • func (f *Forks) GetBlocksForView(view uint64) []*model.Block
  • func (f *Forks) IsKnownBlock(blockID flow.Identifier) bool
  • func (f *Forks) IsProcessingNeeded(block *model.Block) bool

Types

type BlockContainer

type BlockContainer model.Block

BlockContainer wraps a block proposal to implement forest.Vertex so the proposal can be stored in forest.LevelledForest

func ToBlockContainer2

func ToBlockContainer2(block *model.Block) *BlockContainer

func (*BlockContainer) Block

func (b *BlockContainer) Block() *model.Block

func (*BlockContainer) Level

func (b *BlockContainer) Level() uint64

func (*BlockContainer) Parent

func (b *BlockContainer) Parent() (flow.Identifier, uint64)

func (*BlockContainer) VertexID

func (b *BlockContainer) VertexID() flow.Identifier

Functions implementing forest.Vertex

type Forks

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

Forks enforces structural validity of the consensus state and implements finalization rules as defined in Jolteon consensus https://arxiv.org/abs/2106.10362 The same approach has later been adopted by the Diem team resulting in DiemBFT v4: https://developers.diem.com/papers/diem-consensus-state-machine-replication-in-the-diem-blockchain/2021-08-17.pdf Forks is NOT safe for concurrent use by multiple goroutines.

func New

func New(trustedRoot *model.CertifiedBlock, finalizationCallback module.Finalizer, notifier hotstuff.FollowerConsumer) (*Forks, error)

func (*Forks) AddCertifiedBlock

func (f *Forks) AddCertifiedBlock(certifiedBlock *model.CertifiedBlock) error

AddCertifiedBlock appends the given certified block to the tree of pending blocks and updates the latest finalized block (if finalization progressed). Unless the parent is below the pruning threshold (latest finalized view), we require that the parent is already stored in Forks. Calling this method with previously processed blocks leaves the consensus state invariant (though, it will potentially cause some duplicate processing).

Possible error returns:

• model.MissingBlockError if the parent does not exist in the forest (but is above the pruned view). From the perspective of Forks, this error is benign (no-op).
• model.InvalidBlockError if the block is invalid (see `Forks.EnsureBlockIsValidExtension` for details). From the perspective of Forks, this error is benign (no-op). However, we assume all blocks are fully verified, i.e. they should satisfy all consistency requirements. Hence, this error is likely an indicator of a bug in the compliance layer.
• model.ByzantineThresholdExceededError if conflicting QCs or conflicting finalized blocks have been detected (violating a foundational consensus guarantees). This indicates that there are 1/3+ Byzantine nodes (weighted by stake) in the network, breaking the safety guarantees of HotStuff (or there is a critical bug / data corruption). Forks cannot recover from this exception.
• All other errors are potential symptoms of bugs or state corruption.

func (*Forks) AddValidatedBlock

func (f *Forks) AddValidatedBlock(proposal *model.Block) error

AddValidatedBlock appends the validated block to the tree of pending blocks and updates the latest finalized block (if applicable). Unless the parent is below the pruning threshold (latest finalized view), we require that the parent is already stored in Forks. Calling this method with previously processed blocks leaves the consensus state invariant (though, it will potentially cause some duplicate processing). Notes:

• Method `AddCertifiedBlock(..)` should be used preferably, if a QC certifying `block` is already known. This is generally the case for the consensus follower. Method `AddValidatedBlock` is intended for active consensus participants, which fully validate blocks (incl. payload), i.e. QCs are processed as part of validated proposals.

Possible error returns:

• model.MissingBlockError if the parent does not exist in the forest (but is above the pruned view). From the perspective of Forks, this error is benign (no-op).
• model.InvalidBlockError if the block is invalid (see `Forks.EnsureBlockIsValidExtension` for details). From the perspective of Forks, this error is benign (no-op). However, we assume all blocks are fully verified, i.e. they should satisfy all consistency requirements. Hence, this error is likely an indicator of a bug in the compliance layer.
• model.ByzantineThresholdExceededError if conflicting QCs or conflicting finalized blocks have been detected (violating a foundational consensus guarantees). This indicates that there are 1/3+ Byzantine nodes (weighted by stake) in the network, breaking the safety guarantees of HotStuff (or there is a critical bug / data corruption). Forks cannot recover from this exception.
• All other errors are potential symptoms of bugs or state corruption.

func (*Forks) EnsureBlockIsValidExtension

func (f *Forks) EnsureBlockIsValidExtension(block *model.Block) error

EnsureBlockIsValidExtension checks that the given block is a valid extension to the tree of blocks already stored (no state modifications). Specifically, the following conditions are enforced, which are critical to the correctness of Forks:

1. If a block with the same ID is already stored, their views must be identical.
2. The block's view must be strictly larger than the view of its parent.
3. The parent must already be stored (or below the pruning height).

Exclusions to these rules (by design): Let W denote the view of block's parent (i.e. W := block.QC.View) and F the latest finalized view.

  (i) If block.View < F, adding the block would be a no-op. Such blocks are considered
      compatible (principle of vacuous truth), i.e. we skip checking 1, 2, 3.
 (ii) If block.View == F, we do not inspect the QC / parent at all (skip 2 and 3).
      This exception is important for compatability with genesis or spork-root blocks,
      which do not contain a QC.
(iii) If block.View > F, but block.QC.View < F the parent has already been pruned. In
      this case, we omit rule 3. (principle of vacuous truth applied to the parent)

We assume that all blocks are fully verified. A valid block must satisfy all consistency requirements; otherwise we have a bug in the compliance layer.

Error returns:

• model.MissingBlockError if the parent of the input proposal does not exist in the forest (but is above the pruned view). Represents violation of condition 3.
• model.InvalidBlockError if the block violates condition 1. or 2.
• generic error in case of unexpected bug or internal state corruption

func (*Forks) FinalityProof

func (f *Forks) FinalityProof() (*hotstuff.FinalityProof, bool)

FinalityProof returns the latest finalized block and a certified child from the subsequent view, which proves finality. CAUTION: method returns (nil, false), when Forks has not yet finalized any blocks beyond the finalized root block it was initialized with.

func (*Forks) FinalizedBlock

func (f *Forks) FinalizedBlock() *model.Block

FinalizedBlock returns the finalized block with the largest view number

func (*Forks) FinalizedView

func (f *Forks) FinalizedView() uint64

FinalizedView returns the largest view number where a finalized block is known

func (*Forks) GetBlock

func (f *Forks) GetBlock(blockID flow.Identifier) (*model.Block, bool)

GetBlock returns (BlockProposal, true) if the block with the specified id was found and (nil, false) otherwise.

func (*Forks) GetBlocksForView

func (f *Forks) GetBlocksForView(view uint64) []*model.Block

GetBlocksForView returns all known blocks for the given view

func (*Forks) IsKnownBlock

func (f *Forks) IsKnownBlock(blockID flow.Identifier) bool

IsKnownBlock checks whether block is known.

func (*Forks) IsProcessingNeeded

func (f *Forks) IsProcessingNeeded(block *model.Block) bool

IsProcessingNeeded determines whether the given block needs processing, based on the block's view and hash. Returns false if any of the following conditions applies

• block view is _below_ the most recently finalized block
• the block already exists in the consensus state

UNVALIDATED: expects block to pass Forks.EnsureBlockIsValidExtension(block)