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

     1  package cluster
     2  
     3  import (
     4  	cluster "github.com/onflow/flow-go/model/cluster"
     5  	"github.com/onflow/flow-go/model/flow"
     6  )
     7  
     8  // State represents the chain state for collection node cluster consensus. It
     9  // tracks which blocks are finalized and indexes blocks by number and ID. The
    10  // purpose of cluster consensus is to agree on collections of transactions, so
    11  // each block within the cluster state corresponds to a proposed collection.
    12  //
    13  // NOTE: This is modelled after, and is a simpler version of, protocol.State.
    14  type State interface {
    15  
    16  	// Params returns constant information about the cluster state.
    17  	Params() Params
    18  
    19  	// Final returns the snapshot of the cluster state at the latest finalized
    20  	// block. The returned snapshot is therefore immutable over time.
    21  	Final() Snapshot
    22  
    23  	// AtBlockID returns the snapshot of the persistent cluster at the given
    24  	// block ID. It is available for any block that was introduced into the
    25  	// the cluster state, and can thus represent an ambiguous state that was or
    26  	// will never be finalized.
    27  	AtBlockID(blockID flow.Identifier) Snapshot
    28  }
    29  
    30  // MutableState allows extending the cluster state in a consistent manner that preserves
    31  // integrity, validity, and functionality of the database. It enforces a number of invariants on the
    32  // input data to ensure internal bookkeeping mechanisms remain functional and valid.
    33  type MutableState interface {
    34  	State
    35  	// Extend introduces the given block into the cluster state as a pending
    36  	// without modifying the current finalized state.
    37  	// The block's parent must have already been successfully inserted.
    38  	// Expected errors during normal operations:
    39  	//   - state.OutdatedExtensionError if the candidate block is outdated (e.g. orphaned)
    40  	//   - state.UnverifiableExtensionError if the reference block is _not_ a known finalized block
    41  	//   - state.InvalidExtensionError if the candidate block is invalid
    42  	Extend(candidate *cluster.Block) error
    43  }