github.com/koko1123/flow-go-1@v0.29.6/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/koko1123/flow-go-1/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  type MutableState interface {
    41  	State
    42  	// Extend introduces the block with the given ID into the persistent
    43  	// protocol state without modifying the current finalized state. It allows
    44  	// us to execute fork-aware queries against ambiguous protocol state, while
    45  	// still checking that the given block is a valid extension of the protocol
    46  	// state. Depending on implementation it might be a lighter version that checks only
    47  	// block header.
    48  	// Expected errors during normal operations:
    49  	//  * state.OutdatedExtensionError if the candidate block is outdated (e.g. orphaned)
    50  	//  * state.InvalidExtensionError if the candidate block is invalid
    51  	Extend(ctx context.Context, candidate *flow.Block) error
    52  
    53  	// Finalize finalizes the block with the given hash.
    54  	// At this level, we can only finalize one block at a time. This implies
    55  	// that the parent of the pending block that is to be finalized has
    56  	// to be the last finalized block.
    57  	// It modifies the persistent immutable protocol state accordingly and
    58  	// forwards the pointer to the latest finalized state.
    59  	// TODO error docs
    60  	Finalize(ctx context.Context, blockID flow.Identifier) error
    61  
    62  	// MarkValid marks the block header with the given block hash as valid.
    63  	// At this level, we can only mark one block at a time as valid. This
    64  	// implies that the parent of the block to be marked as valid
    65  	// has to be already valid.
    66  	// It modifies the persistent immutable protocol state accordingly.
    67  	// TODO error docs
    68  	MarkValid(blockID flow.Identifier) error
    69  }