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

     1  package storage
     2  
     3  import (
     4  	"github.com/onflow/flow-go/model/flow"
     5  	"github.com/onflow/flow-go/storage/badger/transaction"
     6  )
     7  
     8  // ProtocolState represents persistent storage for protocol state entries.
     9  type ProtocolState interface {
    10  	// StoreTx returns an anonymous function (intended to be executed as part of a badger transaction),
    11  	// which persists the given protocol state as part of a DB tx. Per convention, the identities in
    12  	// the Protocol State must be in canonical order for the current and next epoch (if present),
    13  	// otherwise an exception is returned.
    14  	// Expected errors of the returned anonymous function:
    15  	//   - storage.ErrAlreadyExists if a Protocol State with the given id is already stored
    16  	StoreTx(protocolStateID flow.Identifier, protocolState *flow.ProtocolStateEntry) func(*transaction.Tx) error
    17  
    18  	// Index returns an anonymous function that is intended to be executed as part of a database transaction.
    19  	// In a nutshell, we want to maintain a map from `blockID` to `protocolStateID`, where `blockID` references the
    20  	// block that _proposes_ the Protocol State.
    21  	// Upon call, the anonymous function persists the specific map entry in the node's database.
    22  	// Protocol convention:
    23  	//   - Consider block B, whose ingestion might potentially lead to an updated protocol state. For example,
    24  	//     the protocol state changes if we seal some execution results emitting service events.
    25  	//   - For the key `blockID`, we use the identity of block B which _proposes_ this Protocol State. As value,
    26  	//     the hash of the resulting protocol state at the end of processing B is to be used.
    27  	//   - CAUTION: The protocol state requires confirmation by a QC and will only become active at the child block,
    28  	//     _after_ validating the QC.
    29  	//
    30  	// Expected errors during normal operations:
    31  	//   - storage.ErrAlreadyExists if a Protocol State for the given blockID has already been indexed
    32  	Index(blockID flow.Identifier, protocolStateID flow.Identifier) func(*transaction.Tx) error
    33  
    34  	// ByID returns the protocol state by its ID.
    35  	// Expected errors during normal operations:
    36  	//   - storage.ErrNotFound if no protocol state with the given Identifier is known.
    37  	ByID(id flow.Identifier) (*flow.RichProtocolStateEntry, error)
    38  
    39  	// ByBlockID retrieves the Protocol State that the block with the given ID proposes.
    40  	// CAUTION: this protocol state requires confirmation by a QC and will only become active at the child block,
    41  	// _after_ validating the QC. Protocol convention:
    42  	//   - Consider block B, whose ingestion might potentially lead to an updated protocol state. For example,
    43  	//     the protocol state changes if we seal some execution results emitting service events.
    44  	//   - For the key `blockID`, we use the identity of block B which _proposes_ this Protocol State. As value,
    45  	//     the hash of the resulting protocol state at the end of processing B is to be used.
    46  	//   - CAUTION: The protocol state requires confirmation by a QC and will only become active at the child block,
    47  	//     _after_ validating the QC.
    48  	//
    49  	// Expected errors during normal operations:
    50  	//   - storage.ErrNotFound if no protocol state has been indexed for the given block.
    51  	ByBlockID(blockID flow.Identifier) (*flow.RichProtocolStateEntry, error)
    52  }