storage

type All struct {
	Headers                   Headers
	Guarantees                Guarantees
	Seals                     Seals
	Index                     Index
	Payloads                  Payloads
	Blocks                    Blocks
	QuorumCertificates        QuorumCertificates
	Setups                    EpochSetups
	EpochCommits              EpochCommits
	ChunkDataPacks            ChunkDataPacks
	Transactions              Transactions
	Collections               Collections
	EpochProtocolStateEntries EpochProtocolStateEntries
	ProtocolKVStore           ProtocolKVStore
	VersionBeacons            VersionBeacons
	RegisterIndex             RegisterIndex

	// These results are for reading and storing the result data from block payload
	// EN uses a different results module to store their own results
	// and receipts (see the Execution struct below)
	Results  ExecutionResults
	Receipts ExecutionReceipts
}

type Batch interface {
	ReaderBatchWriter

	// Commit applies the batched updates to the database.
	// Commit may be called at most once per Batch.
	// No errors are expected during normal operation.
	Commit() error

	// Close releases memory of the batch.
	// Close must be called exactly once per Batch.
	// This can be called as a defer statement immediately after creating Batch
	// to reduce risk of unbounded memory consumption.
	// No errors are expected during normal operation.
	Close() error
}

type BatchStorage interface {
	GetWriter() *badger.WriteBatch

	// OnSucceed adds a callback to execute after the batch has
	// been successfully flushed.
	// useful for implementing the cache where we will only cache
	// after the batch has been successfully flushed
	OnSucceed(callback func())

	// Flush will flush the write batch and update the cache.
	Flush() error
}

type Blocks interface {

	// BatchStore stores a valid block in a batch.
	// Error returns:
	//   - storage.ErrAlreadyExists if the blockID already exists in the database.
	//   - generic error in case of unexpected failure from the database layer or encoding failure.
	BatchStore(lctx lockctx.Proof, rw ReaderBatchWriter, proposal *flow.Proposal) error

	// ByID returns the block with the given hash. It is available for all incorporated blocks (validated blocks
	// that have been appended to any of the known forks) no matter whether the block has been finalized or not.
	//
	// Error returns:
	//   - storage.ErrNotFound if no block with the corresponding ID was found
	//   - generic error in case of unexpected failure from the database layer, or failure
	//     to decode an existing database value
	ByID(blockID flow.Identifier) (*flow.Block, error)

	// ProposalByID returns the block with the given ID, along with the proposer's signature on it.
	// It is available for all incorporated blocks (validated blocks that have been appended to any
	// of the known forks) no matter whether the block has been finalized or not.
	//
	// Error returns:
	//   - storage.ErrNotFound if no block with the corresponding ID was found
	//   - generic error in case of unexpected failure from the database layer, or failure
	//     to decode an existing database value
	ProposalByID(blockID flow.Identifier) (*flow.Proposal, error)

	// ByHeight returns the block at the given height. It is only available
	// for finalized blocks.
	//
	// Error returns:
	//   - storage.ErrNotFound if no block for the corresponding height was found
	//   - generic error in case of unexpected failure from the database layer, or failure
	//     to decode an existing database value
	ByHeight(height uint64) (*flow.Block, error)

	// ProposalByHeight returns the block at the given height, along with the proposer's
	// signature on it. It is only available for finalized blocks.
	//
	// Error returns:
	//   - storage.ErrNotFound if no block proposal for the corresponding height was found
	//   - generic error in case of unexpected failure from the database layer, or failure
	//     to decode an existing database value
	ProposalByHeight(height uint64) (*flow.Proposal, error)

	// ByView returns the block with the given view. It is only available for certified blocks.
	// Certified blocks are the blocks that have received a QC. Hotstuff guarantees that for each view,
	// at most one block is certified. Hence, the return value of `ByView` is guaranteed to be unique
	// even for non-finalized blocks.
	//
	// Expected errors during normal operations:
	//   - `storage.ErrNotFound` if no certified block is known at given view.
	ByView(view uint64) (*flow.Block, error)

	// ProposalByView returns the block proposal with the given view. It is only available for certified blocks.
	//
	// Expected errors during normal operations:
	//   - `storage.ErrNotFound` if no certified block is known at given view.
	ProposalByView(view uint64) (*flow.Proposal, error)

	// ByCollectionID returns the block for the given [flow.CollectionGuarantee] ID.
	// This method is only available for collections included in finalized blocks.
	// While consensus nodes verify that collections are not repeated within the same fork,
	// each different fork can contain a recent collection once. Therefore, we must wait for
	// finality.
	// CAUTION: this method is not backed by a cache and therefore comparatively slow!
	//
	// Error returns:
	//   - storage.ErrNotFound if the collection ID was not found
	//   - generic error in case of unexpected failure from the database layer, or failure
	//     to decode an existing database value
	ByCollectionID(collID flow.Identifier) (*flow.Block, error)

	// IndexBlockContainingCollectionGuarantees populates an index `guaranteeID->blockID` for each guarantee
	// which appears in the block.
	// CAUTION: a collection can be included in multiple *unfinalized* blocks. However, the implementation
	// assumes a one-to-one map from collection ID to a *single* block ID. This holds for FINALIZED BLOCKS ONLY
	// *and* only in the absence of byzantine collector clusters (which the mature protocol must tolerate).
	// Hence, this function should be treated as a temporary solution, which requires generalization
	// (one-to-many mapping) for soft finality and the mature protocol.
	//
	// Error returns:
	//   - generic error in case of unexpected failure from the database layer or encoding failure.
	IndexBlockContainingCollectionGuarantees(blockID flow.Identifier, collIDs []flow.Identifier) error
}

