module

type AccessMetrics interface {
	// TotalConnectionsInPool updates the number connections to collection/execution nodes stored in the pool, and the size of the pool
	TotalConnectionsInPool(connectionCount uint, connectionPoolSize uint)

	// ConnectionFromPoolReused tracks the number of times a connection to a collection/execution node is reused from the connection pool
	ConnectionFromPoolReused()

	// ConnectionAddedToPool tracks the number of times a collection/execution node is added to the connection pool
	ConnectionAddedToPool()

	// NewConnectionEstablished tracks the number of times a new grpc connection is established
	NewConnectionEstablished()

	// ConnectionFromPoolInvalidated tracks the number of times a cached grpc connection is invalidated and closed
	ConnectionFromPoolInvalidated()

	// ConnectionFromPoolUpdated tracks the number of times a cached connection is updated
	ConnectionFromPoolUpdated()

	// ConnectionFromPoolEvicted tracks the number of times a cached connection is evicted from the cache
	ConnectionFromPoolEvicted()
}

type BackendScriptsMetrics interface {
	// Record the round trip time while executing a script
	ScriptExecuted(dur time.Duration, size int)
}

type BitswapMetrics interface {
	Peers(prefix string, n int)
	Wantlist(prefix string, n int)
	BlobsReceived(prefix string, n uint64)
	DataReceived(prefix string, n uint64)
	BlobsSent(prefix string, n uint64)
	DataSent(prefix string, n uint64)
	DupBlobsReceived(prefix string, n uint64)
	DupDataReceived(prefix string, n uint64)
	MessagesReceived(prefix string, n uint64)
}

type BlockRequester interface {

	// RequestBlock indicates that the given block should be queued for retrieval.
	RequestBlock(blockID flow.Identifier, height uint64)

	// RequestHeight indicates that the given block height should be queued for retrieval.
	RequestHeight(height uint64)

	// Manually Prune requests
	Prune(final *flow.Header)
}

type Builder interface {

	// BuildOn generates a new payload that is valid with respect to the parent
	// being built upon, with the view being provided by the consensus algorithm.
	// The builder stores the block and validates it against the protocol state
	// before returning it.
	//
	// NOTE: Since the block is stored within Builder, HotStuff MUST propose the
	// block once BuildOn succcessfully returns.
	BuildOn(parentID flow.Identifier, setter func(*flow.Header) error) (*flow.Header, error)
}

type CacheMetrics interface {
	// CacheEntries report the total number of cached items
	CacheEntries(resource string, entries uint)
	// CacheHit report the number of times the queried item is found in the cache
	CacheHit(resource string)
	// CacheNotFound records the number of times the queried item was not found in either cache or database.
	CacheNotFound(resource string)
	// CacheMiss report the number of times the queried item is not found in the cache, but found in the database.
	CacheMiss(resource string)
}

type ChainSyncMetrics interface {
	// record pruned blocks. requested and received times might be zero values
	PrunedBlockById(status *chainsync.Status)

	PrunedBlockByHeight(status *chainsync.Status)

	// totalByHeight and totalById are the number of blocks pruned for blocks requested by height and by id
	// storedByHeight and storedById are the number of blocks still stored by height and id
	PrunedBlocks(totalByHeight, totalById, storedByHeight, storedById int)

	RangeRequested(ran chainsync.Range)

	BatchRequested(batch chainsync.Batch)
}

type ChunkAssigner interface {
	// Assign generates the assignment
	// error returns:
	//  * NoValidChildBlockError indicates that no valid child block is known
	//    (which contains the block's source of randomness)
	//  * unexpected errors should be considered symptoms of internal bugs
	Assign(result *flow.ExecutionResult, blockID flow.Identifier) (*chmodels.Assignment, error)
}

type ChunkVerifier interface {
	// Verify verifies the given VerifiableChunk by executing it and checking
	// the final state commitment.
	// It returns a Spock Secret as a byte array, verification fault of the
	// chunk, and an error.
	Verify(
		ch *verification.VerifiableChunkData,
	) (
		[]byte,
		chmodels.ChunkFault,
		error,
	)
}

type CleanerMetrics interface {
	RanGC(took time.Duration)
}

type ClusterRootQCVoter interface {

	// Vote handles the full procedure of generating a vote, submitting it to the
	// epoch smart contract, and verifying submission. Returns an error only if
	// there is a critical error that would make it impossible for the vote to be
	// submitted. Otherwise, exits when the vote has been successfully submitted.
	//
	// It is safe to run Vote multiple times within a single setup phase.
	Vote(context.Context, protocol.Epoch) error
}

type CollectionMetrics interface {
	// TransactionIngested is called when a new transaction is ingested by the
	// node. It increments the total count of ingested transactions and starts
	// a tx->col span for the transaction.
	TransactionIngested(txID flow.Identifier)

	// ClusterBlockProposed is called when a new collection is proposed by us or
	// any other node in the cluster.
	ClusterBlockProposed(block *cluster.Block)

	// ClusterBlockFinalized is called when a collection is finalized.
	ClusterBlockFinalized(block *cluster.Block)
}

type ComplianceMetrics interface {
	FinalizedHeight(height uint64)
	CommittedEpochFinalView(view uint64)
	SealedHeight(height uint64)
	BlockFinalized(*flow.Block)
	BlockSealed(*flow.Block)
	BlockProposalDuration(duration time.Duration)
	CurrentEpochCounter(counter uint64)
	CurrentEpochPhase(phase flow.EpochPhase)
	CurrentEpochFinalView(view uint64)
	CurrentDKGPhase1FinalView(view uint64)
	CurrentDKGPhase2FinalView(view uint64)
	CurrentDKGPhase3FinalView(view uint64)
	EpochEmergencyFallbackTriggered()
}

