cluster

type MutableState interface {
	State
	// Extend introduces the given block into the cluster state as a pending
	// without modifying the current finalized state.
	// The block's parent must have already been successfully inserted.
	// Expected errors during normal operations:
	//   - state.OutdatedExtensionError if the candidate block is outdated (e.g. orphaned)
	//   - state.UnverifiableExtensionError if the reference block is _not_ a known finalized block
	//   - state.InvalidExtensionError if the candidate block is invalid
	Extend(proposal *cluster.Proposal) error
}

type Params interface {
	// ChainID returns the chain ID for this cluster.
	ChainID() flow.ChainID
}

type Snapshot interface {

	// Collection returns the collection designated as the reference for this
	// snapshot. Technically, this is a portion of the payload of a cluster block.
	//
	// Expected error returns during normal operations:
	//  - If the snapshot is for an unknown collection [state.ErrUnknownSnapshotReference]
	Collection() (*flow.Collection, error)

	// Head returns the header of the collection that is designated as the reference for
	// this snapshot. Technically, this is the header of a [cluster.Block]
	//
	// Expected error returns during normal operations:
	//  - If the snapshot is for an unknown collection [state.ErrUnknownSnapshotReference]
	Head() (*flow.Header, error)

	// Pending returns the IDs of *all* collections descending from the snapshot's head collection.
	// The result is ordered such that parents are included before their children. While only valid
	// descendants will be returned, note that the descendants may not be finalized yet.
	//
	// CAUTION: the list of descendants is constructed for each call via database reads,
	// and may be expensive to compute, especially if the reference collection is older.
	//
	// Expected error returns during normal operations:
	//  - If the snapshot is for an unknown collection [state.ErrUnknownSnapshotReference]
	Pending() ([]flow.Identifier, error)
}

type State interface {

	// Params returns constant information about the cluster state.
	Params() Params

	// Final returns the snapshot of the cluster state at the latest finalized
	// block. The returned snapshot is therefore immutable over time.
	Final() Snapshot

	// AtBlockID returns the snapshot of the persistent cluster at the given
	// block ID. It is available for any block that was introduced into the
	// cluster state, and can thus represent an ambiguous state that was or
	// will never be finalized.
	// If the block is unknown, it returns an invalid snapshot, which returns
	// state.ErrUnknownSnapshotReference for all methods
	AtBlockID(blockID flow.Identifier) Snapshot
}