common

package
v1.7.6-rc.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2022 License: BSD-3-Clause Imports: 17 Imported by: 224

Documentation

Index

Constants

View Source 
const (
	// StatusUpdateFrequency is how many containers should be processed between
	// logs
	StatusUpdateFrequency = 5000

	// MaxOutstandingGetAncestorsRequests is the maximum number of GetAncestors
	// sent but not responded to/failed
	MaxOutstandingGetAncestorsRequests = 10

	// MaxOutstandingBootstrapRequests is the maximum number of
	// GetAcceptedFrontier and GetAccepted messages sent but not responded
	// to/failed
	MaxOutstandingBootstrapRequests = 50

	// MaxTimeFetchingAncestors is the maximum amount of time to spend fetching
	// vertices during a call to GetAncestors
	MaxTimeFetchingAncestors = 50 * time.Millisecond
)
View Source 
const (
	WriteLock = iota
	ReadLock
	NoLock
)

List of all allowed options

Variables

This section is empty.

Functions

This section is empty.

Types

type AcceptedFrontierHandler added in v1.7.4 

type AcceptedFrontierHandler interface {
	// 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.
	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
}

AcceptedFrontierHandler defines how a consensus engine reacts to accepted frontier messages from other validators. Functions only return fatal errors.

func NewNoOpAcceptedFrontierHandler added in v1.7.4 

func NewNoOpAcceptedFrontierHandler(log logging.Logger) AcceptedFrontierHandler

type AcceptedHandler 

type AcceptedHandler interface {
	// 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.
	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
}

AcceptedHandler defines how a consensus engine reacts to accepted messages from other validators. Functions only return fatal errors.

func NewNoOpAcceptedHandler added in v1.7.4 

func NewNoOpAcceptedHandler(log logging.Logger) AcceptedHandler

type AcceptedSender 

type AcceptedSender interface {
	// SendGetAccepted requests that every node in [nodeIDs] sends an Accepted
	// message with all the IDs in [containerIDs] that the node thinks are
	// accepted.
	SendGetAccepted(
		nodeIDs ids.ShortSet,
		requestID uint32,
		containerIDs []ids.ID,
	)

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

AcceptedSender defines how a consensus engine sends messages pertaining to accepted containers

type AllGetsServer added in v1.7.4 

type AllGetsServer interface {
	GetAcceptedFrontierHandler
	GetAcceptedHandler
	GetAncestorsHandler
	GetHandler
}

type AncestorsHandler added in v1.7.4 

type AncestorsHandler interface {
	// Notify this engine of multiple containers.
	//
	// Each element of [containers] is the byte representation of a container.
	//
	// This should only be called during bootstrapping, 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.
	Ancestors(
		validatorID ids.ShortID,
		requestID uint32,
		containers [][]byte,
	) 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
}

AncestorsHandler defines how a consensus engine reacts to bootstrapping retrieval messages from other validators. Functions only return fatal errors.

func NewNoOpAncestorsHandler added in v1.7.4 

func NewNoOpAncestorsHandler(log logging.Logger) AncestorsHandler

type AppHandler added in v1.5.3 

type AppHandler interface {
	// Notify this engine of a request for data from [nodeID].
	//
	// The meaning of [request], and what should be sent in response to it, is
	// application (VM) specific.
	//
	// It is not guaranteed that:
	// * [request] is well-formed/valid.
	//
	// This node should typically send an AppResponse to [nodeID] in response to
	// a valid message using the same request ID before the deadline. However,
	// the VM may arbitrarily choose to not send a response to this request.
	AppRequest(nodeID ids.ShortID, requestID uint32, deadline time.Time, request []byte) error

	// Notify this engine that an AppRequest message it sent to [nodeID] with
	// request ID [requestID] failed.
	//
	// This may be because the request timed out or because the message couldn't
	// be sent to [nodeID].
	//
	// It is guaranteed that:
	// * This engine sent a request to [nodeID] with ID [requestID].
	// * AppRequestFailed([nodeID], [requestID]) has not already been called.
	// * AppResponse([nodeID], [requestID]) has not already been called.
	AppRequestFailed(nodeID ids.ShortID, requestID uint32) error

	// Notify this engine of a response to the AppRequest message it sent to
	// [nodeID] with request ID [requestID].
	//
	// The meaning of [response] is application (VM) specifc.
	//
	// It is guaranteed that:
	// * This engine sent a request to [nodeID] with ID [requestID].
	// * AppRequestFailed([nodeID], [requestID]) has not already been called.
	// * AppResponse([nodeID], [requestID]) has not already been called.
	//
	// It is not guaranteed that:
	// * [response] contains the expected response
	// * [response] is well-formed/valid.
	//
	// If [response] is invalid or not the expected response, the VM chooses how
	// to react. For example, the VM may send another AppRequest, or it may give
	// up trying to get the requested information.
	AppResponse(nodeID ids.ShortID, requestID uint32, response []byte) error

	// Notify this engine of a gossip message from [nodeID].
	//
	// The meaning of [msg] is application (VM) specific, and the VM defines how
	// to react to this message.
	//
	// This message is not expected in response to any event, and it does not
	// need to be responded to.
	//
	// A node may gossip the same message multiple times. That is,
	// AppGossip([nodeID], [msg]) may be called multiple times.
	AppGossip(nodeID ids.ShortID, msg []byte) error
}

AppHandler defines how a consensus engine reacts to app specific messages. Functions only return fatal errors.

func NewNoOpAppHandler added in v1.7.4 

func NewNoOpAppHandler(log logging.Logger) AppHandler

type AppSender added in v1.5.3 

type AppSender interface {
	// Send an application-level request.
	// A nil return value guarantees that for each nodeID in [nodeIDs],
	// the VM corresponding to this AppSender eventually receives either:
	// * An AppResponse from nodeID with ID [requestID]
	// * An AppRequestFailed from nodeID with ID [requestID]
	// Exactly one of the above messages will eventually be received per nodeID.
	// A non-nil error should be considered fatal.
	SendAppRequest(nodeIDs ids.ShortSet, requestID uint32, appRequestBytes []byte) error
	// Send an application-level response to a request.
	// This response must be in response to an AppRequest that the VM corresponding
	// to this AppSender received from [nodeID] with ID [requestID].
	// A non-nil error should be considered fatal.
	SendAppResponse(nodeID ids.ShortID, requestID uint32, appResponseBytes []byte) error
	// Gossip an application-level message.
	// A non-nil error should be considered fatal.
	SendAppGossip(appGossipBytes []byte) error
	SendAppGossipSpecific(nodeIDs ids.ShortSet, appGossipBytes []byte) error
}

AppSender sends application (VM) level messages. See also common.AppHandler.

type Bootstrapable 

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

	// Clear remove all containers to be processed upon bootstrapping
	Clear() error
}