type ConsensusMetrics interface {
	// StartCollectionToFinalized reports Metrics C1: Collection Received by CCL→ Collection Included in Finalized Block
	StartCollectionToFinalized(collectionID flow.Identifier)

	// FinishCollectionToFinalized reports Metrics C1: Collection Received by CCL→ Collection Included in Finalized Block
	FinishCollectionToFinalized(collectionID flow.Identifier)

	// StartBlockToSeal reports Metrics C4: Block Received by CCL → Block Seal in finalized block
	StartBlockToSeal(blockID flow.Identifier)

	// FinishBlockToSeal reports Metrics C4: Block Received by CCL → Block Seal in finalized block
	FinishBlockToSeal(blockID flow.Identifier)

	// EmergencySeal increments the number of seals that were created in emergency mode
	EmergencySeal()

	// OnReceiptProcessingDuration records the number of seconds spent processing a receipt
	OnReceiptProcessingDuration(duration time.Duration)

	// OnApprovalProcessingDuration records the number of seconds spent processing an approval
	OnApprovalProcessingDuration(duration time.Duration)

	// CheckSealingDuration records absolute time for the full sealing check by the consensus match engine
	CheckSealingDuration(duration time.Duration)
}

type DHTMetrics interface {
	RoutingTablePeerAdded()
	RoutingTablePeerRemoved()
}

type DKGContractClient interface {

	// Broadcast broadcasts a message to all other nodes participating in the
	// DKG. The message is broadcast by submitting a transaction to the DKG
	// smart contract. An error is returned if the transaction has failed has
	// failed.
	// TBD: retry logic
	Broadcast(msg messages.BroadcastDKGMessage) error

	// ReadBroadcast reads the broadcast messages from the smart contract.
	// Messages are returned in the order in which they were broadcast (received
	// and stored in the smart contract). The parameters are:
	//
	// * fromIndex: return messages with index >= fromIndex
	// * referenceBlock: a marker for the state against which the query should
	//   be executed
	//
	// DKG nodes should call ReadBroadcast one final time once they have
	// observed the phase deadline trigger to guarantee they receive all
	// messages for that phase.
	ReadBroadcast(fromIndex uint, referenceBlock flow.Identifier) ([]messages.BroadcastDKGMessage, error)

	// SubmitResult submits the final public result of the DKG protocol. This
	// represents the group public key and the node's local computation of the
	// public keys for each DKG participant.
	//
	// SubmitResult must be called strictly after the final phase has ended.
	SubmitResult(crypto.PublicKey, []crypto.PublicKey) error
}

type DKGController interface {

	// Run starts the DKG controller and starts phase 1. It is a blocking call
	// that blocks until the controller is shutdown or until an error is
	// encountered in one of the protocol phases.
	Run() error

	// EndPhase1 notifies the controller to end phase 1, and start phase 2.
	EndPhase1() error

	// EndPhase2 notifies the controller to end phase 2, and start phase 3.
	EndPhase2() error

	// End terminates the DKG state machine and records the artifacts.
	End() error

	// Shutdown stops the controller regardless of the current state.
	Shutdown()

	// Poll instructs the controller to actively fetch broadcast messages (ex.
	// read from DKG smart contract). The method does not return until all
	// received messages are processed.
	Poll(blockReference flow.Identifier) error

	// GetArtifacts returns our node's private key share, the group public key,
	// and the list of all nodes' public keys (including ours), as computed by
	// the DKG.
	GetArtifacts() (crypto.PrivateKey, crypto.PublicKey, []crypto.PublicKey)

	// GetIndex returns the index of this node in the DKG committee list.
	GetIndex() int

	// SubmitResult instructs the broker to publish the results of the DKG run
	// (ex. publish to DKG smart contract).
	SubmitResult() error
}

type DKGControllerFactory interface {

	// Create instantiates a new DKGController.
	Create(dkgInstanceID string, participants flow.IdentityList, seed []byte) (DKGController, error)
}

type EngineMetrics interface {
	MessageSent(engine string, message string)
	MessageReceived(engine string, message string)
	MessageHandled(engine string, messages string)
}

type EntriesFunc func() uint

type EpochLookup interface {

	// EpochForView returns the counter of the epoch that the view belongs to.
	EpochForView(view uint64) (epochCounter uint64, err error)

	// EpochForViewWithFallback returns the counter of the epoch that the view belongs to.
	EpochForViewWithFallback(view uint64) (epochCounter uint64, err error)
}

type ExecutionDataProviderMetrics interface {
	RootIDComputed(duration time.Duration, numberOfChunks int)
	AddBlobsSucceeded(duration time.Duration, totalSize uint64)
	AddBlobsFailed()
}

type ExecutionDataPrunerMetrics interface {
	Pruned(height uint64, duration time.Duration)
}

type ExecutionDataRequesterMetrics interface {
	// ExecutionDataFetchStarted records an in-progress download
	ExecutionDataFetchStarted()

	// ExecutionDataFetchFinished records a completed download
	ExecutionDataFetchFinished(duration time.Duration, success bool, height uint64)

	// NotificationSent reports that ExecutionData received notifications were sent for a block height
	NotificationSent(height uint64)

	// FetchRetried reports that a download retry was processed
	FetchRetried()
}

type ExecutionDataRequesterV2Metrics interface {
	FulfilledHeight(blockHeight uint64)
	ReceiptSkipped()
	RequestSucceeded(blockHeight uint64, duration time.Duration, totalSize uint64, numberOfAttempts int)
	RequestFailed(duration time.Duration, retryable bool)
	RequestCanceled()
	ResponseDropped()
}

