common

type AcceptedHandler interface {
	// Notify this engine of a request to filter non-accepted vertices.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is utilizing a unique requestID. However, the validatorID is
	// assumed to be authenticated.
	//
	// This engine should respond with an Accepted message with the same
	// requestID, and the subset of the containerIDs that this node has decided
	// are accepted.
	GetAccepted(
		validatorID ids.ShortID,
		requestID uint32,
		containerIDs []ids.ID,
	) error

	// Notify this engine of a set of accepted vertices.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is in response to a GetAccepted message, is utilizing a
	// unique requestID, or that the containerIDs are a subset of the
	// containerIDs from a GetAccepted message. However, the validatorID is
	// assumed to be authenticated.
	Accepted(
		validatorID ids.ShortID,
		requestID uint32,
		containerIDs []ids.ID,
	) error

	// Notify this engine that a get accepted request it issued has failed.
	//
	// This function will be called if the engine sent a GetAccepted message
	// that is not anticipated to be responded to. This could be because the
	// recipient of the message is unknown or if the message request has timed
	// out.
	//
	// The validatorID, and requestID, are assumed to be the same as those sent
	// in the GetAccepted message.
	GetAcceptedFailed(validatorID ids.ShortID, requestID uint32) error
}

type AcceptedSender interface {
	// GetAccepted requests that every validator in [validatorIDs] sends an
	// Accepted message with all the IDs in [containerIDs] that the validator
	// thinks is accepted.
	GetAccepted(validatorIDs ids.ShortSet, requestID uint32, containerIDs []ids.ID)

	// Accepted responds to a GetAccepted message with a set of IDs of
	// containers that are accepted.
	Accepted(validatorID ids.ShortID, requestID uint32, containerIDs []ids.ID)
}

type Bootstrapable interface {
	// Returns the set of containerIDs that are accepted, but have no accepted
	// children.
	CurrentAcceptedFrontier() []ids.ID

	// Returns the subset of containerIDs that are accepted by this chain.
	FilterAccepted(containerIDs []ids.ID) (acceptedContainerIDs []ids.ID)

	// Force the provided containers to be accepted. Only returns fatal errors
	// if they occur.
	ForceAccepted(acceptedContainerIDs []ids.ID) error
}

type BootstrapableTest struct {
	T *testing.T

	CantCurrentAcceptedFrontier,
	CantFilterAccepted,
	CantForceAccepted bool

	CurrentAcceptedFrontierF func() (acceptedContainerIDs []ids.ID)
	FilterAcceptedF          func(containerIDs []ids.ID) (acceptedContainerIDs []ids.ID)
	ForceAcceptedF           func(acceptedContainerIDs []ids.ID) error
}

type Bootstrapper struct {
	Config

	RequestID uint32
	// contains filtered or unexported fields
}

type Config struct {
	Ctx        *snow.Context
	Validators validators.Set
	Beacons    validators.Set

	SampleK       int
	StartupAlpha  uint64
	Alpha         uint64
	Sender        Sender
	Bootstrapable Bootstrapable
}

type Engine interface {
	Handler

	// Return the context of the chain this engine is working on
	Context() *snow.Context

	// Returns true iff the chain is done bootstrapping
	IsBootstrapped() bool

	// Returns nil if the engine is healthy.
	// Periodically called and reported through the health API
	Health() (interface{}, error)
}