type ChunkDataPacks interface {

	// Store persists multiple ChunkDataPacks in a two-phase process:
	// 1. Store chunk data packs (StoredChunkDataPack) by its hash (chunkDataPackID) in chunk data pack database.
	// 2. Populate index mapping from ChunkID to chunkDataPackID in protocol database.
	//
	// Reasoning for two-phase approach: the chunk data pack and the other execution data are stored in different databases.
	//   - Chunk data pack content is stored in the chunk data pack database by its hash (ID). Conceptually, it would be possible
	//     to store multiple different (disagreeing) chunk data packs here. Each chunk data pack is stored using its own collision
	//     resistant hash as key, so different chunk data packs will be stored under different keys. So from the perspective of the
	//     storage layer, we _could_ in phase 1 store all known chunk data packs. However, an Execution Node may only commit to a single
	//     chunk data pack (or it will get slashed). This mapping from chunk ID to the ID of the chunk data pack that the Execution Node
	//     actually committed to is stored in the protocol database, in the following phase 2.
	//   - In the second phase, we populate the index mappings from ChunkID to one "distinguished" chunk data pack ID. This mapping
	//     is stored in the protocol database. Typically, an Execution Node uses this for indexing its own chunk data packs which it
	//     publicly committed to.
	//
	// ATOMICITY:
	// [ChunkDataPacks.Store] executes phase 1 immediately, persisting the chunk data packs in their dedicated database. However,
	// the index mappings in phase 2 is deferred to the caller, who must invoke the returned functor to perform phase 2. This
	// approach has the following benefits:
	//   - Our API reflects that we are writing to two different databases here, with the chunk data pack database containing largely
	//     specialized data subject to pruning. In contrast, the protocol database persists the commitments a node make (subject to
	//     slashing). The caller receives the ability to persist this commitment in the form of the returned functor. The functor
	//     may be discarded by the caller without corrupting the state (if anything, we have just stored some additional chunk data
	//     packs).
	//   - The serialization and storage of the comparatively large chunk data packs is separated from the protocol database writes.
	//   - The locking duration of the protocol database is reduced.
	//
	// The Store method returns:
	//   - func(lctx lockctx.Proof, rw storage.ReaderBatchWriter) error: Function for populating the index mapping from chunkID
	//     to chunk data pack ID in the protocol database. This mapping persists that the Execution Node committed to the result
	//     represented by this chunk data pack. This function returns [storage.ErrDataMismatch] when a _different_ chunk data pack
	//     ID for the same chunk ID has already been stored (changing which result an execution Node committed to would be a
	//     slashable protocol violation). The caller must acquire [storage.LockInsertChunkDataPack] and hold it until the database
	//     write has been committed.
	//   - error: No error should be returned during normal operation. Any error indicates a failure in the first phase.
	Store(cs []*flow.ChunkDataPack) (func(lctx lockctx.Proof, protocolDBBatch ReaderBatchWriter) error, error)

	// ByChunkID returns the chunk data for the given chunk ID.
	// It returns [storage.ErrNotFound] if no entry exists for the given chunk ID.
	ByChunkID(chunkID flow.Identifier) (*flow.ChunkDataPack, error)

	// BatchRemove schedules all ChunkDataPacks with the given IDs to be deleted from the databases,
	// part of the provided write batches. Unknown IDs are silently ignored.
	// It returns the list of chunk data pack IDs (chunkDataPackID) that were scheduled for removal from the chunk data pack database.
	// It performs a two-phase removal:
	// 1. First phase: Remove index mappings from ChunkID to chunkDataPackID in the protocol database
	// 2. Second phase: Remove chunk data packs (StoredChunkDataPack) by its hash (chunkDataPackID) in chunk data pack database.
	//  This phase is deferred until the caller of BatchRemove invokes the returned functor.
	//
	// Note: it does not remove the collection referred by the chunk data pack.
	// This method is useful for the rollback execution tool to batch remove chunk data packs associated with a set of blocks.
	// No errors are expected during normal operation, even if no entries are matched.
	BatchRemove(chunkIDs []flow.Identifier, rw ReaderBatchWriter) (chunkDataPackIDs []flow.Identifier, err error)

	// BatchRemoveChunkDataPacksOnly removes multiple ChunkDataPacks with the given chunk IDs from chunk data pack database only.
	// It does not remove the index mappings from ChunkID to chunkDataPackID in the protocol database.
	// This method is useful for the runtime chunk data pack pruner to batch remove chunk data packs associated with a set of blocks.
	// CAUTION: the chunk data pack batch is for chunk data pack database only, DO NOT pass a batch writer for protocol database.
	// No errors are expected during normal operation, even if no entries are matched.
	BatchRemoveChunkDataPacksOnly(chunkIDs []flow.Identifier, chunkDataPackBatch ReaderBatchWriter) error
}

type ChunksQueue interface {
	StoreChunkLocator(locator *chunks.Locator) (bool, error)

	LatestIndex() (uint64, error)

	AtIndex(index uint64) (*chunks.Locator, error)
}

type ClusterBlocks interface {

	// ProposalByID returns the collection with the given ID, along with the proposer's signature on it.
	// It is available for all incorporated collections (validated blocks that have been appended to any
	// of the known forks) no matter whether the collection has been finalized or not.
	//
	// Error returns:
	//   - storage.ErrNotFound if the block ID was not found
	//   - generic error in case of unexpected failure from the database layer, or failure
	//     to decode an existing database value
	ProposalByID(blockID flow.Identifier) (*cluster.Proposal, error)

	// ProposalByHeight returns the collection at the given height, along with the proposer's
	// signature on it. It is only available for finalized collections.
	//
	// Error returns:
	//   - storage.ErrNotFound if the block height or block ID was not found
	//   - generic error in case of unexpected failure from the database layer, or failure
	//     to decode an existing database value
	ProposalByHeight(height uint64) (*cluster.Proposal, error)
}

type ClusterPayloads interface {

	// ByBlockID returns the cluster payload for the given block ID.
	ByBlockID(blockID flow.Identifier) (*cluster.Payload, error)
}

type Collections interface {
	CollectionsReader

	// Store inserts the collection keyed by ID and all constituent
	// transactions.
	// This is used by execution node storing collections.
	// No errors are expected during normal operation.
	Store(collection *flow.Collection) (*flow.LightCollection, error)

	// Remove removes the collection and all constituent transactions.
	// No errors are expected during normal operation.
	Remove(collID flow.Identifier) error

	// StoreAndIndexByTransaction stores the collection and indexes it by transaction.
	// This is used by access node storing collections for finalized blocks.
	//
	// CAUTION: current approach is NOT BFT and needs to be revised in the future.
	// Honest clusters ensure a transaction can only belong to one collection. However, in rare
	// cases, the collector clusters can exceed byzantine thresholds -- making it possible to
	// produce multiple finalized collections (aka guaranteed collections) containing the same
	// transaction repeatedly.
	// TODO: eventually we need to handle Byzantine clusters
	//
	// No errors are expected during normal operation.
	StoreAndIndexByTransaction(lctx lockctx.Proof, collection *flow.Collection) (*flow.LightCollection, error)

	// BatchStoreAndIndexByTransaction stores the collection and indexes it by transaction within a batch.
	//
	// CAUTION: current approach is NOT BFT and needs to be revised in the future.
	// Honest clusters ensure a transaction can only belong to one collection. However, in rare
	// cases, the collector clusters can exceed byzantine thresholds -- making it possible to
	// produce multiple finalized collections (aka guaranteed collections) containing the same
	// transaction repeatedly.
	// TODO: eventually we need to handle Byzantine clusters
	//
	// This is used by access node storing collections for finalized blocks
	BatchStoreAndIndexByTransaction(lctx lockctx.Proof, collection *flow.Collection, batch ReaderBatchWriter) (*flow.LightCollection, error)
}

type CollectionsReader interface {
	// ByID returns the collection with the given ID, including all
	// transactions within the collection.
	//
	// Expected errors during normal operation:
	//   - `storage.ErrNotFound` if no light collection was found.
	ByID(collID flow.Identifier) (*flow.Collection, error)

	// LightByID returns a reduced representation of the collection with the given ID.
	// The reduced collection references the constituent transactions by their hashes.
	//
	// Expected errors during normal operation:
	//   - `storage.ErrNotFound` if no light collection was found.
	LightByID(collID flow.Identifier) (*flow.LightCollection, error)

	// LightByTransactionID returns a reduced representation of the collection
	// holding the given transaction ID. The reduced collection references the
	// constituent transactions by their hashes.
	//
	// Expected errors during normal operation:
	//   - `storage.ErrNotFound` if no light collection was found.
	LightByTransactionID(txID flow.Identifier) (*flow.LightCollection, error)
}

type Commits interface {
	CommitsReader

	// BatchStore stores Commit keyed by blockID in provided batch
	// No errors are expected during normal operation, even if no entries are matched.
	// If the database unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	BatchStore(lctx lockctx.Proof, blockID flow.Identifier, commit flow.StateCommitment, batch ReaderBatchWriter) error

	// BatchRemoveByBlockID removes Commit keyed by blockID in provided batch
	// No errors are expected during normal operation, even if no entries are matched.
	// If the database unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	BatchRemoveByBlockID(blockID flow.Identifier, batch ReaderBatchWriter) error
}

type CommitsReader interface {
	// ByBlockID will retrieve a commit by its ID from persistent storage.
	ByBlockID(blockID flow.Identifier) (flow.StateCommitment, error)
}