Bootstrapable defines the functionality required to support bootstrapping

type BootstrapableEngine added in v1.7.4 

type BootstrapableEngine interface {
	Bootstrapable
	Engine
}

type BootstrapableTest 

type BootstrapableTest struct {
	T *testing.T

	CantForceAccepted, CantClear bool

	ClearF         func() error
	ForceAcceptedF func(acceptedContainerIDs []ids.ID) error
}

BootstrapableTest is a test engine that supports bootstrapping

func (*BootstrapableTest) Clear added in v1.7.5 

func (b *BootstrapableTest) Clear() error

func (*BootstrapableTest) Default 

func (b *BootstrapableTest) Default(cant bool)

Default sets the default on call handling

func (*BootstrapableTest) ForceAccepted 

func (b *BootstrapableTest) ForceAccepted(containerIDs []ids.ID) error

type Bootstrapper 

type Bootstrapper interface {
	AcceptedFrontierHandler
	AcceptedHandler
	Haltable
	Startup() error
	Restart(reset bool) error
}

func NewCommonBootstrapper added in v1.7.4 

func NewCommonBootstrapper(config Config) Bootstrapper

type BootstrapperTest added in v1.7.4 

type BootstrapperTest struct {
	BootstrapableTest
	EngineTest
}

EngineTest is a test engine

func (*BootstrapperTest) Default added in v1.7.4 

func (b *BootstrapperTest) Default(cant bool)

type ChitsHandler added in v1.7.4 

type ChitsHandler interface {
	// 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
}

ChitsHandler defines how a consensus engine reacts to query response messages from other validators. Functions only return fatal errors.

func NewNoOpChitsHandler added in v1.7.4 

func NewNoOpChitsHandler(log logging.Logger) ChitsHandler