type EngineTest struct {
	T *testing.T

	CantIsBootstrapped,
	CantStartup,
	CantGossip,
	CantShutdown,

	CantContext,

	CantNotify,

	CantGetAcceptedFrontier,
	CantGetAcceptedFrontierFailed,
	CantAcceptedFrontier,

	CantGetAccepted,
	CantGetAcceptedFailed,
	CantAccepted,

	CantGet,
	CantGetAncestors,
	CantGetFailed,
	CantGetAncestorsFailed,
	CantPut,
	CantMultiPut,

	CantPushQuery,
	CantPullQuery,
	CantQueryFailed,
	CantChits,

	CantConnected,
	CantDisconnected,

	CantHealth bool

	IsBootstrappedF                                    func() bool
	ContextF                                           func() *snow.Context
	StartupF, GossipF, ShutdownF                       func() error
	NotifyF                                            func(Message) error
	GetF, GetAncestorsF, PullQueryF                    func(validatorID ids.ShortID, requestID uint32, containerID ids.ID) error
	PutF, PushQueryF                                   func(validatorID ids.ShortID, requestID uint32, containerID ids.ID, container []byte) error
	MultiPutF                                          func(validatorID ids.ShortID, requestID uint32, containers [][]byte) error
	AcceptedFrontierF, GetAcceptedF, AcceptedF, ChitsF func(validatorID ids.ShortID, requestID uint32, containerIDs []ids.ID) error
	GetAcceptedFrontierF, GetFailedF, GetAncestorsFailedF,
	QueryFailedF, GetAcceptedFrontierFailedF, GetAcceptedFailedF func(validatorID ids.ShortID, requestID uint32) error
	ConnectedF, DisconnectedF func(validatorID ids.ShortID) error
	HealthF                   func() (interface{}, error)
}

type ExternalHandler interface {
	FrontierHandler
	AcceptedHandler
	FetchHandler
	QueryHandler
}

type FetchHandler interface {
	// Notify this engine of a request for a container.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is utilizing a unique requestID. It is also not safe to
	// assume the requested containerID exists. However, the validatorID is
	// assumed to be authenticated.
	//
	// There should never be a situation where a virtuous node sends a Get
	// request to another virtuous node that does not have the requested
	// container. Unless that container was pruned from the active set.
	//
	// This engine should respond with a Put message with the same requestID if
	// the container was locally available. Otherwise, the message can be safely
	// dropped.
	Get(validatorID ids.ShortID, requestID uint32, containerID ids.ID) error

	// Notify this engine of a request for a container and its ancestors.
	// The request is from validator [validatorID]. The requested container is [containerID].
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is utilizing a unique requestID. It is also not safe to
	// assume the requested containerID exists. However, the validatorID is
	// assumed to be authenticated.
	//
	// This engine should respond with a MultiPut message with the same requestID,
	// which contains [containerID] as well as its ancestors. See MultiPut's documentation.
	//
	// If this engine doesn't have some ancestors, it should reply with its best effort attempt at getting them.
	// If this engine doesn't have [containerID] it can ignore this message.
	GetAncestors(validatorID ids.ShortID, requestID uint32, containerID ids.ID) error

	// Notify this engine of a container.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is utilizing a unique requestID or even that the containerID
	// matches the ID of the container bytes. However, the validatorID is
	// assumed to be authenticated.
	//
	// This engine needs to request and receive missing ancestors of the
	// container before adding the container to consensus. Once all ancestor
	// containers are added, pushes the container into the consensus.
	Put(
		validatorID ids.ShortID,
		requestID uint32,
		containerID ids.ID,
		container []byte,
	) error

	// Notify this engine of multiple containers.
	// Each element of [containers] is the byte representation of a container.
	//
	// This should only be called during bootstrapping, and in response to a GetAncestors message to
	// [validatorID] with request ID [requestID]. This call should contain the container requested in
	// that message, along with ancestors.
	// The containers should be in BFS order (ie the first container must be the container
	// requested in the GetAncestors message and further back ancestors are later in [containers]
	//
	// It is not safe to assume this message is in response to a GetAncestor message, that this
	// message has a unique requestID or that any of the containers in [containers] are valid.
	// However, the validatorID is assumed to be authenticated.
	MultiPut(
		validatorID ids.ShortID,
		requestID uint32,
		containers [][]byte,
	) error

	// Notify this engine that a get request it issued has failed.
	//
	// This function will be called if the engine sent a Get message that is not
	// anticipated to be responded to. This could be because the recipient of
	// the message is unknown or if the message request has timed out.
	//
	// The validatorID and requestID are assumed to be the same as those sent in
	// the Get message.
	GetFailed(validatorID ids.ShortID, requestID uint32) error

	// Notify this engine that a GetAncestors request it issued has failed.
	//
	// This function will be called if the engine sent a GetAncestors message that is not
	// anticipated to be responded to. This could be because the recipient of
	// the message is unknown or if the message request has timed out.
	//
	// The validatorID and requestID are assumed to be the same as those sent in
	// the GetAncestors message.
	GetAncestorsFailed(validatorID ids.ShortID, requestID uint32) error
}