type ExecutionMetrics interface {
	LedgerMetrics
	RuntimeMetrics
	ProviderMetrics
	WALMetrics

	// StartBlockReceivedToExecuted starts a span to trace the duration of a block
	// from being received for execution to execution being finished
	StartBlockReceivedToExecuted(blockID flow.Identifier)

	// FinishBlockReceivedToExecuted finishes a span to trace the duration of a block
	// from being received for execution to execution being finished
	FinishBlockReceivedToExecuted(blockID flow.Identifier)

	// ExecutionStorageStateCommitment reports the storage size of a state commitment in bytes
	ExecutionStorageStateCommitment(bytes int64)

	// ExecutionLastExecutedBlockHeight reports last executed block height
	ExecutionLastExecutedBlockHeight(height uint64)

	// ExecutionBlockExecuted reports the total time and computation spent on executing a block
	ExecutionBlockExecuted(dur time.Duration, stats ExecutionResultStats)

	// ExecutionBlockExecutionEffortVectorComponent reports the unweighted effort of given ComputationKind at block level
	ExecutionBlockExecutionEffortVectorComponent(string, uint)

	// ExecutionCollectionExecuted reports the total time and computation spent on executing a collection
	ExecutionCollectionExecuted(dur time.Duration, stats ExecutionResultStats)

	// ExecutionTransactionExecuted reports stats on executing a single transaction
	ExecutionTransactionExecuted(dur time.Duration,
		compUsed, memoryUsed, actualMemoryUsed uint64,
		eventCounts, eventSize int,
		failed bool)

	// ExecutionChunkDataPackGenerated reports stats on chunk data pack generation
	ExecutionChunkDataPackGenerated(proofSize, numberOfTransactions int)

	// ExecutionScriptExecuted reports the time and memory spent on executing an script
	ExecutionScriptExecuted(dur time.Duration, compUsed, memoryUsed, memoryEstimate uint64)

	// ExecutionCollectionRequestSent reports when a request for a collection is sent to a collection node
	ExecutionCollectionRequestSent()

	// Unused
	ExecutionCollectionRequestRetried()

	// ExecutionSync reports when the state syncing is triggered or stopped.
	ExecutionSync(syncing bool)

	// Upload metrics
	ExecutionBlockDataUploadStarted()
	ExecutionBlockDataUploadFinished(dur time.Duration)
	ExecutionComputationResultUploaded()
	ExecutionComputationResultUploadRetried()

	UpdateCollectionMaxHeight(height uint64)
}

type ExecutionResultStats struct {
	ComputationUsed                 uint64
	MemoryUsed                      uint64
	EventCounts                     int
	EventSize                       int
	NumberOfRegistersTouched        int
	NumberOfBytesWrittenToRegisters int
	NumberOfCollections             int
	NumberOfTransactions            int
}

type Finalizer interface {

	// MakeValid will mark a block as having passed the consensus algorithm's
	// internal validation.
	MakeValid(blockID flow.Identifier) error

	// MakeFinal will declare a block and all of its ancestors as finalized, which
	// makes it an immutable part of the blockchain. Returning an error indicates
	// some fatal condition and will cause the finalization logic to terminate.
	MakeFinal(blockID flow.Identifier) error
}

type GossipSubRouterMetrics interface {
	// OnIncomingRpcAcceptedFully tracks the number of RPC messages received by the node that are fully accepted.
	// An RPC may contain any number of control messages, i.e., IHAVE, IWANT, GRAFT, PRUNE, as well as the actual messages.
	// A fully accepted RPC means that all the control messages are accepted and all the messages are accepted.
	OnIncomingRpcAcceptedFully()

	// OnIncomingRpcAcceptedOnlyForControlMessages tracks the number of RPC messages received by the node that are accepted
	// only for the control messages, i.e., only for the included IHAVE, IWANT, GRAFT, PRUNE. However, the actual messages
	// included in the RPC are not accepted.
	// This happens mostly when the validation pipeline of GossipSub is throttled, and cannot accept more actual messages for
	// validation.
	OnIncomingRpcAcceptedOnlyForControlMessages()

	// OnIncomingRpcRejected tracks the number of RPC messages received by the node that are rejected.
	// This happens mostly when the RPC is coming from a low-scored peer based on the peer scoring module of GossipSub.
	OnIncomingRpcRejected()

	// OnIWantReceived tracks the number of IWANT messages received by the node from other nodes over an RPC message.
	// iWant is a control message that is sent by a node to request a message that it has seen advertised in an iHAVE message.
	OnIWantReceived(count int)

	// OnIHaveReceived tracks the number of IHAVE messages received by the node from other nodes over an RPC message.
	// iHave is a control message that is sent by a node to another node to indicate that it has a new gossiped message.
	OnIHaveReceived(count int)

	// OnGraftReceived tracks the number of GRAFT messages received by the node from other nodes over an RPC message.
	// GRAFT is a control message of GossipSub protocol that connects two nodes over a topic directly as gossip partners.
	OnGraftReceived(count int)

	// OnPruneReceived tracks the number of PRUNE messages received by the node from other nodes over an RPC message.
	// PRUNE is a control message of GossipSub protocol that disconnects two nodes over a topic.
	OnPruneReceived(count int)

	// OnPublishedGossipMessagesReceived tracks the number of gossip messages received by the node from other nodes over an
	// RPC message.
	OnPublishedGossipMessagesReceived(count int)
}