type ComputationResultUploadStatus interface {
	// Upsert upserts omputationResult into persistent storage with given BlockID.
	Upsert(blockID flow.Identifier, wasUploadCompleted bool) error

	// GetIDsByUploadStatus returns BlockIDs whose upload status matches with targetUploadStatus
	GetIDsByUploadStatus(targetUploadStatus bool) ([]flow.Identifier, error)

	// ByID returns the upload status of ComputationResult with given BlockID.
	ByID(blockID flow.Identifier) (bool, error)

	// Remove removes an instance of ComputationResult with given BlockID.
	Remove(blockID flow.Identifier) error
}

type ConsumerProgress interface {
	// ProcessedIndex returns the processed index for the consumer
	// No errors are expected during normal operation
	ProcessedIndex() (uint64, error)

	// SetProcessedIndex updates the processed index for the consumer
	// The caller must use ConsumerProgressInitializer to initialize the progress index in storage
	// No errors are expected during normal operation
	SetProcessedIndex(processed uint64) error

	// BatchSetProcessedIndex updates the processed index for the consumer within in provided batch
	// The caller must use ConsumerProgressInitializer to initialize the progress index in storage
	// No errors are expected during normal operation
	BatchSetProcessedIndex(processed uint64, batch ReaderBatchWriter) error
}

type ConsumerProgressInitializer interface {
	// Initialize takes a default index and initializes the consumer progress index in storage
	// Initialize must be concurrent safe, meaning if called by different modules, should only
	// initialize once.
	Initialize(defaultIndex uint64) (ConsumerProgress, error)
}

type DB interface {
	// Reader returns a database-backed reader which reads the latest
	// committed global database state
	Reader() Reader

	// WithReaderBatchWriter creates a batch writer and allows the caller to perform
	// atomic batch updates to the database.
	// Any error returned are considered fatal and the batch is not committed.
	WithReaderBatchWriter(func(ReaderBatchWriter) error) error

	// NewBatch create a new batch for writing.
	NewBatch() Batch

	// Close closes the database and releases all resources.
	// No errors are expected during normal operation.
	Close() error
}

type DKGState interface {
	DKGStateReader

	// SetDKGState performs a state transition for the Random Beacon Recoverable State Machine.
	// Some state transitions may not be possible using this method. For instance, we might not be able to enter [flow.DKGStateCompleted]
	// state directly from [flow.DKGStateStarted], even if such transition is valid. The reason for this is that some states require additional
	// data to be processed by the state machine before the transition can be made. For such cases there are dedicated methods that should be used, ex.
	// InsertMyBeaconPrivateKey and UpsertMyBeaconPrivateKey, which allow to store the needed data and perform the transition in one atomic operation.
	// Error returns:
	//   - [storage.InvalidDKGStateTransitionError] - if the requested state transition is invalid.
	SetDKGState(epochCounter uint64, newState flow.DKGState) error

	// InsertMyBeaconPrivateKey stores the random beacon private key for an epoch and transitions the
	// state machine into the [flow.DKGStateCompleted] state.
	//
	// CAUTION: these keys are stored before they are validated against the
	// canonical key vector and may not be valid for use in signing. Use [SafeBeaconKeys]
	// to guarantee only keys safe for signing are returned
	// Error returns:
	//   - [storage.ErrAlreadyExists] - if there is already a key stored for given epoch.
	//   - [storage.InvalidDKGStateTransitionError] - if the requested state transition is invalid.
	InsertMyBeaconPrivateKey(epochCounter uint64, key crypto.PrivateKey) error

	// CommitMyBeaconPrivateKey commits the previously inserted random beacon private key for an epoch. Effectively, this method
	// transitions the state machine into the [flow.RandomBeaconKeyCommitted] state if the current state is [flow.DKGStateCompleted].
	// The caller needs to supply the [flow.EpochCommit] as evidence that the stored key is valid for the specified epoch. Repeated
	// calls for the same epoch are accepted (idempotent operation),if and only if the provided EpochCommit confirms the already
	// committed key.
	// No errors are expected during normal operations.
	CommitMyBeaconPrivateKey(epochCounter uint64, commit *flow.EpochCommit) error
}

type DKGStateReader interface {
	SafeBeaconKeys

	// GetDKGState retrieves the current state of the state machine for the given epoch.
	// If an error is returned, the state is undefined meaning that state machine is in initial state
	// Error returns:
	//   - [storage.ErrNotFound] - if there is no state stored for given epoch, meaning the state machine is in initial state.
	GetDKGState(epochCounter uint64) (flow.DKGState, error)

	// IsDKGStarted checks whether the DKG has been started for the given epoch.
	// No errors expected during normal operation.
	IsDKGStarted(epochCounter uint64) (bool, error)

	// UnsafeRetrieveMyBeaconPrivateKey retrieves the random beacon private key for an epoch.
	//
	// CAUTION: these keys are stored before they are validated against the
	// canonical key vector and may not be valid for use in signing. Use SafeBeaconKeys
	// to guarantee only keys safe for signing are returned
	// Error returns:
	//   - [storage.ErrNotFound] - if there is no key stored for given epoch.
	UnsafeRetrieveMyBeaconPrivateKey(epochCounter uint64) (crypto.PrivateKey, error)
}

type EpochCommits interface {

	// BatchStore allows us to store a new epoch commit in a DB batch update while updating the cache.
	// No errors are expected during normal operation.
	BatchStore(rw ReaderBatchWriter, commit *flow.EpochCommit) error

	// ByID will return the EpochCommit event by its ID.
	// Error returns:
	// * storage.ErrNotFound if no EpochCommit with the ID exists
	ByID(flow.Identifier) (*flow.EpochCommit, error)
}

type EpochProtocolStateEntries interface {

	// BatchStore persists the given epoch protocol state entry as part of a DB batch. Per convention, the identities in
	// the flow.MinEpochStateEntry must be in canonical order for the current and next epoch (if present), otherwise an
	// exception is returned.
	//
	// CAUTION: The caller must ensure `epochProtocolStateID` is a collision-resistant hash of the provided
	// `epochProtocolStateEntry`! This method silently overrides existing data, which is safe only if for the same
	// key, we always write the same value.
	//
	// No errors are expected during normal operation.
	BatchStore(w Writer, epochProtocolStateID flow.Identifier, epochProtocolStateEntry *flow.MinEpochStateEntry) error

	// BatchIndex persists the specific map entry in the node's database.
	// In a nutshell, we want to maintain a map from `blockID` to `epochStateEntry`, where `blockID` references the
	// block that _proposes_ the referenced epoch protocol state entry.
	// Protocol convention:
	//   - Consider block B, whose ingestion might potentially lead to an updated protocol state. For example,
	//     the protocol state changes if we seal some execution results emitting service events.
	//   - For the key `blockID`, we use the identity of block B which _proposes_ this Protocol State. As value,
	//     the hash of the resulting protocol state at the end of processing B is to be used.
	//   - IMPORTANT: The protocol state requires confirmation by a QC and will only become active at the child block,
	//     _after_ validating the QC.
	//
	// CAUTION:
	//   - The caller must acquire the lock [storage.LockInsertBlock] and hold it until the database write has been committed.
	//   - OVERWRITES existing data (potential for data corruption):
	//     The lock proof serves as a reminder that the CALLER is responsible to ensure that the DEDUPLICATION CHECK is done elsewhere
	//     ATOMICALLY within this write operation. Currently it's done by operation.InsertHeader where it performs a check
	//     to ensure the blockID is new, therefore any data indexed by this blockID is new as well.
	//
	// Expected errors during normal operations:
	// No expected errors during normal operations.
	BatchIndex(lctx lockctx.Proof, rw ReaderBatchWriter, blockID flow.Identifier, epochProtocolStateID flow.Identifier) error

	// ByID returns the flow.RichEpochStateEntry by its ID.
	// Expected errors during normal operations:
	//   - storage.ErrNotFound if no epoch state entry with the given Identifier is known.
	ByID(id flow.Identifier) (*flow.RichEpochStateEntry, error)

	// ByBlockID retrieves the flow.RichEpochStateEntry that the block with the given ID proposes.
	// CAUTION: this protocol state requires confirmation by a QC and will only become active at the child block,
	// _after_ validating the QC. Protocol convention:
	//   - Consider block B, whose ingestion might potentially lead to an updated protocol state. For example,
	//     the protocol state changes if we seal some execution results emitting service events.
	//   - For the key `blockID`, we use the identity of block B which _proposes_ this Protocol State. As value,
	//     the hash of the resulting protocol state at the end of processing B is to be used.
	//   - CAUTION: The protocol state requires confirmation by a QC and will only become active at the child block,
	//     _after_ validating the QC.
	//
	// Expected errors during normal operations:
	//   - storage.ErrNotFound if no epoch state entry has been indexed for the given block.
	ByBlockID(blockID flow.Identifier) (*flow.RichEpochStateEntry, error)
}

