execution

type BlockAttestationResult struct {
	*BlockExecutionResult

	// TODO(ramtin): move this to the outside, everything needed for create this
	// should be available as part of computation result and most likely trieUpdate
	// was the reason this is kept here, long term we don't need this data and should
	// act based on register deltas
	*execution_data.BlockExecutionData
	// contains filtered or unexported fields
}

type BlockExecutionResult struct {
	*entity.ExecutableBlock

	ExecutionDataRoot *flow.BlockExecutionDataRoot // full root data structure produced from block
	// contains filtered or unexported fields
}

type CollectionAttestationResult struct {
	// contains filtered or unexported fields
}

type CollectionExecutionResult struct {
	// contains filtered or unexported fields
}

type ComputationResult struct {
	*BlockExecutionResult
	*BlockAttestationResult

	ExecutionReceipt *flow.ExecutionReceipt
}

type ExecutedFinalizedWAL interface {
	Append(height uint64, registers flow.RegisterEntries) error

	// Latest returns the latest height in the WAL.
	Latest() (uint64, error)

	GetReader(height uint64) WALReader
}

type ExtendableStorageSnapshot interface {
	snapshot.StorageSnapshot
	Extend(newCommit flow.StateCommitment, updatedRegisters map[flow.RegisterID]flow.RegisterValue) ExtendableStorageSnapshot
	Commitment() flow.StateCommitment
}

type FinalizedReader interface {
	// FinalizedBlockIDAtHeight returns the block ID of the finalized block at the given height.
	// It return storage.NotFound if the given height has not been finalized yet
	// any other error returned are exceptions
	FinalizedBlockIDAtHeight(height uint64) (flow.Identifier, error)
}

type InMemoryRegisterStore interface {
	Prune(finalizedHeight uint64, finalizedBlockID flow.Identifier) error
	PrunedHeight() uint64

	// GetRegister will return the latest updated value of the given register since the pruned height.
	// It returns ErrPruned if the register is unknown or not updated since the pruned height
	// It returns exception if internal index is inconsistent
	GetRegister(height uint64, blockID flow.Identifier, register flow.RegisterID) (flow.RegisterValue, error)
	GetUpdatedRegisters(height uint64, blockID flow.Identifier) (flow.RegisterEntries, error)
	SaveRegisters(
		height uint64,
		blockID flow.Identifier,
		parentID flow.Identifier,
		registers flow.RegisterEntries,
	) error

	// IsBlockExecuted returns wheather the given block is executed.
	// It returns:
	// - (true, nil) if the block is above the pruned height and is executed
	// - (true, nil) if the block is the pruned block, since the prunded block are finalized and executed
	// - (false, nil) if the block is above the pruned height and is not executed
	// - (false, nil) if the block's height is the pruned height, but is different from the pruned block
	// - (false, exception) if the block is below the pruned height
	IsBlockExecuted(height uint64, blockID flow.Identifier) (bool, error)
}

type OnDiskRegisterStore = storage.RegisterIndex

type RegisterStore interface {
	// GetRegister first try to get the register from InMemoryRegisterStore, then OnDiskRegisterStore
	// It returns:
	//  - (value, nil) if the register value is found at the given block
	//  - (nil, nil) if the register is not found
	//  - (nil, storage.ErrHeightNotIndexed) if the height is below the first height that is indexed.
	//  - (nil, storehouse.ErrNotExecuted) if the block is not executed yet
	//  - (nil, storehouse.ErrNotExecuted) if the block is conflicting iwth finalized block
	//  - (nil, err) for any other exceptions
	GetRegister(height uint64, blockID flow.Identifier, register flow.RegisterID) (flow.RegisterValue, error)

	// SaveRegisters saves to InMemoryRegisterStore first, then trigger the same check as OnBlockFinalized
	// Depend on InMemoryRegisterStore.SaveRegisters
	// It returns:
	// - nil if the registers are saved successfully
	// - exception is the block is above the pruned height but does not connect to the pruned height (conflicting block).
	// - exception if the block is below the pruned height
	// - exception if the save block is saved again
	// - exception for any other exception
	SaveRegisters(header *flow.Header, registers flow.RegisterEntries) error

	// Depend on FinalizedReader's FinalizedBlockIDAtHeight
	// Depend on ExecutedFinalizedWAL.Append
	// Depend on OnDiskRegisterStore.SaveRegisters
	// OnBlockFinalized trigger the check of whether a block at the next height becomes finalized and executed.
	// Note: This is a blocking call
	// the next height is the existing finalized and executed block's height + 1.
	// If a block at next height becomes finalized and executed, then:
	// 1. write the registers to write ahead logs
	// 2. save the registers of the block to OnDiskRegisterStore
	// 3. prune the height in InMemoryRegisterStore
	// any error returned are exception
	OnBlockFinalized() error

	// LastFinalizedAndExecutedHeight returns the height of the last finalized and executed block,
	// which has been saved in OnDiskRegisterStore
	LastFinalizedAndExecutedHeight() uint64

	// IsBlockExecuted returns whether the given block is executed.
	// If a block is not executed, it does not distinguish whether the block exists or not.
	// It returns:
	// - (true, nil) if the block is executed, regardless of whether the registers of the block is pruned on disk or not
	// - (false, nil) if the block is not executed
	// - (false, exception) if running into any exception
	IsBlockExecuted(height uint64, blockID flow.Identifier) (bool, error)
}

type RegisterStoreNotifier interface {
	OnFinalizedAndExecutedHeightUpdated(height uint64)
}

type ScriptExecutor interface {

	// ExecuteScriptAtBlockID executes a script at the given Block id
	// it returns the value, the computation used and the error (if any)
	ExecuteScriptAtBlockID(ctx context.Context, script []byte, arguments [][]byte, blockID flow.Identifier) ([]byte, uint64, error)

	// GetAccount returns the Account details at the given Block id
	GetAccount(ctx context.Context, address flow.Address, blockID flow.Identifier) (*flow.Account, error)

	// GetRegisterAtBlockID returns the value of a register at the given Block id (if available)
	GetRegisterAtBlockID(ctx context.Context, owner, key []byte, blockID flow.Identifier) ([]byte, error)
}

type WALReader interface {
	// Next returns the next height and trie updates in the WAL.
	// It returns EOF when there are no more entries.
	Next() (height uint64, registers flow.RegisterEntries, err error)
}