type Config 

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

	SampleK       int
	StartupAlpha  uint64
	Alpha         uint64
	Sender        Sender
	Bootstrapable Bootstrapable
	Subnet        Subnet
	Timer         Timer

	// Should Bootstrap be retried
	RetryBootstrap bool

	// Max number of times to retry bootstrap before warning the node operator
	RetryBootstrapWarnFrequency int

	// Max time to spend fetching a container and its ancestors when responding
	// to a GetAncestors
	MaxTimeGetAncestors time.Duration

	// Max number of containers in an ancestors message sent by this node.
	AncestorsMaxContainersSent int

	// This node will only consider the first [AncestorsMaxContainersReceived]
	// containers in an ancestors message it receives.
	AncestorsMaxContainersReceived int

	SharedCfg *SharedConfig
}

Config wraps the common configurations that are needed by a Snow consensus engine

func DefaultConfigTest 

func DefaultConfigTest() Config

DefaultConfigTest returns a test configuration

func (*Config) Context 

func (c *Config) Context() *snow.ConsensusContext

func (*Config) IsBootstrapped added in v0.8.0 

func (c *Config) IsBootstrapped() bool

IsBootstrapped returns true iff this chain is done bootstrapping

type Engine 

type Engine interface {
	Handler

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

	// Start engine operations from given request ID
	Start(startReqID uint32) error

	// Returns nil if the engine is healthy.
	// Periodically called and reported through the health API
	health.Checker

	// GetVM returns this engine's VM
	GetVM() VM
}

Engine describes the standard interface of a consensus engine

type EngineTest 

type EngineTest struct {
	T *testing.T

	CantStart,

	CantIsBootstrapped,
	CantTimeout,
	CantGossip,
	CantHalt,
	CantShutdown,

	CantContext,

	CantNotify,

	CantGetAcceptedFrontier,
	CantGetAcceptedFrontierFailed,
	CantAcceptedFrontier,

	CantGetAccepted,
	CantGetAcceptedFailed,
	CantAccepted,

	CantGet,
	CantGetAncestors,
	CantGetFailed,
	CantGetAncestorsFailed,
	CantPut,
	CantAncestors,

	CantPushQuery,
	CantPullQuery,
	CantQueryFailed,
	CantChits,

	CantConnected,
	CantDisconnected,

	CantHealth,

	CantAppRequest,
	CantAppResponse,
	CantAppGossip,
	CantAppRequestFailed,

	CantGetVM bool

	StartF                                             func(startReqID uint32) error
	IsBootstrappedF                                    func() bool
	ContextF                                           func() *snow.ConsensusContext
	HaltF                                              func()
	TimeoutF, GossipF, ShutdownF                       func() error
	NotifyF                                            func(Message) error
	GetF, GetAncestorsF, PullQueryF                    func(nodeID ids.ShortID, requestID uint32, containerID ids.ID) error
	PutF, PushQueryF                                   func(nodeID ids.ShortID, requestID uint32, container []byte) error
	AncestorsF                                         func(nodeID ids.ShortID, requestID uint32, containers [][]byte) error
	AcceptedFrontierF, GetAcceptedF, AcceptedF, ChitsF func(nodeID ids.ShortID, requestID uint32, containerIDs []ids.ID) error
	GetAcceptedFrontierF, GetFailedF, GetAncestorsFailedF,
	QueryFailedF, GetAcceptedFrontierFailedF, GetAcceptedFailedF, AppRequestFailedF func(nodeID ids.ShortID, requestID uint32) error
	ConnectedF                func(nodeID ids.ShortID, nodeVersion version.Application) error
	DisconnectedF             func(nodeID ids.ShortID) error
	HealthF                   func() (interface{}, error)
	GetVMF                    func() VM
	AppRequestF, AppResponseF func(nodeID ids.ShortID, requestID uint32, msg []byte) error
	AppGossipF                func(nodeID ids.ShortID, msg []byte) error
}

EngineTest is a test engine

func (*EngineTest) Accepted 

func (e *EngineTest) Accepted(nodeID ids.ShortID, requestID uint32, containerIDs []ids.ID) error

func (*EngineTest) AcceptedFrontier 

func (e *EngineTest) AcceptedFrontier(nodeID ids.ShortID, requestID uint32, containerIDs []ids.ID) error

func (*EngineTest) Ancestors added in v1.7.4 

func (e *EngineTest) Ancestors(nodeID ids.ShortID, requestID uint32, containers [][]byte) error

func (*EngineTest) AppGossip added in v1.5.3 

func (e *EngineTest) AppGossip(nodeID ids.ShortID, msg []byte) error

func (*EngineTest) AppRequest added in v1.5.3 

func (e *EngineTest) AppRequest(nodeID ids.ShortID, requestID uint32, deadline time.Time, request []byte) error