type EpochRecoveryMyBeaconKey interface {
	DKGStateReader

	// UpsertMyBeaconPrivateKey overwrites the random beacon private key for the epoch that recovers the protocol
	// from Epoch Fallback Mode. The resulting state of this method call is [flow.RandomBeaconKeyCommitted].
	// State transitions are allowed if and only if the current state is not equal to [flow.RandomBeaconKeyCommitted].
	// Repeated calls for the same epoch are idempotent, if and only if the provided EpochCommit confirms the already
	// committed key (error otherwise).
	// No errors are expected during normal operations.
	UpsertMyBeaconPrivateKey(epochCounter uint64, key crypto.PrivateKey, commit *flow.EpochCommit) error
}

type EpochSetups interface {

	// BatchStore allows us to store a new epoch setup in a DB batch update while going through the cache.
	// No errors are expected during normal operation.
	BatchStore(rw ReaderBatchWriter, setup *flow.EpochSetup) error

	// ByID will return the EpochSetup event by its ID.
	// Error returns:
	// * storage.ErrNotFound if no EpochSetup with the ID exists
	ByID(flow.Identifier) (*flow.EpochSetup, error)
}

type Events interface {
	EventsReader

	// Store will store events for the given block ID
	// TODO: error documentation
	Store(blockID flow.Identifier, blockEvents []flow.EventsList) error

	// BatchStore will store events for the given block ID in a given batch
	// TODO: error documentation
	BatchStore(blockID flow.Identifier, events []flow.EventsList, batch ReaderBatchWriter) error

	// BatchRemoveByBlockID removes events keyed by a blockID in provided batch
	// No errors are expected during normal operation, even if no entries are matched.
	// If database unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	BatchRemoveByBlockID(blockID flow.Identifier, batch ReaderBatchWriter) error
}

type EventsReader interface {
	// ByBlockID returns the events for the given block ID
	ByBlockID(blockID flow.Identifier) ([]flow.Event, error)

	// ByBlockIDTransactionID returns the events for the given block ID and transaction ID
	ByBlockIDTransactionID(blockID flow.Identifier, transactionID flow.Identifier) ([]flow.Event, error)

	// ByBlockIDTransactionIndex returns the events for the transaction at given index in a given block
	ByBlockIDTransactionIndex(blockID flow.Identifier, txIndex uint32) ([]flow.Event, error)

	// ByBlockIDEventType returns the events for the given block ID and event type
	ByBlockIDEventType(blockID flow.Identifier, eventType flow.EventType) ([]flow.Event, error)
}

type ExecutionForkEvidence interface {
	// StoreIfNotExists stores the given conflictingSeals to the database
	// if no execution fork evidence is currently stored in the database.
	// This function is a no-op if evidence is already stored, because
	// only one execution fork evidence can be stored at a time.
	// The caller must hold the [storage.LockInsertExecutionForkEvidence] lock.
	// No errors are expected during normal operations.
	StoreIfNotExists(lctx lockctx.Proof, conflictingSeals []*flow.IncorporatedResultSeal) error

	// Retrieve reads conflicting seals from the database.
	// No error is returned if database record doesn't exist.
	// No errors are expected during normal operations.
	Retrieve() ([]*flow.IncorporatedResultSeal, error)
}

type ExecutionReceipts interface {

	// Store stores an execution receipt.
	Store(receipt *flow.ExecutionReceipt) error

	// BatchStore stores an execution receipt inside given batch
	BatchStore(receipt *flow.ExecutionReceipt, batch ReaderBatchWriter) error

	// ByID retrieves an execution receipt by its ID.
	ByID(receiptID flow.Identifier) (*flow.ExecutionReceipt, error)

	// ByBlockID retrieves all known execution receipts for the given block
	// (from any Execution Node).
	//
	// No errors are expected errors during normal operations.
	ByBlockID(blockID flow.Identifier) (flow.ExecutionReceiptList, error)
}

type ExecutionResults interface {
	ExecutionResultsReader

	// Store stores an execution result.
	Store(result *flow.ExecutionResult) error

	// BatchStore stores an execution result in a given batch
	BatchStore(result *flow.ExecutionResult, batch ReaderBatchWriter) error

	// Index indexes an execution result by block ID.
	Index(blockID flow.Identifier, resultID flow.Identifier) error

	// ForceIndex indexes an execution result by block ID overwriting existing database entry
	ForceIndex(blockID flow.Identifier, resultID flow.Identifier) error

	// BatchIndex indexes an execution result by block ID in a given batch
	BatchIndex(blockID flow.Identifier, resultID flow.Identifier, batch ReaderBatchWriter) error

	// BatchRemoveIndexByBlockID removes blockID-to-executionResultID index entries keyed by blockID in a provided batch.
	// No errors are expected during normal operation, even if no entries are matched.
	// If Badger unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	BatchRemoveIndexByBlockID(blockID flow.Identifier, batch ReaderBatchWriter) error
}

type ExecutionResultsReader interface {
	// ByID retrieves an execution result by its ID. Returns `ErrNotFound` if `resultID` is unknown.
	ByID(resultID flow.Identifier) (*flow.ExecutionResult, error)

	// ByBlockID retrieves an execution result by block ID.
	ByBlockID(blockID flow.Identifier) (*flow.ExecutionResult, error)
}

type Guarantees interface {

	// ByID returns the [flow.CollectionGuarantee] by its ID.
	// Expected errors during normal operations:
	//   - [storage.ErrNotFound] if no collection guarantee with the given Identifier is known.
	ByID(guaranteeID flow.Identifier) (*flow.CollectionGuarantee, error)

	// ByCollectionID retrieves the collection guarantee by collection ID.
	// Expected errors during normal operations:
	//   - [storage.ErrNotFound] if no collection guarantee has been indexed for the given collection ID.
	ByCollectionID(collID flow.Identifier) (*flow.CollectionGuarantee, error)
}

