forks

package
v0.30.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 31, 2023 License: AGPL-3.0 Imports: 8 Imported by: 6

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrPrunedAncestry = errors.New("cannot resolve pruned ancestor")

ErrPrunedAncestry is a sentinel error: cannot resolve ancestry of block due to pruning

Functions

This section is empty.

Types

type BlockContainer added in v0.29.0 

type BlockContainer struct {
	Proposal *model.Proposal
}

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

func (*BlockContainer) Level added in v0.29.0 

func (b *BlockContainer) Level() uint64

func (*BlockContainer) Parent added in v0.29.0 

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

func (*BlockContainer) VertexID added in v0.29.0 

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

type BlockContainer2 added in v0.30.6 

type BlockContainer2 model.Block

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

func ToBlockContainer2 added in v0.30.6 

func ToBlockContainer2(block *model.Block) *BlockContainer2

func (*BlockContainer2) Block added in v0.30.6 

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

func (*BlockContainer2) Level added in v0.30.6 

func (b *BlockContainer2) Level() uint64

func (*BlockContainer2) Parent added in v0.30.6 

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

func (*BlockContainer2) VertexID added in v0.30.6 

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

Functions implementing forest.Vertex

type FinalityProof added in v0.30.6 

type FinalityProof struct {
	Block          *model.Block
	CertifiedChild model.CertifiedBlock
}

FinalityProof represents a finality proof for a Block. By convention, a FinalityProof is immutable. Finality in Jolteon/HotStuff is determined by the 2-chain rule: 

There exists a _certified_ block C, such that Block.View + 1 = C.View

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.FinalizationConsumer) (*Forks, error)

func (*Forks) AddProposal added in v0.29.0 

func (f *Forks) AddProposal(proposal *model.Proposal) error

AddProposal adds proposal to the consensus state. Performs verification to make sure that we don't add invalid proposals into consensus state. 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. Expected errors during normal operations:

  • model.ByzantineThresholdExceededError - new block results in conflicting finalized blocks

func (*Forks) FinalizedBlock 

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

func (*Forks) FinalizedView 

func (f *Forks) FinalizedView() uint64

func (*Forks) GetProposal added in v0.29.0 

func (f *Forks) GetProposal(blockID flow.Identifier) (*model.Proposal, bool)

GetProposal returns block for given ID

func (*Forks) GetProposalsForView added in v0.29.0 

func (f *Forks) GetProposalsForView(view uint64) []*model.Proposal

GetProposalsForView returns all known proposals for the given view

func (*Forks) IsKnownBlock added in v0.29.0 

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

IsKnownBlock checks whether block is known. UNVALIDATED: expects block to pass Forks.VerifyProposal(block)

func (*Forks) IsProcessingNeeded added in v0.29.0 

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

IsProcessingNeeded performs basic checks to determine whether block needs processing, only considering the block's height 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.VerifyProposal(block)

func (*Forks) NewestView added in v0.29.0 

func (f *Forks) NewestView() uint64

func (*Forks) UnverifiedAddProposal added in v0.29.0 

func (f *Forks) UnverifiedAddProposal(proposal *model.Proposal) error

UnverifiedAddProposal adds `proposal` to the consensus state and updates the latest finalized block, if possible. Calling this method with previously-processed blocks leaves the consensus state invariant (though, it will potentially cause some duplicate processing). UNVALIDATED: expects block to pass Forks.VerifyProposal(block) Error returns: * model.ByzantineThresholdExceededError if proposal's QC conflicts with an existing QC. * generic error in case of unexpected bug or internal state corruption

func (*Forks) VerifyProposal added in v0.29.0 

func (f *Forks) VerifyProposal(proposal *model.Proposal) error

VerifyProposal checks a block for internal consistency and consistency with the current forest state. See forest.VerifyVertex for more detail. 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)
  • generic error in case of unexpected bug or internal state corruption

type Forks2 added in v0.30.6 

type Forks2 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 NewForks2 added in v0.30.6 

func NewForks2(trustedRoot *model.CertifiedBlock, finalizationCallback module.Finalizer, notifier hotstuff.FinalizationConsumer) (*Forks2, error)

func (*Forks2) AddCertifiedBlock added in v0.30.6 

func (f *Forks2) 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.

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 (*Forks2) AddProposal added in v0.30.6 

func (f *Forks2) AddProposal(proposal *model.Block) error

AddProposal appends the given 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 `AddProposal` 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 (*Forks2) EnsureBlockIsValidExtension added in v0.30.6 

func (f *Forks2) 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 (*Forks2) FinalityProof added in v0.30.6 

func (f *Forks2) FinalityProof() (*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 (*Forks2) FinalizedBlock added in v0.30.6 

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

FinalizedBlock returns the finalized block with the largest view number

func (*Forks2) FinalizedView added in v0.30.6 

func (f *Forks2) FinalizedView() uint64

FinalizedView returns the largest view number that has been finalized so far

func (*Forks2) GetBlock added in v0.30.6 

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

GetBlock returns block for given ID

func (*Forks2) GetBlocksForView added in v0.30.6 

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

GetBlocksForView returns all known blocks for the given view

func (*Forks2) IsKnownBlock added in v0.30.6 

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

IsKnownBlock checks whether block is known.

func (*Forks2) IsProcessingNeeded added in v0.30.6 

func (f *Forks2) 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)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.