type HeroCacheMetrics interface {
	// BucketAvailableSlots keeps track of number of available slots in buckets of cache.
	BucketAvailableSlots(uint64, uint64)

	// OnKeyPutAttempt is called whenever a new (key, value) pair is attempted to be put in cache.
	// It does not reflect whether the put was successful or not.
	// A (key, value) pair put attempt may fail if the cache is full, or the key already exists.
	OnKeyPutAttempt(size uint32)

	// OnKeyPutSuccess is called whenever a new (key, entity) pair is successfully added to the cache.
	OnKeyPutSuccess(size uint32)

	// OnKeyPutDrop is called whenever a new (key, entity) pair is dropped from the cache due to full cache.
	OnKeyPutDrop()

	// OnKeyPutDeduplicated is tracking the total number of unsuccessful writes caused by adding a duplicate key to the cache.
	// A duplicate key is dropped by the cache when it is written to the cache.
	// Note: in context of HeroCache, the key corresponds to the identifier of its entity. Hence, a duplicate key corresponds to
	// a duplicate entity.
	OnKeyPutDeduplicated()

	// OnKeyRemoved is called whenever a (key, entity) pair is removed from the cache.
	OnKeyRemoved(size uint32)

	// OnKeyGetSuccess tracks total number of successful read queries.
	// A read query is successful if the entity corresponding to its key is available in the cache.
	// Note: in context of HeroCache, the key corresponds to the identifier of its entity.
	OnKeyGetSuccess()

	// OnKeyGetFailure tracks total number of unsuccessful read queries.
	// A read query is unsuccessful if the entity corresponding to its key is not available in the cache.
	// Note: in context of HeroCache, the key corresponds to the identifier of its entity.
	OnKeyGetFailure()

	// OnEntityEjectionDueToFullCapacity is called whenever adding a new (key, entity) to the cache results in ejection of another (key', entity') pair.
	// This normally happens -- and is expected -- when the cache is full.
	// Note: in context of HeroCache, the key corresponds to the identifier of its entity.
	OnEntityEjectionDueToFullCapacity()

	// OnEntityEjectionDueToEmergency is called whenever a bucket is found full and all of its keys are valid, i.e.,
	// each key belongs to an existing (key, entity) pair.
	// Hence, adding a new key to that bucket will replace the oldest valid key inside that bucket.
	// Note: in context of HeroCache, the key corresponds to the identifier of its entity.
	OnEntityEjectionDueToEmergency()
}

type HotStuff interface {
	ReadyDoneAware
	Startable

	// SubmitProposal submits a new block proposal to the HotStuff event loop.
	// This method blocks until the proposal is accepted to the event queue.
	//
	// Block proposals must be submitted in order and only if they extend a
	// block already known to HotStuff core.
	SubmitProposal(proposal *flow.Header, parentView uint64) (done <-chan struct{})
}

type HotStuffFollower interface {
	ReadyDoneAware

	// SubmitProposal feeds a new block proposal into the HotStuffFollower.
	// This method blocks until the proposal is accepted to the event queue.
	//
	// Block proposals must be submitted in order, i.e. a proposal's parent must
	// have been previously processed by the HotStuffFollower.
	SubmitProposal(proposal *flow.Header, parentView uint64) (done <-chan struct{})
}

type HotstuffMetrics interface {
	// HotStuffBusyDuration reports Metrics C6 HotStuff Busy Duration
	HotStuffBusyDuration(duration time.Duration, event string)

	// HotStuffIdleDuration reports Metrics C6 HotStuff Idle Duration
	HotStuffIdleDuration(duration time.Duration)

	// HotStuffWaitDuration reports Metrics C6 HotStuff Idle Duration
	HotStuffWaitDuration(duration time.Duration, event string)

	// SetCurView reports Metrics C8: Current View
	SetCurView(view uint64)

	// SetQCView reports Metrics C9: View of Newest Known QC
	SetQCView(view uint64)

	// CountSkipped reports the number of times we skipped ahead.
	CountSkipped()

	// CountTimeout reports the number of times we timed out.
	CountTimeout()

	// SetTimeout sets the current timeout duration
	SetTimeout(duration time.Duration)

	// CommitteeProcessingDuration measures the time which the HotStuff's core logic
	// spends in the hotstuff.Committee component, i.e. the time determining consensus
	// committee relations.
	CommitteeProcessingDuration(duration time.Duration)

	// SignerProcessingDuration measures the time which the HotStuff's core logic
	// spends in the hotstuff.Signer component, i.e. the with crypto-related operations.
	SignerProcessingDuration(duration time.Duration)

	// ValidatorProcessingDuration measures the time which the HotStuff's core logic
	// spends in the hotstuff.Validator component, i.e. the with verifying
	// consensus messages.
	ValidatorProcessingDuration(duration time.Duration)

	// PayloadProductionDuration measures the time which the HotStuff's core logic
	// spends in the module.Builder component, i.e. the with generating block payloads.
	PayloadProductionDuration(duration time.Duration)
}

type IdentifierProvider interface {
	Identifiers() flow.IdentifierList
}

type IdentityProvider interface {
	// Identities returns the full identities of _all_ nodes currently known to the
	// protocol that pass the provided filter. Caution, this includes ejected nodes.
	// Please check the `Ejected` flag in the identities (or provide a filter for
	// removing ejected nodes).
	Identities(flow.IdentityFilter) flow.IdentityList

	// ByNodeID returns the full identity for the node with the given Identifier,
	// where Identifier is the way the protocol refers to the node. The function
	// has the same semantics as a map lookup, where the boolean return value is
	// true if and only if Identity has been found, i.e. `Identity` is not nil.
	// Caution: function returns include ejected nodes. Please check the `Ejected`
	// flag in the identity.
	ByNodeID(flow.Identifier) (*flow.Identity, bool)

	// ByPeerID returns the full identity for the node with the given peer ID,
	// where ID is the way the libP2P refers to the node. The function
	// has the same semantics as a map lookup, where the boolean return value is
	// true if and only if Identity has been found, i.e. `Identity` is not nil.
	// Caution: function returns include ejected nodes. Please check the `Ejected`
	// flag in the identity.
	ByPeerID(peer.ID) (*flow.Identity, bool)
}

type Job interface {
	// each job has a unique ID for deduplication
	ID() JobID
}

