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

     1  package protocol
     2  
     3  import "github.com/onflow/flow-go/model/flow"
     4  
     5  // This file contains versioned read interface to the Protocol State's
     6  // key-value store and are used by the Protocol State Machine.
     7  //
     8  // When a key is added or removed, this requires a new protocol state version:
     9  //  - Create a new versioned model in ./protocol_state/kvstore/models.go (eg. modelv3 if latest model is modelv2)
    10  //  - Update the KVStoreReader and protocol_state.KVStoreAPI interfaces to include any new keys
    11  
    12  // KVStoreReader is the latest read-only interface to the Protocol State key-value store
    13  // at a particular block.
    14  //
    15  // Caution:
    16  // Engineers evolving this interface must ensure that it is backwards-compatible
    17  // with all versions of Protocol State Snapshots that can be retrieved from the local
    18  // database, which should exactly correspond to the versioned model types defined in
    19  // ./kvstore/models.go
    20  type KVStoreReader interface {
    21  	// ID returns an identifier for this key-value store snapshot by hashing internal fields.
    22  	// Two different model versions containing the same data must have different IDs.
    23  	// New models should use `makeVersionedModelID` to implement ID.
    24  	ID() flow.Identifier
    25  
    26  	// v0/v1
    27  
    28  	VersionedEncodable
    29  
    30  	// GetProtocolStateVersion returns the Protocol State Version that created the specific
    31  	// Snapshot backing this interface instance. Slightly simplified, the Protocol State
    32  	// Version defines the key-value store's data model (specifically, the set of all keys
    33  	// and the respective type for each corresponding value).
    34  	// Generally, changes in the protocol state version correspond to changes in the set
    35  	// of key-value pairs which are supported, and which model is used for serialization.
    36  	// The protocol state version is updated by UpdateKVStoreVersion service events.
    37  	GetProtocolStateVersion() uint64
    38  
    39  	// GetVersionUpgrade returns the upgrade version of protocol.
    40  	// VersionUpgrade is a view-based activator that specifies the version which has to be applied
    41  	// and the view from which on it has to be applied. It may return the current protocol version
    42  	// with a past view if the upgrade has already been activated.
    43  	GetVersionUpgrade() *ViewBasedActivator[uint64]
    44  
    45  	// GetEpochStateID returns the state ID of the epoch state.
    46  	// This is part of the most basic model and is used to commit the epoch state to the KV store.
    47  	GetEpochStateID() flow.Identifier
    48  }
    49  
    50  // VersionedEncodable defines the interface for a versioned key-value store independent
    51  // of the set of keys which are supported. This allows the storage layer to support
    52  // storing different key-value model versions within the same software version.
    53  type VersionedEncodable interface {
    54  	// VersionedEncode encodes the key-value store, returning the version separately
    55  	// from the encoded bytes.
    56  	// No errors are expected during normal operation.
    57  	VersionedEncode() (uint64, []byte, error)
    58  }
    59  
    60  // ViewBasedActivator allows setting value that will be active from specific view.
    61  type ViewBasedActivator[T any] struct {
    62  	Data           T
    63  	ActivationView uint64 // first view at which Data will take effect
    64  }