func (*EngineTest) AppRequestFailed added in v1.5.3 

func (e *EngineTest) AppRequestFailed(nodeID ids.ShortID, requestID uint32) error

func (*EngineTest) AppResponse added in v1.5.3 

func (e *EngineTest) AppResponse(nodeID ids.ShortID, requestID uint32, response []byte) error

func (*EngineTest) Chits 

func (e *EngineTest) Chits(nodeID ids.ShortID, requestID uint32, containerIDs []ids.ID) error

func (*EngineTest) Connected added in v0.8.2 

func (e *EngineTest) Connected(nodeID ids.ShortID, nodeVersion version.Application) error

func (*EngineTest) Context 

func (e *EngineTest) Context() *snow.ConsensusContext

func (*EngineTest) Default 

func (e *EngineTest) Default(cant bool)

func (*EngineTest) Disconnected added in v0.8.2 

func (e *EngineTest) Disconnected(nodeID ids.ShortID) error

func (*EngineTest) Get 

func (e *EngineTest) Get(nodeID ids.ShortID, requestID uint32, containerID ids.ID) error

func (*EngineTest) GetAccepted 

func (e *EngineTest) GetAccepted(nodeID ids.ShortID, requestID uint32, containerIDs []ids.ID) error

func (*EngineTest) GetAcceptedFailed 

func (e *EngineTest) GetAcceptedFailed(nodeID ids.ShortID, requestID uint32) error

func (*EngineTest) GetAcceptedFrontier 

func (e *EngineTest) GetAcceptedFrontier(nodeID ids.ShortID, requestID uint32) error

func (*EngineTest) GetAcceptedFrontierFailed 

func (e *EngineTest) GetAcceptedFrontierFailed(nodeID ids.ShortID, requestID uint32) error

func (*EngineTest) GetAncestors added in v0.8.0 

func (e *EngineTest) GetAncestors(nodeID ids.ShortID, requestID uint32, containerID ids.ID) error

func (*EngineTest) GetAncestorsFailed added in v0.8.0 

func (e *EngineTest) GetAncestorsFailed(nodeID ids.ShortID, requestID uint32) error

func (*EngineTest) GetFailed 

func (e *EngineTest) GetFailed(nodeID ids.ShortID, requestID uint32) error

func (*EngineTest) GetVM added in v1.3.2 

func (e *EngineTest) GetVM() VM

func (*EngineTest) Gossip added in v0.8.0 

func (e *EngineTest) Gossip() error

func (*EngineTest) Halt added in v1.4.0 

func (e *EngineTest) Halt()

func (*EngineTest) HealthCheck added in v1.2.1 

func (e *EngineTest) HealthCheck() (interface{}, error)

func (*EngineTest) Notify 

func (e *EngineTest) Notify(msg Message) error

func (*EngineTest) PullQuery 

func (e *EngineTest) PullQuery(nodeID ids.ShortID, requestID uint32, containerID ids.ID) error

func (*EngineTest) PushQuery 

func (e *EngineTest) PushQuery(nodeID ids.ShortID, requestID uint32, container []byte) error

func (*EngineTest) Put 

func (e *EngineTest) Put(nodeID ids.ShortID, requestID uint32, container []byte) error

func (*EngineTest) QueryFailed 

func (e *EngineTest) QueryFailed(nodeID ids.ShortID, requestID uint32) error

func (*EngineTest) Shutdown 

func (e *EngineTest) Shutdown() error

func (*EngineTest) Start added in v1.7.4 

func (e *EngineTest) Start(startReqID uint32) error

func (*EngineTest) Timeout added in v1.4.4 

func (e *EngineTest) Timeout() error

type FetchSender 