type FetchSender interface {
	// Request a container from a validator.
	// Request that the specified validator send the specified container
	// to this validator
	Get(validatorID ids.ShortID, requestID uint32, containerID ids.ID)

	// GetAncestors requests that the validator with ID [validatorID] send container [containerID] and its
	// ancestors. The maximum number of ancestors to send in response is defined in snow/engine/common/bootstrapper.go
	GetAncestors(validatorID ids.ShortID, requestID uint32, containerID ids.ID)

	// Tell the specified validator that the container whose ID is <containerID>
	// has body <container>
	Put(validatorID ids.ShortID, requestID uint32, containerID ids.ID, container []byte)

	// Give the specified validator several containers at once
	// Should be in response to a GetAncestors message with request ID [requestID] from the validator
	MultiPut(validatorID ids.ShortID, requestID uint32, containers [][]byte)
}

type Fetcher struct {
	// number of containers fetched so far
	NumFetched uint32

	// tracks which validators were asked for which containers in which requests
	OutstandingRequests Requests

	// Called when bootstrapping is done
	OnFinished func() error
}

type FrontierHandler interface {
	// Notify this engine of a request for the accepted frontier of vertices.
	//
	// The accepted frontier is the set of accepted vertices that do not have
	// any accepted descendants.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is utilizing a unique requestID. However, the validatorID is
	// assumed to be authenticated.
	//
	// This engine should respond with an AcceptedFrontier message with the same
	// requestID, and the engine's current accepted frontier.
	GetAcceptedFrontier(validatorID ids.ShortID, requestID uint32) error

	// Notify this engine of an accepted frontier.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is in response to a GetAcceptedFrontier message, is
	// utilizing a unique requestID, or that the containerIDs from a valid
	// frontier. However, the validatorID is  assumed to be authenticated.
	AcceptedFrontier(
		validatorID ids.ShortID,
		requestID uint32,
		containerIDs []ids.ID,
	) error

	// Notify this engine that a get accepted frontier request it issued has
	// failed.
	//
	// This function will be called if the engine sent a GetAcceptedFrontier
	// message that is not anticipated to be responded to. This could be because
	// the recipient of the message is unknown or if the message request has
	// timed out.
	//
	// The validatorID, and requestID, are assumed to be the same as those sent
	// in the GetAcceptedFrontier message.
	GetAcceptedFrontierFailed(validatorID ids.ShortID, requestID uint32) error
}

type FrontierSender interface {
	// GetAcceptedFrontier requests that every validator in [validatorIDs] sends
	// an AcceptedFrontier message.
	GetAcceptedFrontier(validatorIDs ids.ShortSet, requestID uint32)

	// AcceptedFrontier responds to a AcceptedFrontier message with this
	// engine's current accepted frontier.
	AcceptedFrontier(validatorID ids.ShortID, requestID uint32, containerIDs []ids.ID)
}

type Fx struct {
	ID ids.ID
	Fx interface{}
}

type Gossiper interface {
	// Gossip gossips the provided container throughout the network
	Gossip(containerID ids.ID, container []byte)
}

type HTTPHandler struct {
	LockOptions LockOption
	Handler     http.Handler
}

type Handler interface {
	ExternalHandler
	InternalHandler
}