type JobConsumer interface {
	NewJobListener

	// Start starts processing jobs from a job queue. If this is the first time, a processed index
	// will be initialized in the storage. If it fails to initialize, an error will be returned
	Start(defaultIndex uint64) error

	// Stop gracefully stops the consumer from reading new jobs from the job queue. It does not stop
	// the existing worker finishing their jobs
	// It blocks until the existing worker finish processing the job
	Stop()

	// LastProcessedIndex returns the last processed job index
	LastProcessedIndex() uint64

	// NotifyJobIsDone let the consumer know a job has been finished, so that consumer will take
	// the next job from the job queue if there are workers available. It returns the last processed job index.
	NotifyJobIsDone(JobID) uint64

	// Size returns the number of processing jobs in consumer.
	Size() uint
}

type JobID string

type JobQueue interface {
	// Add a job to the job queue
	Add(job Job) error
}

type Jobs interface {
	// AtIndex returns the job at the given index.
	// Error returns:
	//   * storage.ErrNotFound if a job at the provided index is not available
	AtIndex(index uint64) (Job, error)

	// Head returns the index of the last job
	Head() (uint64, error)
}

type LedgerMetrics interface {
	// ForestApproxMemorySize records approximate memory usage of forest (all in-memory trees)
	ForestApproxMemorySize(bytes uint64)

	// ForestNumberOfTrees current number of trees in a forest (in memory)
	ForestNumberOfTrees(number uint64)

	// LatestTrieRegCount records the number of unique register allocated (the latest created trie)
	LatestTrieRegCount(number uint64)

	// LatestTrieRegCountDiff records the difference between the number of unique register allocated of the latest created trie and parent trie
	LatestTrieRegCountDiff(number int64)

	// LatestTrieRegSize records the size of unique register allocated (the latest created trie)
	LatestTrieRegSize(size uint64)

	// LatestTrieRegSizeDiff records the difference between the size of unique register allocated of the latest created trie and parent trie
	LatestTrieRegSizeDiff(size int64)

	// LatestTrieMaxDepthTouched records the maximum depth touched of the lastest created trie
	LatestTrieMaxDepthTouched(maxDepth uint16)

	// UpdateCount increase a counter of performed updates
	UpdateCount()

	// ProofSize records a proof size
	ProofSize(bytes uint32)

	// UpdateValuesNumber accumulates number of updated values
	UpdateValuesNumber(number uint64)

	// UpdateValuesSize total size (in bytes) of updates values
	UpdateValuesSize(byte uint64)

	// UpdateDuration records absolute time for the update of a trie
	UpdateDuration(duration time.Duration)

	// UpdateDurationPerItem records update time for single value (total duration / number of updated values)
	UpdateDurationPerItem(duration time.Duration)

	// ReadValuesNumber accumulates number of read values
	ReadValuesNumber(number uint64)

	// ReadValuesSize total size (in bytes) of read values
	ReadValuesSize(byte uint64)

	// ReadDuration records absolute time for the read from a trie
	ReadDuration(duration time.Duration)

	// ReadDurationPerItem records read time for single value (total duration / number of read values)
	ReadDurationPerItem(duration time.Duration)
}

type LibP2PConnectionMetrics interface {
	// OutboundConnections updates the metric tracking the number of outbound connections of this node
	OutboundConnections(connectionCount uint)

	// InboundConnections updates the metric tracking the number of inbound connections of this node
	InboundConnections(connectionCount uint)
}

type LibP2PMetrics interface {
	GossipSubRouterMetrics
	ResolverMetrics
	DHTMetrics
	rcmgr.MetricsReporter
	LibP2PConnectionMetrics
}

type Local interface {

	// NodeID returns the node ID of the local node.
	NodeID() flow.Identifier

	// Address returns the (listen) address of the local node.
	Address() string

	// Sign provides a signature oracle that given a message and hasher, it
	// generates and returns a signature over the message using the node's private key
	// as well as the input hasher
	Sign([]byte, hash.Hasher) (crypto.Signature, error)

	// NotMeFilter returns handy not-me filter for searching identity
	NotMeFilter() flow.IdentityFilter

	// SignFunc provides a signature oracle that given a message, a hasher, and a signing function, it
	// generates and returns a signature over the message using the node's private key
	// as well as the input hasher by invoking the given signing function. The overall idea of this function
	// is to not expose the private key to the caller.
	SignFunc([]byte, hash.Hasher, func(crypto.PrivateKey, []byte, hash.Hasher) (crypto.Signature,
		error)) (crypto.Signature, error)
}

type MempoolMetrics interface {
	MempoolEntries(resource string, entries uint)
	Register(resource string, entriesFunc EntriesFunc) error
}

type NetworkCoreMetrics interface {
	NetworkInboundQueueMetrics
	// OutboundMessageSent collects metrics related to a message sent by the node.
	OutboundMessageSent(sizeBytes int, topic string, protocol string, messageType string)
	// InboundMessageReceived collects metrics related to a message received by the node.
	InboundMessageReceived(sizeBytes int, topic string, protocol string, messageType string)
	// DuplicateInboundMessagesDropped increments the metric tracking the number of duplicate messages dropped by the node.
	DuplicateInboundMessagesDropped(topic string, protocol string, messageType string)
	// UnicastMessageSendingStarted increments the metric tracking the number of unicast messages sent by the node.
	UnicastMessageSendingStarted(topic string)
	// UnicastMessageSendingCompleted decrements the metric tracking the number of unicast messages sent by the node.
	UnicastMessageSendingCompleted(topic string)
	// MessageProcessingStarted increments the metric tracking the number of messages being processed by the node.
	MessageProcessingStarted(topic string)
	// MessageProcessingFinished tracks the time spent by the node to process a message and decrements the metric tracking
	// the number of messages being processed by the node.
	MessageProcessingFinished(topic string, duration time.Duration)
}