type Headers interface {

	// ByBlockID returns the header with the given ID. It is available for finalized blocks and those pending finalization.
	// Error returns:
	//  - [storage.ErrNotFound] if no block header with the given ID exists
	ByBlockID(blockID flow.Identifier) (*flow.Header, error)

	// ByHeight returns the block with the given number. It is only available for finalized blocks.
	// Error returns:
	//  - [storage.ErrNotFound] if no finalized block is known at the given height
	ByHeight(height uint64) (*flow.Header, error)

	// ByView returns the block with the given view. It is only available for certified blocks.
	// Certified blocks are the blocks that have received QC. Hotstuff guarantees that for each view,
	// at most one block is certified. Hence, the return value of `ByView` is guaranteed to be unique
	// even for non-finalized blocks.
	//
	// Expected errors during normal operations:
	//   - [storage.ErrNotFound] if no certified block is known at given view.
	ByView(view uint64) (*flow.Header, error)

	// Exists returns true if a header with the given ID has been stored.
	// No errors are expected during normal operation.
	Exists(blockID flow.Identifier) (bool, error)

	// BlockIDByHeight returns the block ID that is finalized at the given height. It is an optimized
	// version of `ByHeight` that skips retrieving the block. Expected errors during normal operations:
	//  - [storage.ErrNotFound] if no finalized block is known at given height
	BlockIDByHeight(height uint64) (flow.Identifier, error)

	// ByParentID finds all children for the given parent block. The returned headers
	// might be unfinalized; if there is more than one, at least one of them has to
	// be unfinalized.
	// CAUTION: this method is not backed by a cache and therefore comparatively slow!
	//
	// Expected error returns during normal operations:
	//   - [storage.ErrNotFound] if no block with the given parentID is known
	ByParentID(parentID flow.Identifier) ([]*flow.Header, error)

	// ProposalByBlockID returns the header with the given ID, along with the corresponding proposer signature.
	// It is available for finalized blocks and those pending finalization.
	// Error returns:
	//  - [storage.ErrNotFound] if no block header or proposer signature with the given blockID exists
	ProposalByBlockID(blockID flow.Identifier) (*flow.ProposalHeader, error)
}

type HeightIndex interface {
	// LatestHeight returns the latest indexed height.
	LatestHeight() (uint64, error)
	// FirstHeight at which we started to index. Returns the first indexed height found in the store.
	FirstHeight() (uint64, error)
	// SetLatestHeight updates the latest height.
	// The provided height should either be one higher than the current height or the same to ensure idempotency.
	// If the height is not within those bounds it will panic!
	// An error might get returned if there are problems with persisting the height.
	SetLatestHeight(height uint64) error
}

type Index interface {

	// ByBlockID retrieves the index for a block payload.
	// Error returns:
	//  - ErrNotFound if no block header with the given ID exists
	ByBlockID(blockID flow.Identifier) (*flow.Index, error)
}

type InvalidDKGStateTransitionError struct {
	From flow.DKGState
	To   flow.DKGState
	// contains filtered or unexported fields
}

type IterItem interface {
	// Key returns the key of the current key-value pair
	// Key is only valid until the Iterator.Next() method is called
	// If you need to use it outside its validity, please use KeyCopy
	Key() []byte

	// KeyCopy returns a copy of the key of the item, writing it to dst slice.
	// If nil is passed, or capacity of dst isn't sufficient, a new slice would be allocated and
	// returned.
	KeyCopy(dst []byte) []byte

	// Value returns the value of the current key-value pair
	// The reason it takes a function is to follow badgerDB's API pattern
	// No errors expected during normal operation
	Value(func(val []byte) error) error
}

type Iterator interface {
	// First seeks to the smallest key greater than or equal to the given key.
	// This method must be called because it's necessary for the badger implementation
	// to move the iteration cursor to the first key in the iteration range.
	// This method must be called before calling Valid, Next, IterItem, or Close.
	// return true if the iterator is pointing to a valid key-value pair after calling First,
	// return false otherwise.
	First() bool

	// Valid returns whether the iterator is positioned at a valid key-value pair.
	// If Valid returns false, the iterator is done and must be closed.
	Valid() bool

	// Next advances the iterator to the next key-value pair.
	// The next key-value pair might be invalid, so you should call Valid() to check.
	Next()

	// IterItem returns the current key-value pair, or nil if Valid returns false.
	// Always to call Valid() before calling IterItem.
	// Note, the returned item is only valid until the Next() method is called.
	IterItem() IterItem

	// Close closes the iterator. Iterator must be closed, otherwise it causes memory leak.
	// No errors expected during normal operation
	Close() error
}

type IteratorOption struct {
	BadgerIterateKeyOnly bool // default false
}

type LatestPersistedSealedResult interface {
	// Latest returns the ID and height of the latest persisted sealed result.
	Latest() (flow.Identifier, uint64)

	// BatchSet updates the latest persisted sealed result in a batch operation
	// The resultID and height are added to the provided batch, and the local data is updated only after
	// the batch is successfully committed.
	//
	// No errors are expected during normal operation,
	BatchSet(resultID flow.Identifier, height uint64, batch ReaderBatchWriter) error
}

type Ledger interface {
	EmptyStateCommitment() flow.StateCommitment

	// Trusted methods (without proof)
	// Get registers at specific StateCommitment by a list of register ids
	GetRegisters(registerIDs []flow.RegisterID, stateCommitment flow.StateCommitment) (values []flow.RegisterValue, err error)
	// Batched atomic updates of a subset of registers at specific state
	UpdateRegisters(registerIDs []flow.RegisterID, values []flow.RegisterValue, stateCommitment flow.StateCommitment) (newStateCommitment flow.StateCommitment, err error)

	// Untrusted methods (providing proofs)
	// Get registers at specific StateCommitment by a list of register ids with proofs
	GetRegistersWithProof(registerIDs []flow.RegisterID, stateCommitment flow.StateCommitment) (values []flow.RegisterValue, proofs []flow.StorageProof, err error)
	// Batched atomic updates of a subset of registers at specific state with proofs
	UpdateRegistersWithProof(registerIDs []flow.RegisterID, values []flow.RegisterValue, stateCommitment flow.StateCommitment) (newStateCommitment flow.StateCommitment, proofs []flow.StorageProof, err error)
}

type LedgerVerifier interface {
	// verify if a provided proof for getRegisters is accurate
	VerifyRegistersProof(registerIDs []flow.RegisterID, stateCommitment flow.StateCommitment, values []flow.RegisterValue, proof []flow.StorageProof) (verified bool, err error)
}

type LightTransactionResults interface {
	LightTransactionResultsReader

	// BatchStore persists and indexes all transaction results (light representation) for the given blockID
	// as part of the provided batch. The caller must acquire [storage.LockInsertLightTransactionResult] and
	// hold it until the write batch has been committed.
	// It returns [storage.ErrAlreadyExists] if light transaction results for the block already exist.
	BatchStore(lctx lockctx.Proof, rw ReaderBatchWriter, blockID flow.Identifier, transactionResults []flow.LightTransactionResult) error
}

type LightTransactionResultsReader interface {
	// ByBlockIDTransactionID returns the transaction result for the given block ID and transaction ID
	//
	// Expected error returns during normal operation:
	//   - [storage.ErrNotFound] if light transaction result at given blockID wasn't found.
	ByBlockIDTransactionID(blockID flow.Identifier, transactionID flow.Identifier) (*flow.LightTransactionResult, error)

	// ByBlockIDTransactionIndex returns the transaction result for the given blockID and transaction index
	//
	// Expected error returns during normal operation:
	//   - [storage.ErrNotFound] if light transaction result at given blockID and txIndex wasn't found.
	ByBlockIDTransactionIndex(blockID flow.Identifier, txIndex uint32) (*flow.LightTransactionResult, error)

	// ByBlockID gets all transaction results for a block, ordered by transaction index
	// CAUTION: this function returns the empty list in case for block IDs without known results.
	// No error returns are expected during normal operations.
	ByBlockID(id flow.Identifier) ([]flow.LightTransactionResult, error)
}

type LockManager = lockctx.Manager