type FetchSender interface {
	// Request that the specified node send the specified container to this
	// node.
	SendGet(nodeID ids.ShortID, requestID uint32, containerID ids.ID)

	// SendGetAncestors requests that node [nodeID] send container [containerID]
	// and its ancestors.
	SendGetAncestors(nodeID ids.ShortID, requestID uint32, containerID ids.ID)

	// Tell the specified node that the container whose ID is [containerID] has
	// body [container].
	SendPut(
		nodeID ids.ShortID,
		requestID uint32,
		containerID ids.ID,
		container []byte,
	)

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

FetchSender defines how a consensus engine sends retrieval messages to other nodes.

type Fetcher added in v0.8.0 

type Fetcher struct {
	// tracks which validators were asked for which containers in which requests
	OutstandingRequests Requests

	// Called when bootstrapping is done on a specific chain
	OnFinished func(lastReqID uint32) error
}

type FrontierSender 

type FrontierSender interface {
	// SendGetAcceptedFrontier requests that every node in [nodeIDs] sends an
	// AcceptedFrontier message.
	SendGetAcceptedFrontier(nodeIDs ids.ShortSet, requestID uint32)

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

FrontierSender defines how a consensus engine sends frontier messages to other nodes.

type Fx 

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

Fx wraps an instance of a feature extension

type GetAcceptedFrontierHandler added in v1.7.4 

type GetAcceptedFrontierHandler 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.
	//
	// 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
}

GetAcceptedFrontierHandler defines how a consensus engine reacts to a get accepted frontier message from another validator. Functions only return fatal errors.

type GetAcceptedHandler added in v1.7.4 

type GetAcceptedHandler 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
}

GetAcceptedHandler defines how a consensus engine reacts to a get accepted message from another validator. Functions only return fatal errors.

type GetAncestorsHandler added in v1.7.4 

type GetAncestorsHandler interface {
	// 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.
	//
	// This engine should respond with an Ancestors message with the same
	// requestID, which contains [containerID] as well as its ancestors. See
	// Ancestors'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
}

GetAncestorsHandler defines how a consensus engine reacts to a get ancestors message from another validator. Functions only return fatal errors.

type GetHandler added in v1.7.4 

type GetHandler 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.
	//
	// 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.
	//
	// 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
}

GetHandler defines how a consensus engine reacts to get message from another validator. Functions only return fatal errors.

type Gossiper added in v0.8.0 

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

Gossiper defines how a consensus engine gossips a container on the accepted frontier to other nodes

type HTTPHandler 

type HTTPHandler struct {
	LockOptions LockOption
	Handler     http.Handler
}

type Haltable added in v1.4.5 

type Haltable interface {
	Halt()
	Halted() bool
}

type Halter added in v1.4.0 

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

func (*Halter) Halt added in v1.4.0 

func (h *Halter) Halt()

func (*Halter) Halted added in v1.4.0 

func (h *Halter) Halted() bool

type Handler 

type Handler interface {
	AllGetsServer
	AcceptedFrontierHandler
	AcceptedHandler
	AncestorsHandler
	PutHandler
	QueryHandler
	ChitsHandler
	AppHandler

	InternalHandler
}

type InternalHandler 

type InternalHandler interface {
	// Notify this engine of peer changes.
	validators.Connector

	// Notify this engine that a registered timeout has fired.
	Timeout() error

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

	// Halt this engine.
	//
	// This function will be called before the environment starts exiting. This
	// function is slightly special, in that it does not expect the chain's
	// context lock to be held before calling this function.
	Halt()

	// 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
}

InternalHandler defines how this consensus engine reacts to messages from other components of this validator. Functions only return fatal errors if they occur.

type LockOption 

type LockOption uint32

LockOption allows the vm to specify their lock option based on their endpoint

type Message 

type Message uint32

Message is an enum of the message types that vms can send to consensus 

const (
	// PendingTxs notifies a consensus engine that
	// its VM has pending transactions
	// (i.e. it would like to add a new block/vertex to consensus)
	PendingTxs Message = iota
	// StopVertex notifies a consensus that it has a pending stop vertex
	StopVertex
)

func (Message) String 

func (msg Message) String() string

type PutHandler added in v1.7.4 

type PutHandler interface {
	// 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.
	Put(
		validatorID ids.ShortID,
		requestID uint32,
		container []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
}

PutHandler defines how a consensus engine reacts to put messages from other validators. Functions only return fatal errors.

func NewNoOpPutHandler added in v1.7.4 

func NewNoOpPutHandler(log logging.Logger) PutHandler

type QueryHandler 

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.
	//
	// 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,
		container []byte,
	) error
}

QueryHandler defines how a consensus engine reacts to query messages from other validators. Functions only return fatal errors.

func NewNoOpQueryHandler added in v1.7.4 

func NewNoOpQueryHandler(log logging.Logger) QueryHandler

type QuerySender 

type QuerySender interface {
	// Request from the specified nodes 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.
	SendPushQuery(
		nodeIDs ids.ShortSet,
		requestID uint32,
		containerID ids.ID,
		container []byte,
	)

	// Request from the specified nodes their preferred frontier, given the
	// existence of the specified container.
	SendPullQuery(nodeIDs ids.ShortSet, requestID uint32, containerID ids.ID)

	// Send chits to the specified node
	SendChits(nodeID ids.ShortID, requestID uint32, votes []ids.ID)
}