type InternalHandler interface {
	// Startup this engine.
	//
	// This function will be called once the environment is configured to be
	// able to run the engine.
	Startup() error

	// Gossip to the network a container on the accepted frontier
	Gossip() error

	// Shutdown this engine.
	//
	// This function will be called when the environment is exiting.
	Shutdown() error

	// Notify this engine of a message from the virtual machine.
	Notify(Message) error

	// Notify this engine of a new peer.
	Connected(validatorID ids.ShortID) error

	// Notify this engine of a removed peer.
	Disconnected(validatorID ids.ShortID) error
}

type LockOption uint32

type Message uint32

type QueryHandler interface {
	// Notify this engine of a request for our preferences.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is utilizing a unique requestID. However, the validatorID is
	// assumed to be authenticated.
	//
	// If the container or its ancestry is incomplete, this engine is expected
	// to request the missing containers from the validator. Once the ancestry
	// is complete, this engine should send this validator the current
	// preferences in a Chits message. The Chits message should have the same
	// requestID that was passed in here.
	PullQuery(
		validatorID ids.ShortID,
		requestID uint32,
		containerID ids.ID,
	) error

	// Notify this engine of a request for our preferences.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is utilizing a unique requestID or even that the containerID
	// matches the ID of the container bytes. However, the validatorID is
	// assumed to be authenticated.
	//
	// This function is meant to behave the same way as PullQuery, except the
	// container is optimistically provided to potentially remove the need for
	// a series of Get/Put messages.
	//
	// If the ancestry of the container is incomplete, this engine is expected
	// to request the ancestry from the validator. Once the ancestry is
	// complete, this engine should send this validator the current preferences
	// in a Chits message. The Chits message should have the same requestID that
	// was passed in here.
	PushQuery(
		validatorID ids.ShortID,
		requestID uint32,
		containerID ids.ID,
		container []byte,
	) error

	// Notify this engine of the specified validators preferences.
	//
	// This function can be called by any validator. It is not safe to assume
	// this message is in response to a PullQuery or a PushQuery message.
	// However, the validatorID is assumed to be authenticated.
	Chits(validatorID ids.ShortID, requestID uint32, containerIDs []ids.ID) error

	// Notify this engine that a query it issued has failed.
	//
	// This function will be called if the engine sent a PullQuery or PushQuery
	// message that is not anticipated to be responded to. This could be because
	// the recipient of the message is unknown or if the message request has
	// timed out.
	//
	// The validatorID and the requestID are assumed to be the same as those
	// sent in the Query message.
	QueryFailed(validatorID ids.ShortID, requestID uint32) error
}

type QuerySender interface {
	// Request from the specified validators their preferred frontier, given the
	// existence of the specified container.
	// This is the same as PullQuery, except that this message includes not only
	// the ID of the container but also its body.
	PushQuery(validatorIDs ids.ShortSet, requestID uint32, containerID ids.ID, container []byte)

	// Request from the specified validators their preferred frontier, given the
	// existence of the specified container.
	PullQuery(validatorIDs ids.ShortSet, requestID uint32, containerID ids.ID)

	// Chits sends chits to the specified validator
	Chits(validatorID ids.ShortID, requestID uint32, votes []ids.ID)
}

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

type Sender interface {
	FrontierSender
	AcceptedSender
	FetchSender
	QuerySender
	Gossiper
}