type MyExecutionReceipts interface {
	// BatchStoreMyReceipt stores blockID-to-my-receipt index entry keyed by blockID in a provided batch.
	//
	// If entity fails marshalling, the error is wrapped in a generic error and returned.
	// If database unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	//
	// Expected error returns during *normal* operations:
	//   - `storage.ErrDataMismatch` if a *different* receipt has already been indexed for the same block
	BatchStoreMyReceipt(lctx lockctx.Proof, receipt *flow.ExecutionReceipt, batch ReaderBatchWriter) error

	// MyReceipt retrieves my receipt for the given block.
	MyReceipt(blockID flow.Identifier) (*flow.ExecutionReceipt, error)

	// BatchRemoveIndexByBlockID removes blockID-to-my-execution-receipt index entry keyed by a blockID in a provided batch
	// No errors are expected during normal operation, even if no entries are matched.
	// If database unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	BatchRemoveIndexByBlockID(blockID flow.Identifier, batch ReaderBatchWriter) error
}

type NodeDisallowList interface {
	// Store writes the given disallowList to the database.
	// To avoid legacy entries in the database, we purge
	// the entire database entry if disallowList is empty.
	// No errors are expected during normal operations.
	Store(disallowList map[flow.Identifier]struct{}) error

	// Retrieve reads the set of disallowed nodes from the database.
	// No error is returned if no database entry exists.
	// No errors are expected during normal operations.
	Retrieve(disallowList *map[flow.Identifier]struct{}) error
}

type Payloads interface {

	// ByBlockID returns the payload with the given hash. It is available for
	// finalized and ambiguous blocks.
	ByBlockID(blockID flow.Identifier) (*flow.Payload, error)
}

type ProtocolKVStore interface {
	// BatchStore persists the KV-store snapshot in the database using the given ID as key.
	// BatchStore is idempotent, i.e. it accepts repeated calls with the same pairs of (stateID, kvStore).
	// Here, the ID is expected to be a collision-resistant hash of the snapshot (including the
	// ProtocolStateVersion).
	//
	// No error is expected during normal operations.
	BatchStore(rw ReaderBatchWriter, stateID flow.Identifier, data *flow.PSKeyValueStoreData) error

	// BatchIndex appends the following operation to the provided write batch:
	// we extend the map from `blockID` to `stateID`, where `blockID` references the
	// block that _proposes_ updated key-value store.
	// BatchIndex is idempotent, i.e. it accepts repeated calls with the same pairs of (blockID , stateID).
	// Per protocol convention, the block references the `stateID`. As the `blockID` is a collision-resistant hash,
	// for the same `blockID`, BatchIndex will reject changing the data.
	// Protocol convention:
	//   - Consider block B, whose ingestion might potentially lead to an updated KV store. For example,
	//     the KV store changes if we seal some execution results emitting specific service events.
	//   - For the key `blockID`, we use the identity of block B which _proposes_ this updated KV store.
	//   - IMPORTANT: The updated state requires confirmation by a QC and will only become active at the
	//     child block, _after_ validating the QC.
	//
	// CAUTION: To prevent data corruption, we need to guarantee atomicity of existence-check and the subsequent
	// database write. Hence, we require the caller to acquire [storage.LockInsertBlock] and hold it until the
	// database write has been committed.
	//
	// Expected error returns during normal operations:
	// - [storage.ErrAlreadyExists] if a KV store for the given blockID has already been indexed
	BatchIndex(lctx lockctx.Proof, rw ReaderBatchWriter, blockID flow.Identifier, stateID flow.Identifier) error

	// ByID retrieves the KV store snapshot with the given ID.
	// Expected errors during normal operations:
	//   - storage.ErrNotFound if no snapshot with the given Identifier is known.
	ByID(id flow.Identifier) (*flow.PSKeyValueStoreData, error)

	// ByBlockID retrieves the kv-store snapshot that the block with the given ID proposes.
	// CAUTION: this store snapshot requires confirmation by a QC and will only become active at the child block,
	// _after_ validating the QC. Protocol convention:
	//   - Consider block B, whose ingestion might potentially lead to an updated KV store state.
	//     For example, the state changes if we seal some execution results emitting specific service events.
	//   - For the key `blockID`, we use the identity of block B which _proposes_ this updated KV store. As value,
	//     the hash of the resulting state at the end of processing B is to be used.
	//   - CAUTION: The updated state requires confirmation by a QC and will only become active at the child block,
	//     _after_ validating the QC.
	//
	// Expected errors during normal operations:
	//   - storage.ErrNotFound if no snapshot has been indexed for the given block.
	ByBlockID(blockID flow.Identifier) (*flow.PSKeyValueStoreData, error)
}

type QuorumCertificates interface {
	// BatchStore stores a Quorum Certificate as part of database batch update. QC is indexed by QC.BlockID.
	//
	// Note: For the same block, different QCs can easily be constructed by selecting different sub-sets of the received votes
	// (provided more than the minimal number of consensus participants voted, which is typically the case). In most cases, it
	// is only important that a block has been certified, but irrelevant who specifically contributed to the QC. Therefore, we
	// only store the first QC.
	//
	// If *any* quorum certificate for QC.BlockID has already been stored, a `storage.ErrAlreadyExists` is returned (typically benign).
	BatchStore(lockctx.Proof, ReaderBatchWriter, *flow.QuorumCertificate) error

	// ByBlockID returns QC that certifies block referred by blockID.
	// * storage.ErrNotFound if no QC for blockID doesn't exist.
	ByBlockID(blockID flow.Identifier) (*flow.QuorumCertificate, error)
}

type Reader interface {
	// Get gets the value for the given key. It returns ErrNotFound if the DB
	// does not contain the key.
	// other errors are exceptions
	//
	// The caller should not modify the contents of the returned slice, but it is
	// safe to modify the contents of the `key` argument after Get returns. The
	// returned slice will remain valid until the returned Closer is closed.
	// when err == nil, the caller MUST call closer.Close() or a memory leak will occur.
	Get(key []byte) (value []byte, closer io.Closer, err error)

	// NewIter returns a new Iterator for the given key prefix range [startPrefix, endPrefix], both inclusive.
	// We require that startPrefix ≤ endPrefix (otherwise this function errors).
	// Specifically, all keys that meet ANY of the following conditions are included in the iteration:
	//   - have a prefix equal to startPrefix OR
	//   - have a prefix equal to the endPrefix OR
	//   - have a prefix that is lexicographically between startPrefix and endPrefix
	NewIter(startPrefix, endPrefix []byte, ops IteratorOption) (Iterator, error)

	// NewSeeker returns a new Seeker.
	NewSeeker() Seeker
}