type NetworkInboundQueueMetrics interface {
	// MessageAdded increments the metric tracking the number of messages in the queue with the given priority
	MessageAdded(priority int)

	// MessageRemoved decrements the metric tracking the number of messages in the queue with the given priority
	MessageRemoved(priority int)

	// QueueDuration tracks the time spent by a message with the given priority in the queue
	QueueDuration(duration time.Duration, priority int)
}

type NetworkMetrics interface {
	LibP2PMetrics
	NetworkSecurityMetrics
	NetworkCoreMetrics
}

type NetworkSecurityMetrics interface {
	// OnUnauthorizedMessage tracks the number of unauthorized messages seen on the network.
	OnUnauthorizedMessage(role, msgType, topic, offense string)

	// OnRateLimitedUnicastMessage tracks the number of rate limited messages seen on the network.
	OnRateLimitedUnicastMessage(role, msgType, topic, reason string)
}

type NewJobListener interface {
	// Check let the producer notify the consumer that a new job has been added, so that the consumer
	// can check if there is worker available to process that job.
	Check()
}

type NoopReadyDoneAware struct{}

type PendingBlockBuffer interface {
	Add(originID flow.Identifier, block *flow.Block) bool

	ByID(blockID flow.Identifier) (flow.Slashable[flow.Block], bool)

	ByParentID(parentID flow.Identifier) ([]flow.Slashable[flow.Block], bool)

	DropForParent(parentID flow.Identifier)

	// PruneByView prunes any pending blocks with views less or equal to the given view.
	PruneByView(view uint64)

	Size() uint
}

type PendingClusterBlockBuffer interface {
	Add(originID flow.Identifier, block *cluster.Block) bool

	ByID(blockID flow.Identifier) (flow.Slashable[cluster.Block], bool)

	ByParentID(parentID flow.Identifier) ([]flow.Slashable[cluster.Block], bool)

	DropForParent(parentID flow.Identifier)

	// PruneByView prunes any pending cluster blocks with views less or equal to the given view.
	PruneByView(view uint64)

	Size() uint
}

type PingMetrics interface {
	// NodeReachable tracks the round trip time in milliseconds taken to ping a node
	// The nodeInfo provides additional information about the node such as the name of the node operator
	NodeReachable(node *flow.Identity, nodeInfo string, rtt time.Duration)

	// NodeInfo tracks the software version, sealed height and hotstuff view of a node
	NodeInfo(node *flow.Identity, nodeInfo string, version string, sealedHeight uint64, hotstuffCurView uint64)
}

type ProcessingNotifier interface {
	Notify(entityID flow.Identifier)
}

type ProviderMetrics interface {
	// ChunkDataPackRequestProcessed is executed every time a chunk data pack request is picked up for processing at execution node.
	// It increases the request processed counter by one.
	ChunkDataPackRequestProcessed()
}

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

type QCContractClient interface {

	// SubmitVote submits the given vote to the cluster QC aggregator smart
	// contract. This function returns only once the transaction has been
	// processed by the network. An error is returned if the transaction has
	// failed and should be re-submitted.
	SubmitVote(ctx context.Context, vote *model.Vote) error

	// Voted returns true if we have successfully submitted a vote to the
	// cluster QC aggregator smart contract for the current epoch.
	Voted(ctx context.Context) (bool, error)
}

type RandomBeaconKeyStore interface {
	// It returns:
	//  - (signer, nil) if the node has beacon keys in the epoch of the view
	//  - (nil, DKGFailError) if the node doesn't have beacon keys in the epoch of the view
	//  - (nil, error) if there is any exception
	ByView(view uint64) (crypto.PrivateKey, error)
}

type RateLimitedBlockstoreMetrics interface {
	BytesRead(int)
}

type ReadyDoneAware interface {
	// Ready commences startup of the module, and returns a ready channel that is closed once
	// startup has completed. Note that the ready channel may never close if errors are
	// encountered during startup.
	// If shutdown has already commenced before this method is called for the first time,
	// startup will not be performed and the returned channel will also never close.
	// This should be an idempotent method.
	Ready() <-chan struct{}

	// Done commences shutdown of the module, and returns a done channel that is closed once
	// shutdown has completed. Note that the done channel should be closed even if errors are
	// encountered during shutdown.
	// This should be an idempotent method.
	Done() <-chan struct{}
}

type ReceiptValidator interface {

	// Validate verifies that the ExecutionReceipt satisfies
	// the following conditions:
	// 	* is from Execution node with positive weight
	//	* has valid signature
	//	* chunks are in correct format
	// 	* execution result has a valid parent and satisfies the subgraph check
	// Returns nil if all checks passed successfully.
	// Expected errors during normal operations:
	// * engine.InvalidInputError
	//   if receipt violates protocol condition
	// * engine.UnverifiableInputError
	//   if receipt's parent result is unknown
	Validate(receipts *flow.ExecutionReceipt) error

	// ValidatePayload verifies the ExecutionReceipts and ExecutionResults
	// in the payload for compliance with the protocol:
	// Receipts:
	// 	* are from Execution node with positive weight
	//	* have valid signature
	//	* chunks are in correct format
	//  * no duplicates in fork
	// Results:
	// 	* have valid parents and satisfy the subgraph check
	//  * extend the execution tree, where the tree root is the latest
	//    finalized block and only results from this fork are included
	//  * no duplicates in fork
	// Expected errors during normal operations:
	// * engine.InvalidInputError
	//   if some receipts in the candidate block violate protocol condition
	// * engine.UnverifiableInputError
	//   if for some of the receipts, their respective parent result is unknown
	ValidatePayload(candidate *flow.Block) error
}