type SenderTest struct {
	T *testing.T

	CantGetAcceptedFrontier, CantAcceptedFrontier,
	CantGetAccepted, CantAccepted,
	CantGet, CantGetAncestors, CantPut, CantMultiPut,
	CantPullQuery, CantPushQuery, CantChits,
	CantGossip bool

	GetAcceptedFrontierF func(ids.ShortSet, uint32)
	AcceptedFrontierF    func(ids.ShortID, uint32, []ids.ID)
	GetAcceptedF         func(ids.ShortSet, uint32, []ids.ID)
	AcceptedF            func(ids.ShortID, uint32, []ids.ID)
	GetF                 func(ids.ShortID, uint32, ids.ID)
	GetAncestorsF        func(ids.ShortID, uint32, ids.ID)
	PutF                 func(ids.ShortID, uint32, ids.ID, []byte)
	MultiPutF            func(ids.ShortID, uint32, [][]byte)
	PushQueryF           func(ids.ShortSet, uint32, ids.ID, []byte)
	PullQueryF           func(ids.ShortSet, uint32, ids.ID)
	ChitsF               func(ids.ShortID, uint32, []ids.ID)
	GossipF              func(ids.ID, []byte)
}

type StaticVM interface {
	// Creates the HTTP handlers for custom VM network calls.
	//
	// This exposes handlers that the outside world can use to communicate with
	// a static reference to the VM. Each handler has the path:
	// [Address of node]/ext/VM/[VM ID]/[extension]
	//
	// Returns a mapping from [extension]s to HTTP handlers.
	//
	// Each extension can specify how locking is managed for convenience.
	//
	// For example, it might make sense to have an extension for creating
	// genesis bytes this VM can interpret.
	CreateStaticHandlers() map[string]*HTTPHandler
}

type TestVM struct {
	T *testing.T

	CantInitialize, CantBootstrapping, CantBootstrapped,
	CantShutdown, CantCreateHandlers, CantCreateStaticHandlers,
	CantHealth bool

	InitializeF                              func(*snow.Context, database.Database, []byte, chan<- Message, []*Fx) error
	BootstrappingF, BootstrappedF, ShutdownF func() error
	CreateHandlersF                          func() map[string]*HTTPHandler
	CreateStaticHandlersF                    func() map[string]*HTTPHandler
	HealthF                                  func() (interface{}, error)
}

type VM interface {
	// Initialize this VM.
	// [ctx]: Metadata about this VM.
	//     [ctx.networkID]: The ID of the network this VM's chain is running on.
	//     [ctx.chainID]: The unique ID of the chain this VM is running on.
	//     [ctx.Log]: Used to log messages
	//     [ctx.NodeID]: The unique staker ID of this node.
	//     [ctx.Lock]: A Read/Write lock shared by this VM and the consensus
	//                 engine that manages this VM. The write lock is held
	//                 whenever code in the consensus engine calls the VM.
	// [db]: The database this VM will persist data to.
	// [genesisBytes]: The byte-encoding of the genesis information of this
	//                 VM. The VM uses it to initialize its state. For
	//                 example, if this VM were an account-based payments
	//                 system, `genesisBytes` would probably contain a genesis
	//                 transaction that gives coins to some accounts, and this
	//                 transaction would be in the genesis block.
	// [toEngine]: The channel used to send messages to the consensus engine.
	// [fxs]: Feature extensions that attach to this VM.
	Initialize(
		ctx *snow.Context,
		db database.Database,
		genesisBytes []byte,
		toEngine chan<- Message,
		fxs []*Fx,
	) error

	// Bootstrapping is called when the node is starting to bootstrap this chain.
	Bootstrapping() error

	// Bootstrapped is called when the node is done bootstrapping this chain.
	Bootstrapped() error

	// Shutdown is called when the node is shutting down.
	Shutdown() error

	// Creates the HTTP handlers for custom chain network calls.
	//
	// This exposes handlers that the outside world can use to communicate with
	// the chain. Each handler has the path:
	// [Address of node]/ext/bc/[chain ID]/[extension]
	//
	// Returns a mapping from [extension]s to HTTP handlers.
	//
	// Each extension can specify how locking is managed for convenience.
	//
	// For example, if this VM implements an account-based payments system,
	// it have an extension called `accounts`, where clients could get
	// information about their accounts.
	CreateHandlers() map[string]*HTTPHandler

	// Returns nil if the VM is healthy.
	// Periodically called and reported via the node's Health API.
	Health() (interface{}, error)
}