type ReaderBatchWriter interface {
	// GlobalReader returns a database-backed reader which reads the latest committed global database state ("read-committed isolation").
	// This reader will not read writes written to ReaderBatchWriter.Writer until the write batch is committed.
	// This reader may observe different values for the same key on subsequent reads.
	GlobalReader() Reader

	// Writer returns a writer associated with a batch of writes. The batch is pending until it is committed.
	// When we `Write` into the batch, that write operation is added to the pending batch, but not committed.
	// The commit operation is atomic w.r.t. the batch; either all writes are applied to the database, or no writes are.
	// Note:
	// - The writer cannot be used concurrently for writing.
	Writer() Writer

	// AddCallback adds a callback to execute after the batch has been flush
	// regardless the batch update is succeeded or failed.
	// The error parameter is the error returned by the batch update.
	AddCallback(func(error))

	// SetScopedValue stores the given value by the given key in this batch.
	// Value can be retrieved by the same key via ScopedValue(key).
	//
	// Saving data in ReaderBatchWriter can be useful when the store's operation
	// is called repeatedly with the same ReaderBatchWriter and different data
	// (e.g., block ID).  Aggregating different data (e.g., block ID) within
	// the same ReaderBatchWriter can help store's operation to perform batch
	// operation efficiently on commit success.
	//
	// For example, TransactionResults.BatchRemoveByBlockID() receives
	// ReaderBatchWriter and block ID to remove the given block from the
	// database and memory cache.  TransactionResults.BatchRemoveByBlockID()
	// can be called repeatedly with the same ReaderBatchWriter and different
	// block IDs to remove multiple blocks.  By saving all removed block IDs
	// with the same ReaderBatchWriter, TransactionResults.BatchRemoveByBlockID()
	// retrieves all block IDs and removes cached blocks by locking just once
	// in OnCommitSucceed() callback, instead of locking TransactionResults cache
	// for every removed block ID.
	SetScopedValue(key string, value any)

	// ScopedValue returns the value associated with this batch for the given key
	// and true if key exists, or nil and false if key doesn't exist.
	ScopedValue(key string) (any, bool)
}

type RegisterIndex interface {
	RegisterIndexReader

	// Store batch of register entries at the provided block height.
	//
	// The provided height must either be one higher than the current height or the same to ensure idempotency,
	// otherwise and error is returned. If the height is not within those bounds there is either a bug
	// or state corruption.
	//
	// No errors are expected during normal operation.
	Store(entries flow.RegisterEntries, height uint64) error
}

type RegisterIndexReader interface {
	// Get register by the register ID at a given block height.
	//
	// If the register at the given height was not indexed, returns the highest
	// height the register was indexed at.
	// Expected errors:
	// - storage.ErrHeightNotIndexed if the given height was not indexed yet or lower than the first indexed height.
	// - storage.ErrNotFound if the given height is indexed, but the register does not exist.
	Get(ID flow.RegisterID, height uint64) (flow.RegisterValue, error)

	// LatestHeight returns the latest indexed height.
	LatestHeight() uint64

	// FirstHeight at which we started to index. Returns the first indexed height found in the store.
	FirstHeight() uint64
}

type ResultApprovals interface {

	// StoreMyApproval returns a functor, whose execution
	//  - will store the given ResultApproval
	//  - and index it by result ID and chunk index.
	//  - requires storage.LockIndexResultApproval lock to be held by the caller
	// The functor's expected error returns during normal operation are:
	//  - `storage.ErrDataMismatch` if a *different* approval for the same key pair (ExecutionResultID, chunk index) is already indexed
	//
	// CAUTION: the Flow protocol requires multiple approvals for the same chunk from different verification
	// nodes. In other words, there are multiple different approvals for the same chunk. Therefore, the index
	// Executed Chunk ➜ ResultApproval ID (populated here) is *only safe* to be used by Verification Nodes
	// for tracking their own approvals.
	//
	// For the same ExecutionResult, a Verifier will always produce the same approval. Therefore, this operation
	// is idempotent, i.e. repeated calls with the *same inputs* are equivalent to just calling the method once;
	// still the method succeeds on each call. However, when attempting to index *different* ResultApproval IDs
	// for the same key (resultID, chunkIndex) this method returns an exception, as this should never happen for
	// a correct Verification Node indexing its own approvals.
	// It returns a functor so that some computation (such as computing approval ID) can be done
	// before acquiring the lock.
	StoreMyApproval(approval *flow.ResultApproval) func(lctx lockctx.Proof) error

	// ByID retrieves a ResultApproval by its ID.
	// Returns [storage.ErrNotFound] if no Approval with the given ID has been stored.
	ByID(approvalID flow.Identifier) (*flow.ResultApproval, error)

	// ByChunk retrieves a ResultApproval by result ID and chunk index.
	// Returns [storage.ErrNotFound] if no Approval for  the given key (resultID, chunkIndex) has been stored.
	ByChunk(resultID flow.Identifier, chunkIndex uint64) (*flow.ResultApproval, error)
}

type SafeBeaconKeys interface {

	// RetrieveMyBeaconPrivateKey retrieves my beacon private key for the given
	// epoch, only if my key has been confirmed valid and safe for use.
	//
	// Returns:
	//   - (key, true, nil) if the key is present and confirmed valid
	//   - (nil, false, nil) if the key has been marked invalid or unavailable
	//     -> no beacon key will ever be available for the epoch in this case
	//   - (nil, false, [storage.ErrNotFound]) if the DKG has not ended
	//   - (nil, false, error) for any unexpected exception
	RetrieveMyBeaconPrivateKey(epochCounter uint64) (key crypto.PrivateKey, safe bool, err error)
}

type ScheduledTransactions interface {
	ScheduledTransactionsReader

	// BatchIndex indexes the scheduled transaction by its block ID, transaction ID, and scheduled transaction ID.
	// `txID` is be the TransactionBody.ID of the scheduled transaction.
	// `scheduledTxID` is the uint64 id field returned by the system smart contract.
	// Requires the lock: [storage.LockIndexScheduledTransaction]
	//
	// Expected error returns during normal operation:
	//   - [storage.ErrAlreadyExists]: if the scheduled transaction is already indexed
	BatchIndex(lctx lockctx.Proof, blockID flow.Identifier, txID flow.Identifier, scheduledTxID uint64, batch ReaderBatchWriter) error
}

type ScheduledTransactionsReader interface {
	// TransactionIDByID returns the transaction ID of the scheduled transaction by its scheduled transaction ID.
	// Note: `scheduledTxID` is the uint64 id field returned by the system smart contract.
	//
	// Expected error returns during normal operation:
	//   - [storage.ErrNotFound]: if no transaction ID is found for the given scheduled transaction ID
	TransactionIDByID(scheduledTxID uint64) (flow.Identifier, error)

	// BlockIDByTransactionID returns the block ID in which the provided system transaction was executed.
	// `txID` is the TransactionBody.ID of the scheduled transaction.
	//
	// Expected error returns during normal operation:
	//   - [storage.ErrNotFound]: if no block ID is found for the given transaction ID
	BlockIDByTransactionID(txID flow.Identifier) (flow.Identifier, error)
}

type Seals interface {

	// Store inserts the seal.
	Store(seal *flow.Seal) error

	// ByID retrieves the seal by the collection
	// fingerprint.
	ByID(sealID flow.Identifier) (*flow.Seal, error)

	// HighestInFork retrieves the highest seal that was included in the
	// fork up to (and including) the given blockID.
	// This method should return
	//   - a seal for any block known to the node.
	//   - storage.ErrNotFound if blockID is unknown.
	HighestInFork(blockID flow.Identifier) (*flow.Seal, error)

	// FinalizedSealForBlock retrieves the finalized seal for the given block ID.
	// Returns storage.ErrNotFound if blockID is unknown or no _finalized_ seal
	// is known for the block.
	FinalizedSealForBlock(blockID flow.Identifier) (*flow.Seal, error)
}

type Seeker interface {
	// SeekLE (seek less than or equal) returns the largest key in lexicographical
	// order within inclusive range of [startPrefix, key].
	// This function returns an error if specified key is less than startPrefix.
	// This function returns storage.ErrNotFound if a key that matches
	// the specified criteria is not found.
	SeekLE(startPrefix, key []byte) ([]byte, error)
}