QuerySender defines how a consensus engine sends query messages to other nodes.

type Requests added in v0.8.0 

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

Requests tracks pending container messages from a peer.

func (*Requests) Add added in v0.8.0 

func (r *Requests) Add(vdr ids.ShortID, requestID uint32, containerID ids.ID)

Add a request. Assumes that requestIDs are unique. Assumes that containerIDs are only in one request at a time.

func (*Requests) Contains added in v0.8.0 

func (r *Requests) Contains(containerID ids.ID) bool

Contains returns true if there is an outstanding request for the container ID.

func (*Requests) Len added in v0.8.0 

func (r *Requests) Len() int

Len returns the total number of outstanding requests.

func (*Requests) Remove added in v0.8.0 

func (r *Requests) Remove(vdr ids.ShortID, requestID uint32) (ids.ID, bool)

Remove attempts to abandon a requestID sent to a validator. If the request is currently outstanding, the requested ID will be returned along with true. If the request isn't currently outstanding, false will be returned.

func (*Requests) RemoveAny added in v0.8.0 

func (r *Requests) RemoveAny(containerID ids.ID) bool

RemoveAny outstanding requests for the container ID. True is returned if the container ID had an outstanding request.

func (Requests) String added in v1.2.0 

func (r Requests) String() string

type Sender 

type Sender interface {
	FrontierSender
	AcceptedSender
	FetchSender
	QuerySender
	Gossiper
	AppSender
}

Sender defines how a consensus engine sends messages and requests to other validators

type SenderTest 

type SenderTest struct {
	T *testing.T

	CantSendGetAcceptedFrontier, CantSendAcceptedFrontier,
	CantSendGetAccepted, CantSendAccepted,
	CantSendGet, CantSendGetAncestors, CantSendPut, CantSendAncestors,
	CantSendPullQuery, CantSendPushQuery, CantSendChits,
	CantSendGossip,
	CantSendAppRequest, CantSendAppResponse, CantSendAppGossip, CantSendAppGossipSpecific bool

	SendGetAcceptedFrontierF func(ids.ShortSet, uint32)
	SendAcceptedFrontierF    func(ids.ShortID, uint32, []ids.ID)
	SendGetAcceptedF         func(ids.ShortSet, uint32, []ids.ID)
	SendAcceptedF            func(ids.ShortID, uint32, []ids.ID)
	SendGetF                 func(ids.ShortID, uint32, ids.ID)
	SendGetAncestorsF        func(ids.ShortID, uint32, ids.ID)
	SendPutF                 func(ids.ShortID, uint32, ids.ID, []byte)
	SendAncestorsF           func(ids.ShortID, uint32, [][]byte)
	SendPushQueryF           func(ids.ShortSet, uint32, ids.ID, []byte)
	SendPullQueryF           func(ids.ShortSet, uint32, ids.ID)
	SendChitsF               func(ids.ShortID, uint32, []ids.ID)
	SendGossipF              func(ids.ID, []byte)
	SendAppRequestF          func(ids.ShortSet, uint32, []byte) error
	SendAppResponseF         func(ids.ShortID, uint32, []byte) error
	SendAppGossipF           func([]byte) error
	SendAppGossipSpecificF   func(ids.ShortSet, []byte) error
}

SenderTest is a test sender

func (*SenderTest) Default 

func (s *SenderTest) Default(cant bool)

Default set the default callable value to [cant]

func (*SenderTest) SendAccepted added in v1.5.3 

func (s *SenderTest) SendAccepted(validatorID ids.ShortID, requestID uint32, containerIDs []ids.ID)

SendAccepted calls SendAcceptedF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendAcceptedFrontier added in v1.5.3 

func (s *SenderTest) SendAcceptedFrontier(validatorID ids.ShortID, requestID uint32, containerIDs []ids.ID)

SendAcceptedFrontier calls SendAcceptedFrontierF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendAncestors added in v1.7.4 

func (s *SenderTest) SendAncestors(vdr ids.ShortID, requestID uint32, vtxs [][]byte)

SendAncestors calls SendAncestorsF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendAppGossip added in v1.5.3 

func (s *SenderTest) SendAppGossip(appGossipBytes []byte) error

SendAppGossip calls SendAppGossipF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendAppGossipSpecific added in v1.6.2 

