github.com/koko1123/flow-go-1@v0.29.6/consensus/hotstuff/forks.go (about)

     1  package hotstuff
     2  
     3  import (
     4  	"github.com/koko1123/flow-go-1/consensus/hotstuff/model"
     5  	"github.com/koko1123/flow-go-1/model/flow"
     6  )
     7  
     8  // Forks encapsulated Finalization Logic and ForkChoice rule in one component.
     9  // Forks maintains an in-memory data-structure of all blocks whose view-number is larger or equal to
    10  // the latest finalized block. The latest finalized block is defined as the finalized block with the largest view number.
    11  // When adding blocks, Forks automatically updates its internal state (including finalized blocks).
    12  // Furthermore, blocks whose view number is smaller than the latest finalized block are pruned automatically.
    13  //
    14  // PREREQUISITES:
    15  // Forks expects that only blocks are added that can be connected to its latest finalized block
    16  // (without missing interim ancestors). If this condition is violated, Forks will raise an error
    17  // and ignore the block.
    18  type Forks interface {
    19  	ForksReader
    20  
    21  	// AddBlock adds the block to Forks. This might cause an update of the finalized block
    22  	// and pruning of older blocks.
    23  	// Handles duplicated addition of blocks (at the potential cost of additional computation time).
    24  	// PREREQUISITE:
    25  	// Forks must be able to connect `block` to its latest finalized block
    26  	// (without missing interim ancestors). Otherwise, an error is raised.
    27  	// When the new block causes the conflicting finalized blocks, it will return
    28  	// Might error with ByzantineThresholdExceededError (e.g. if finalizing conflicting forks)
    29  	AddBlock(block *model.Block) error
    30  
    31  	// AddQC adds a quorum certificate to Forks.
    32  	// Will error in case the block referenced by the qc is unknown.
    33  	// Might error with ByzantineThresholdExceededError (e.g. if two conflicting QCs for the
    34  	// same view are found)
    35  	AddQC(qc *flow.QuorumCertificate) error
    36  
    37  	// MakeForkChoice prompts the ForkChoice to generate a fork choice for the
    38  	// current view `curView`. The fork choice is a qc that should be used for
    39  	// building the primaries block.
    40  	// It returns a qc and the block that the qc is pointing to.
    41  	//
    42  	// PREREQUISITE:
    43  	// ForkChoice cannot generate ForkChoices retroactively for past views.
    44  	// If used correctly, MakeForkChoice should only ever have processed QCs
    45  	// whose view is smaller than curView, for the following reason:
    46  	// Processing a QC with view v should result in the PaceMaker being in
    47  	// view v+1 or larger. Hence, given that the current View is curView,
    48  	// all QCs should have view < curView.
    49  	// To prevent accidental misusage, ForkChoices will error if `curView`
    50  	// is smaller than the view of any qc ForkChoice has seen.
    51  	// Note that tracking the view of the newest qc is for safety purposes
    52  	// and _independent_ of the fork-choice rule.
    53  	MakeForkChoice(curView uint64) (*flow.QuorumCertificate, *model.Block, error)
    54  }
    55  
    56  // ForksReader only reads the forks' state
    57  type ForksReader interface {
    58  
    59  	// IsSafeBlock returns true if block is safe to vote for
    60  	// (according to the definition in https://arxiv.org/abs/1803.05069v6).
    61  	//
    62  	// In the current architecture, the block is stored _before_ evaluating its safety.
    63  	// Consequently, IsSafeBlock accepts only known, valid blocks. Should a block be
    64  	// unknown (not previously added to Forks) or violate some consistency requirements,
    65  	// IsSafeBlock errors. All errors are fatal.
    66  	IsSafeBlock(block *model.Block) bool
    67  
    68  	// GetBlocksForView returns all BlockProposals at the given view number.
    69  	GetBlocksForView(view uint64) []*model.Block
    70  
    71  	// GetBlock returns (BlockProposal, true) if the block with the specified
    72  	// id was found (nil, false) otherwise.
    73  	GetBlock(id flow.Identifier) (*model.Block, bool)
    74  
    75  	// FinalizedView returns the largest view number where a finalized block is known
    76  	FinalizedView() uint64
    77  
    78  	// FinalizedBlock returns the finalized block with the largest view number
    79  	FinalizedBlock() *model.Block
    80  }