type Requester interface {
	// EntityByID will request an entity through the request engine backing
	// the interface. The additional selector will be applied to the subset
	// of valid providers for the entity and allows finer-grained control
	// over which providers to request a given entity from. Use `filter.Any`
	// if no additional restrictions are required. Data integrity of response
	// will be checked upon arrival. This function should be used for requesting
	// entites by their IDs.
	EntityByID(entityID flow.Identifier, selector flow.IdentityFilter)

	// Query will request data through the request engine backing the interface.
	// The additional selector will be applied to the subset
	// of valid providers for the data and allows finer-grained control
	// over which providers to request data from. Doesn't perform integrity check
	// can be used to get entities without knowing their ID.
	Query(key flow.Identifier, selector flow.IdentityFilter)

	// Force will force the dispatcher to send all possible batches immediately.
	// It can be used in cases where responsiveness is of utmost importance, at
	// the cost of additional network messages.
	Force()
}

type ResolverMetrics interface {
	// DNSLookupDuration tracks the time spent to resolve a DNS address.
	DNSLookupDuration(duration time.Duration)

	// OnDNSCacheMiss tracks the total number of dns requests resolved through looking up the network.
	OnDNSCacheMiss()

	// DNSCacheResolution tracks the total number of dns requests resolved through the cache without
	// looking up the network.
	OnDNSCacheHit()

	// OnDNSCacheInvalidated is called whenever dns cache is invalidated for an entry
	OnDNSCacheInvalidated()

	// OnDNSLookupRequestDropped tracks the number of dns lookup requests that are dropped due to a full queue
	OnDNSLookupRequestDropped()
}

type RuntimeMetrics interface {
	// TransactionParsed reports the time spent parsing a single transaction
	RuntimeTransactionParsed(dur time.Duration)

	// TransactionChecked reports the time spent checking a single transaction
	RuntimeTransactionChecked(dur time.Duration)

	// TransactionInterpreted reports the time spent interpreting a single transaction
	RuntimeTransactionInterpreted(dur time.Duration)

	// RuntimeSetNumberOfAccounts Sets the total number of accounts on the network
	RuntimeSetNumberOfAccounts(count uint64)
}

type SDKClientWrapper interface {
	GetAccount(context.Context, sdk.Address) (*sdk.Account, error)
	GetAccountAtLatestBlock(context.Context, sdk.Address) (*sdk.Account, error)
	SendTransaction(context.Context, sdk.Transaction) error
	GetLatestBlock(context.Context, bool) (*sdk.Block, error)
	GetTransactionResult(context.Context, sdk.Identifier) (*sdk.TransactionResult, error)
	ExecuteScriptAtLatestBlock(context.Context, []byte, []cadence.Value) (cadence.Value, error)
	ExecuteScriptAtBlockID(context.Context, sdk.Identifier, []byte, []cadence.Value) (cadence.Value, error)
}

type SealValidator interface {
	Validate(candidate *flow.Block) (*flow.Seal, error)
}

type SealingConfigsGetter interface {
	// updatable fields
	RequireApprovalsForSealConstructionDynamicValue() uint

	// not-updatable fields
	ChunkAlphaConst() uint
	RequireApprovalsForSealVerificationConst() uint
	EmergencySealingActiveConst() bool
	ApprovalRequestsThresholdConst() uint64
}

type SealingConfigsSetter interface {
	SealingConfigsGetter
	// SetRequiredApprovalsForSealingConstruction takes a new config value and updates the config
	// if the new value is valid.
	// Returns ValidationError if the new value results in an invalid sealing config.
	SetRequiredApprovalsForSealingConstruction(newVal uint) error
}

type Startable interface {
	// Start starts the component. Any irrecoverable errors encountered while the component is running
	// should be thrown with the given SignalerContext.
	// This method should only be called once, and subsequent calls should panic with ErrMultipleStartup.
	Start(irrecoverable.SignalerContext)
}

type SyncCore interface {

	// HandleBlock handles receiving a new block. It returns true if the block
	// should be passed along to the rest of the system for processing, or false
	// if it should be discarded.
	HandleBlock(header *flow.Header) bool

	// HandleHeight handles receiving a new highest finalized height from another node.
	HandleHeight(final *flow.Header, height uint64)

	// ScanPending scans all pending block statuses for blocks that should be
	// requested. It apportions requestable items into range and batch requests
	// according to configured maximums, giving precedence to range requests.
	ScanPending(final *flow.Header) ([]chainsync.Range, []chainsync.Batch)

	// WithinTolerance returns whether or not the given height is within configured
	// height tolerance, wrt the given local finalized header.
	WithinTolerance(final *flow.Header, height uint64) bool

	// RangeRequested updates sync state after a range is requested.
	RangeRequested(ran chainsync.Range)

	// BatchRequested updates sync state after a batch is requested.
	BatchRequested(batch chainsync.Batch)
}

type Tracer interface {
	ReadyDoneAware

	// StartBlockSpan starts an span for a block, built as a child of rootSpan.
	// It also returns the context including this span which can be used for
	// nested calls.
	StartBlockSpan(
		ctx context.Context,
		blockID flow.Identifier,
		spanName trace.SpanName,
		opts ...otelTrace.SpanStartOption,
	) (
		otelTrace.Span,
		context.Context,
	)

	// StartCollectionSpan starts an span for a collection, built as a child of
	// rootSpan.  It also returns the context including this span which can be
	// used for nested calls.
	StartCollectionSpan(
		ctx context.Context,
		collectionID flow.Identifier,
		spanName trace.SpanName,
		opts ...otelTrace.SpanStartOption,
	) (
		otelTrace.Span,
		context.Context,
	)

	// StartTransactionSpan starts an span for a transaction, built as a child
	// of rootSpan.  It also returns the context including this span which can
	// be used for nested calls.
	StartTransactionSpan(
		ctx context.Context,
		transactionID flow.Identifier,
		spanName trace.SpanName,
		opts ...otelTrace.SpanStartOption,
	) (
		otelTrace.Span,
		context.Context,
	)

	StartSpanFromContext(
		ctx context.Context,
		operationName trace.SpanName,
		opts ...otelTrace.SpanStartOption,
	) (
		otelTrace.Span,
		context.Context,
	)

	StartSpanFromParent(
		parentSpan otelTrace.Span,
		operationName trace.SpanName,
		opts ...otelTrace.SpanStartOption,
	) otelTrace.Span

	// WithSpanFromContext encapsulates executing a function within an span, i.e., it starts a span with the specified SpanName from the context,
	// executes the function f, and finishes the span once the function returns.
	WithSpanFromContext(
		ctx context.Context,
		operationName trace.SpanName,
		f func(),
		opts ...otelTrace.SpanStartOption,
	)
}

