github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/state/fork/terminal.go (about)

     1  package fork
     2  
     3  import (
     4  	"github.com/onflow/flow-go/model/flow"
     5  	"github.com/onflow/flow-go/storage"
     6  )
     7  
     8  // Terminal specifies the terminal condition for traversing a fork. It abstracts
     9  // the precise termination condition for `TraverseBackward` and `TraverseForward`.
    10  // Generally, when traversing a fork (in either direction), there are two distinct
    11  // blocks:
    12  //   - the `head` of the fork that should be traversed
    13  //   - the `lowestBlock` in that fork, which should be included in the traversal
    14  //
    15  // The traversal algorithm walks `head <--> lowestBlock` (in either direction).
    16  //
    17  // There are a variety of ways to precisely specify `head` and `lowestBlock`:
    18  //   - At least one block, `head` or `lowestBlock`, must be specified by its ID
    19  //     to unambiguously identify the fork that should be traversed.
    20  //   - The other block an either be specified by ID or height.
    21  //   - If both `head` and `lowestBlock` are specified by their ID,
    22  //     they must both be on the same fork.
    23  //
    24  // Essentially it converts the termination condition into two statements:
    25  //   - (i) The height of the lowest block that should be visited.
    26  //   - (ii) A consistency check `ConfirmTerminalReached` for the lowest visited block.
    27  //     This check is predominantly useful in case both `head` and `lowestBlock`
    28  //     are specified by their ID. It allows to enforce that `head` and `lowestBlock`
    29  //     are both on the same fork and error otherwise.
    30  //     However, the precise implementation of `ConfirmTerminalReached` is left to
    31  //     the Terminal. Other, more elaborate conditions are possible.
    32  type Terminal interface {
    33  	// LowestHeightToVisit computes the height of the lowest block that should be visited
    34  	LowestHeightToVisit(headers storage.Headers) (uint64, error)
    35  
    36  	// ConfirmTerminalReached is a self-consistency check that the lowest visited block is
    37  	// in fact the expected terminal.
    38  	ConfirmTerminalReached(headers storage.Headers, lowestVisitedBlock *flow.Header) error
    39  }