github.com/onflow/flow-go@v0.33.17/state/protocol/state.go (about)

     1  // (c) 2019 Dapper Labs - ALL RIGHTS RESERVED
     2  
     3  package protocol
     4  
     5  import (
     6  	"context"
     7  
     8  	"github.com/onflow/flow-go/model/flow"
     9  )
    10  
    11  // State represents the full protocol state of the local node. It allows us to
    12  // obtain snapshots of the state at any point of the protocol state history.
    13  type State interface {
    14  
    15  	// Params gives access to a number of stable parameters of the protocol state.
    16  	Params() Params
    17  
    18  	// Final returns the snapshot of the persistent protocol state at the latest
    19  	// finalized block, and the returned snapshot is therefore immutable over
    20  	// time.
    21  	Final() Snapshot
    22  
    23  	// Sealed returns the snapshot of the persistent protocol state at the
    24  	// latest sealed block, and the returned snapshot is therefore immutable
    25  	// over time.
    26  	Sealed() Snapshot
    27  
    28  	// AtHeight returns the snapshot of the persistent protocol state at the
    29  	// given block number. It is only available for finalized blocks and the
    30  	// returned snapshot is therefore immutable over time.
    31  	AtHeight(height uint64) Snapshot
    32  
    33  	// AtBlockID returns the snapshot of the persistent protocol state at the
    34  	// given block ID. It is available for any block that was introduced into
    35  	// the protocol state, and can thus represent an ambiguous state that was or
    36  	// will never be finalized.
    37  	AtBlockID(blockID flow.Identifier) Snapshot
    38  }
    39  
    40  // FollowerState is a mutable protocol state used by nodes following main consensus (ie. non-consensus nodes).
    41  // All blocks must have a certifying QC when being added to the state to guarantee they are valid,
    42  // so there is a one-block lag between block production and incorporation into the FollowerState.
    43  // However, since all blocks are certified upon insertion, they are immediately processable by other components.
    44  type FollowerState interface {
    45  	State
    46  
    47  	// ExtendCertified introduces the block with the given ID into the persistent
    48  	// protocol state without modifying the current finalized state. It allows us
    49  	// to execute fork-aware queries against the known protocol state. The caller
    50  	// must pass a QC for candidate block to prove that the candidate block has
    51  	// been certified, and it's safe to add it to the protocol state. The QC
    52  	// cannot be nil and must certify candidate block:
    53  	//   candidate.View == qc.View && candidate.BlockID == qc.BlockID
    54  	// The `candidate` block and its QC _must be valid_ (otherwise, the state will
    55  	// be corrupted). ExtendCertified inserts any given block, as long as its
    56  	// parent is already in the protocol state. Also orphaned blocks are excepted.
    57  	// No errors are expected during normal operations.
    58  	ExtendCertified(ctx context.Context, candidate *flow.Block, qc *flow.QuorumCertificate) error
    59  
    60  	// Finalize finalizes the block with the given hash.
    61  	// At this level, we can only finalize one block at a time. This implies
    62  	// that the parent of the pending block that is to be finalized has
    63  	// to be the last finalized block.
    64  	// It modifies the persistent immutable protocol state accordingly and
    65  	// forwards the pointer to the latest finalized state.
    66  	// No errors are expected during normal operations.
    67  	Finalize(ctx context.Context, blockID flow.Identifier) error
    68  }
    69  
    70  // ParticipantState is a mutable protocol state used by active consensus participants (consensus nodes).
    71  // All blocks are validated in full, including payload validation, prior to insertion. Only valid blocks are inserted.
    72  type ParticipantState interface {
    73  	FollowerState
    74  
    75  	// Extend introduces the block with the given ID into the persistent
    76  	// protocol state without modifying the current finalized state. It allows
    77  	// us to execute fork-aware queries against ambiguous protocol state, while
    78  	// still checking that the given block is a valid extension of the protocol state.
    79  	// The candidate block must have passed HotStuff validation before being passed to Extend.
    80  	// Expected errors during normal operations:
    81  	//  * state.OutdatedExtensionError if the candidate block is outdated (e.g. orphaned)
    82  	//  * state.InvalidExtensionError if the candidate block is invalid
    83  	Extend(ctx context.Context, candidate *flow.Block) error
    84  }