type TransactionMetrics interface {
	BackendScriptsMetrics

	// Record the round trip time while getting a transaction result
	TransactionResultFetched(dur time.Duration, size int)

	// TransactionReceived starts tracking of transaction execution/finalization/sealing
	TransactionReceived(txID flow.Identifier, when time.Time)

	// TransactionFinalized reports the time spent between the transaction being received and finalized. Reporting only
	// works if the transaction was earlier added as received.
	TransactionFinalized(txID flow.Identifier, when time.Time)

	// TransactionExecuted reports the time spent between the transaction being received and executed. Reporting only
	// works if the transaction was earlier added as received.
	TransactionExecuted(txID flow.Identifier, when time.Time)

	// TransactionExpired tracks number of expired transactions
	TransactionExpired(txID flow.Identifier)

	// TransactionSubmissionFailed should be called whenever we try to submit a transaction and it fails
	TransactionSubmissionFailed()

	// UpdateExecutionReceiptMaxHeight is called whenever we store an execution receipt from a block from a newer height
	UpdateExecutionReceiptMaxHeight(height uint64)
}

type VerificationMetrics interface {
	// OnBlockConsumerJobDone is invoked by block consumer whenever it is notified a job is done by a worker. It
	// sets the last processed block job index.
	OnBlockConsumerJobDone(uint64)
	// OnChunkConsumerJobDone is invoked by chunk consumer whenever it is notified a job is done by a worker. It
	// sets the last processed chunk job index.
	OnChunkConsumerJobDone(uint64)
	// OnExecutionResultReceivedAtAssignerEngine is called whenever a new execution result arrives
	// at Assigner engine. It increments total number of received execution results.
	OnExecutionResultReceivedAtAssignerEngine()

	// OnVerifiableChunkReceivedAtVerifierEngine increments a counter that keeps track of number of verifiable chunks received at
	// verifier engine from fetcher engine.
	OnVerifiableChunkReceivedAtVerifierEngine()

	// OnFinalizedBlockArrivedAtAssigner sets a gauge that keeps track of number of the latest block height arrives
	// at assigner engine. Note that it assumes blocks are coming to assigner engine in strictly increasing order of their height.
	OnFinalizedBlockArrivedAtAssigner(height uint64)

	// OnChunksAssignmentDoneAtAssigner increments a counter that keeps track of the total number of assigned chunks to
	// the verification node.
	OnChunksAssignmentDoneAtAssigner(chunks int)

	// OnAssignedChunkProcessedAtAssigner increments a counter that keeps track of the total number of assigned chunks pushed by
	// assigner engine to the fetcher engine.
	OnAssignedChunkProcessedAtAssigner()

	// OnAssignedChunkReceivedAtFetcher increments a counter that keeps track of number of assigned chunks arrive at fetcher engine.
	OnAssignedChunkReceivedAtFetcher()

	// OnChunkDataPackRequestSentByFetcher increments a counter that keeps track of number of chunk data pack requests that fetcher engine
	// sends to requester engine.
	OnChunkDataPackRequestSentByFetcher()

	// OnChunkDataPackRequestReceivedByRequester increments a counter that keeps track of number of chunk data pack requests
	// arrive at the requester engine from the fetcher engine.
	OnChunkDataPackRequestReceivedByRequester()

	// OnChunkDataPackRequestDispatchedInNetwork increments a counter that keeps track of number of chunk data pack requests that the
	// requester engine dispatches in the network (to the execution nodes).
	OnChunkDataPackRequestDispatchedInNetworkByRequester()

	// OnChunkDataPackResponseReceivedFromNetwork increments a counter that keeps track of number of chunk data pack responses that the
	// requester engine receives from execution nodes (through network).
	OnChunkDataPackResponseReceivedFromNetworkByRequester()

	// SetMaxChunkDataPackAttemptsForNextUnsealedHeightAtRequester is invoked when a cycle of requesting chunk data packs is done by requester engine.
	// It updates the maximum number of attempts made by requester engine for requesting the chunk data packs of the next unsealed height.
	// The maximum is taken over the history of all chunk data packs requested during that cycle that belong to the next unsealed height.
	SetMaxChunkDataPackAttemptsForNextUnsealedHeightAtRequester(attempts uint64)

	// OnChunkDataPackSentToFetcher increments a counter that keeps track of number of chunk data packs sent to the fetcher engine from
	// requester engine.
	OnChunkDataPackSentToFetcher()

	// OnChunkDataPackArrivedAtFetcher increments a counter that keeps track of number of chunk data packs arrived at fetcher engine from
	// requester engine.
	OnChunkDataPackArrivedAtFetcher()

	// OnVerifiableChunkSentToVerifier increments a counter that keeps track of number of verifiable chunks fetcher engine sent to verifier engine.
	OnVerifiableChunkSentToVerifier()

	// OnResultApprovalDispatchedInNetwork increments a counter that keeps track of number of result approvals dispatched in the network
	// by verifier engine.
	OnResultApprovalDispatchedInNetworkByVerifier()
}

type WALMetrics interface {
}