func (s *SenderTest) SendAppGossipSpecific(nodeIDs ids.ShortSet, appGossipBytes []byte) error

SendAppGossipSpecific calls SendAppGossipSpecificF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendAppRequest added in v1.5.3 

func (s *SenderTest) SendAppRequest(nodeIDs ids.ShortSet, requestID uint32, appRequestBytes []byte) error

SendAppRequest calls SendAppRequestF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendAppResponse added in v1.5.3 

func (s *SenderTest) SendAppResponse(nodeID ids.ShortID, requestID uint32, appResponseBytes []byte) error

SendAppResponse calls SendAppResponseF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendChits added in v1.5.3 

func (s *SenderTest) SendChits(vdr ids.ShortID, requestID uint32, votes []ids.ID)

SendChits calls SendChitsF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendGet added in v1.5.3 

func (s *SenderTest) SendGet(vdr ids.ShortID, requestID uint32, vtxID ids.ID)

SendGet calls SendGetF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendGetAccepted added in v1.5.3 

func (s *SenderTest) SendGetAccepted(nodeIDs ids.ShortSet, requestID uint32, containerIDs []ids.ID)

SendGetAccepted calls SendGetAcceptedF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendGetAcceptedFrontier added in v1.5.3 

func (s *SenderTest) SendGetAcceptedFrontier(validatorIDs ids.ShortSet, requestID uint32)

SendGetAcceptedFrontier calls SendGetAcceptedFrontierF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendGetAncestors added in v1.5.3 

func (s *SenderTest) SendGetAncestors(validatorID ids.ShortID, requestID uint32, vtxID ids.ID)

SendGetAncestors calls SendGetAncestorsF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendGossip added in v1.5.3 

func (s *SenderTest) SendGossip(containerID ids.ID, container []byte)

SendGossip calls SendGossipF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendPullQuery added in v1.5.3 

func (s *SenderTest) SendPullQuery(vdrs ids.ShortSet, requestID uint32, vtxID ids.ID)

SendPullQuery calls SendPullQueryF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendPushQuery added in v1.5.3 

func (s *SenderTest) SendPushQuery(vdrs ids.ShortSet, requestID uint32, vtxID ids.ID, vtx []byte)

SendPushQuery calls SendPushQueryF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SenderTest) SendPut added in v1.5.3 

func (s *SenderTest) SendPut(vdr ids.ShortID, requestID uint32, vtxID ids.ID, vtx []byte)

SendPut calls SendPutF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

type SharedConfig added in v1.7.4 

type SharedConfig struct {
	// Tracks the last requestID that was used in a request
	RequestID uint32

	// True if RestartBootstrap has been called at least once
	Restarted bool
}

Shared among common.bootstrapper and snowman/avalanche bootstrapper

type Subnet added in v1.2.1 

type Subnet interface {
	// Returns true iff the subnet is done bootstrapping
	IsBootstrapped() bool

	// Bootstrapped marks the named chain as being bootstrapped
	Bootstrapped(chainID ids.ID)
}

Subnet describes the standard interface of a subnet description

type SubnetTest added in v1.2.1 

type SubnetTest struct {
	T *testing.T

	CantIsBootstrapped, CantBootstrapped bool

	IsBootstrappedF func() bool
	BootstrappedF   func(ids.ID)
}

SubnetTest is a test subnet

func (*SubnetTest) Bootstrapped added in v1.2.1 

func (s *SubnetTest) Bootstrapped(chainID ids.ID)

Bootstrapped calls BootstrappedF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail.

func (*SubnetTest) Default added in v1.2.1 

func (s *SubnetTest) Default(cant bool)

Default set the default callable value to [cant]

func (*SubnetTest) IsBootstrapped added in v1.2.1 

func (s *SubnetTest) IsBootstrapped() bool

IsBootstrapped calls IsBootstrappedF if it was initialized. If it wasn't initialized and this function shouldn't be called and testing was initialized, then testing will fail. Defaults to returning false.

type TestVM added in v0.8.0 