type ServiceEvents interface {
	// BatchStore stores service events keyed by a blockID in provided batch
	// No errors are expected during normal operation, even if no entries are matched.
	// If database unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	BatchStore(blockID flow.Identifier, events []flow.Event, batch ReaderBatchWriter) error

	// ByBlockID returns the events for the given block ID
	ByBlockID(blockID flow.Identifier) ([]flow.Event, error)

	// BatchRemoveByBlockID removes service events keyed by a blockID in provided batch
	// No errors are expected during normal operation, even if no entries are matched.
	// If database unexpectedly fails to process the request, the error is wrapped in a generic error and returned.
	BatchRemoveByBlockID(blockID flow.Identifier, batch ReaderBatchWriter) error
}

type StoredChunkDataPack struct {
	ChunkID           flow.Identifier
	StartState        flow.StateCommitment
	Proof             flow.StorageProof
	CollectionID      flow.Identifier // flow.ZeroID for system chunks
	ExecutionDataRoot flow.BlockExecutionDataRoot
}

type StoredChunkDataPacks interface {
	// StoreChunkDataPacks stores multiple StoredChunkDataPacks cs in a batch.
	// It returns the chunk data pack IDs
	// No error returns are expected during normal operation.
	StoreChunkDataPacks(cs []*StoredChunkDataPack) ([]flow.Identifier, error)

	// ByID returns the StoredChunkDataPack for the given ID.
	// It returns [storage.ErrNotFound] if no entry exists for the given ID.
	ByID(id flow.Identifier) (*StoredChunkDataPack, error)

	// Remove removes multiple ChunkDataPacks cs keyed by their IDs in a batch.
	// No error returns are expected during normal operation, even if none of the referenced objects exist in storage.
	Remove(chunkDataPackIDs []flow.Identifier) error

	// BatchRemove removes multiple ChunkDataPacks with the given IDs from storage as part of the provided write batch.
	// No error returns are expected during normal operation, even if no entries are matched.
	BatchRemove(chunkDataPackIDs []flow.Identifier, rw ReaderBatchWriter) error
}

type TransactionResultErrorMessages interface {
	TransactionResultErrorMessagesReader

	// Store persists and indexes all transaction result error messages for the given blockID. The caller must
	// acquire [storage.LockInsertTransactionResultErrMessage] and hold it until the write batch has been committed.
	// It returns [storage.ErrAlreadyExists] if tx result error messages for the block already exist.
	Store(lctx lockctx.Proof, blockID flow.Identifier, transactionResultErrorMessages []flow.TransactionResultErrorMessage) error

	// BatchStore persists and indexes all transaction result error messages for the given blockID as part
	// of the provided batch. The caller must acquire [storage.LockInsertTransactionResultErrMessage] and
	// hold it until the write batch has been committed.
	// It returns [storage.ErrAlreadyExists] if tx result error messages for the block already exist.
	BatchStore(lctx lockctx.Proof, rw ReaderBatchWriter, blockID flow.Identifier, transactionResultErrorMessages []flow.TransactionResultErrorMessage) error
}

type TransactionResultErrorMessagesReader interface {
	// Exists returns true if transaction result error messages for the given ID have been stored.
	//
	// Note that transaction error messages are auxiliary data provided by the Execution Nodes on a goodwill basis and
	// not protected by the protocol. Execution Error messages might be non-deterministic, i.e. potentially different
	// for different execution nodes.
	//
	// No errors are expected during normal operation.
	Exists(blockID flow.Identifier) (bool, error)

	// ByBlockIDTransactionID returns the transaction result error message for the given block ID and transaction ID.
	//
	// Note that transaction error messages are auxiliary data provided by the Execution Nodes on a goodwill basis and
	// not protected by the protocol. Execution Error messages might be non-deterministic, i.e. potentially different
	// for different execution nodes.
	//
	// Expected errors during normal operation:
	//   - [storage.ErrNotFound] if no transaction error message is known at given block and transaction id.
	ByBlockIDTransactionID(blockID flow.Identifier, transactionID flow.Identifier) (*flow.TransactionResultErrorMessage, error)

	// ByBlockIDTransactionIndex returns the transaction result error message for the given blockID and transaction index.
	//
	// Note that transaction error messages are auxiliary data provided by the Execution Nodes on a goodwill basis and
	// not protected by the protocol. Execution Error messages might be non-deterministic, i.e. potentially different
	// for different execution nodes.
	//
	// Expected errors during normal operation:
	//   - [storage.ErrNotFound] if no transaction error message is known at given block and transaction index.
	ByBlockIDTransactionIndex(blockID flow.Identifier, txIndex uint32) (*flow.TransactionResultErrorMessage, error)

	// ByBlockID gets all transaction result error messages for a block, ordered by transaction index.
	// CAUTION: This method will return an empty slice both if the block is not indexed yet and if the block does not have any errors.
	//
	// Note that transaction error messages are auxiliary data provided by the Execution Nodes on a goodwill basis and
	// not protected by the protocol. Execution Error messages might be non-deterministic, i.e. potentially different
	// for different execution nodes.
	//
	// No errors are expected during normal operations.
	ByBlockID(id flow.Identifier) ([]flow.TransactionResultErrorMessage, error)
}

type TransactionResults interface {
	TransactionResultsReader

	// BatchStore inserts a batch of transaction result into a batch
	BatchStore(blockID flow.Identifier, transactionResults []flow.TransactionResult, batch ReaderBatchWriter) error

	// RemoveByBlockID removes all transaction results for a block
	BatchRemoveByBlockID(id flow.Identifier, batch ReaderBatchWriter) error
}

type TransactionResultsReader interface {
	// ByBlockIDTransactionID returns the transaction result for the given block ID and transaction ID
	ByBlockIDTransactionID(blockID flow.Identifier, transactionID flow.Identifier) (*flow.TransactionResult, error)

	// ByBlockIDTransactionIndex returns the transaction result for the given blockID and transaction index
	ByBlockIDTransactionIndex(blockID flow.Identifier, txIndex uint32) (*flow.TransactionResult, error)

	// ByBlockID gets all transaction results for a block, ordered by transaction index
	ByBlockID(id flow.Identifier) ([]flow.TransactionResult, error)
}

type Transactions interface {
	TransactionsReader

	// Store inserts the transaction, keyed by fingerprint. Duplicate transaction insertion is ignored
	// No errors are expected during normal operation.
	Store(tx *flow.TransactionBody) error

	// BatchStore stores transaction within a batch operation.
	// No errors are expected during normal operation.
	BatchStore(tx *flow.TransactionBody, batch ReaderBatchWriter) error
}

type TransactionsReader interface {
	// ByID returns the transaction for the given fingerprint.
	// Expected errors during normal operation:
	//   - `storage.ErrNotFound` if transaction is not found.
	ByID(txID flow.Identifier) (*flow.TransactionBody, error)
}

type VersionBeacons interface {

	// Highest finds the highest flow.SealedVersionBeacon but no higher than
	// belowOrEqualTo
	// Returns nil if no version beacon has been sealed below or equal to the
	// input height.
	Highest(belowOrEqualTo uint64) (*flow.SealedVersionBeacon, error)
}

type Writer interface {
	// Set sets the value for the given key. It overwrites any previous value
	// for that key; a DB is not a multi-map.
	//
	// It is safe to modify the contents of the arguments after Set returns.
	// No errors expected during normal operation
	Set(k, v []byte) error

	// Delete deletes the value for the given key. Deletes are blind all will
	// succeed even if the given key does not exist.
	//
	// It is safe to modify the contents of the arguments after Delete returns.
	// No errors expected during normal operation
	Delete(key []byte) error

	// DeleteByRange removes all keys with a prefix that falls within the
	// range [start, end], both inclusive.
	// No errors expected during normal operation
	DeleteByRange(globalReader Reader, startPrefix, endPrefix []byte) error
}