type TestVM struct {
	T *testing.T

	CantInitialize, CantSetState,
	CantShutdown, CantCreateHandlers, CantCreateStaticHandlers,
	CantHealthCheck, CantConnected, CantDisconnected, CantVersion,
	CantAppRequest, CantAppResponse, CantAppGossip, CantAppRequestFailed bool

	InitializeF           func(*snow.Context, manager.Manager, []byte, []byte, []byte, chan<- Message, []*Fx, AppSender) error
	SetStateF             func(snow.State) error
	ShutdownF             func() error
	CreateHandlersF       func() (map[string]*HTTPHandler, error)
	CreateStaticHandlersF func() (map[string]*HTTPHandler, error)
	ConnectedF            func(nodeID ids.ShortID, nodeVersion version.Application) error
	DisconnectedF         func(nodeID ids.ShortID) error
	HealthCheckF          func() (interface{}, error)
	AppRequestF           func(nodeID ids.ShortID, requestID uint32, deadline time.Time, msg []byte) error
	AppResponseF          func(nodeID ids.ShortID, requestID uint32, msg []byte) error
	AppGossipF            func(nodeID ids.ShortID, msg []byte) error
	AppRequestFailedF     func(nodeID ids.ShortID, requestID uint32) error
	VersionF              func() (string, error)
}

TestVM is a test vm

func (*TestVM) AppGossip added in v1.5.3 

func (vm *TestVM) AppGossip(nodeID ids.ShortID, msg []byte) error

func (*TestVM) AppRequest added in v1.5.3 

func (vm *TestVM) AppRequest(nodeID ids.ShortID, requestID uint32, deadline time.Time, request []byte) error

func (*TestVM) AppRequestFailed added in v1.5.3 

func (vm *TestVM) AppRequestFailed(nodeID ids.ShortID, requestID uint32) error

func (*TestVM) AppResponse added in v1.5.3 

func (vm *TestVM) AppResponse(nodeID ids.ShortID, requestID uint32, response []byte) error

func (*TestVM) Connected added in v1.4.8 

func (vm *TestVM) Connected(id ids.ShortID, nodeVersion version.Application) error

func (*TestVM) CreateHandlers added in v0.8.0 

func (vm *TestVM) CreateHandlers() (map[string]*HTTPHandler, error)

func (*TestVM) CreateStaticHandlers added in v0.8.0 

func (vm *TestVM) CreateStaticHandlers() (map[string]*HTTPHandler, error)

func (*TestVM) Default added in v0.8.0 

func (vm *TestVM) Default(cant bool)

func (*TestVM) Disconnected added in v1.4.8 

func (vm *TestVM) Disconnected(id ids.ShortID) error

func (*TestVM) HealthCheck added in v1.2.1 

func (vm *TestVM) HealthCheck() (interface{}, error)

func (*TestVM) Initialize added in v0.8.0 

func (vm *TestVM) Initialize(ctx *snow.Context, db manager.Manager, genesisBytes, upgradeBytes, configBytes []byte, msgChan chan<- Message, fxs []*Fx, appSender AppSender) error

func (*TestVM) SetState added in v1.7.5 

func (vm *TestVM) SetState(state snow.State) error

func (*TestVM) Shutdown added in v0.8.0 

func (vm *TestVM) Shutdown() error

func (*TestVM) Version added in v1.4.10 

func (vm *TestVM) Version() (string, error)

type Timer added in v1.4.4 

type Timer interface {
	// RegisterTimeout specifies how much time to delay the next timeout message
	// by. If the subnet has been bootstrapped, the timeout will fire
	// immediately.
	RegisterTimeout(time.Duration)
}

Timer describes the standard interface for specifying a timeout

type TimerTest added in v1.4.4 

type TimerTest struct {
	T *testing.T

	CantRegisterTimout bool

	RegisterTimeoutF func(time.Duration)
}

TimerTest is a test timer

func (*TimerTest) Default added in v1.4.4 

func (t *TimerTest) Default(cant bool)

Default set the default callable value to [cant]

func (*TimerTest) RegisterTimeout added in v1.4.4 

func (t *TimerTest) RegisterTimeout(delay time.Duration)

type VM 

type VM interface {
	AppHandler

	// Returns nil if the VM is healthy.
	// Periodically called and reported via the node's Health API.
	health.Checker

	// Connector represents a handler that is called on connection connect/disconnect
	validators.Connector

	// 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.
	// [dbManager]: The manager of 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,
		dbManager manager.Manager,
		genesisBytes []byte,
		upgradeBytes []byte,
		configBytes []byte,
		toEngine chan<- Message,
		fxs []*Fx,
		appSender AppSender,
	) error

	// SetState communicates to VM its next state it starts
	SetState(state snow.State) error

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

	// Version returns the version of the VM this node is running.
	Version() (string, error)

	// 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, 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, error)
}

VM describes the interface that all consensus VMs must implement

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.