mirror of https://github.com/poanetwork/gecko.git
updating snowman engine docs
This commit is contained in:
StephenButtolph
parent
5c0b89d5eb
commit
71370efb16
|
|
@ -51,58 +51,140 @@ type FrontierHandler interface {
|
|||
// AcceptedHandler defines how a consensus engine reacts to messages pertaining
|
||||
// to accepted containers from other validators
|
||||
type AcceptedHandler interface {
|
||||
// GetAccepted notifies this consensus engine that it should send the set of
|
||||
// containerIDs that it has accepted from the provided set to the specified
|
||||
// validator
|
||||
// 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.Set)
|
||||
|
||||
// Accepted notifies this consensus engine of a set of accepted containerIDs
|
||||
// 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 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.Set)
|
||||
|
||||
// GetAcceptedFailed notifies this consensus engine that the requested
|
||||
// accepted containers requested from the specified validator should be
|
||||
// considered lost
|
||||
// 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)
|
||||
}
|
||||
|
||||
// FetchHandler defines how a consensus engine reacts to retrieval messages from
|
||||
// other validators
|
||||
type FetchHandler interface {
|
||||
// Get notifies this consensus engine that the specified validator requested
|
||||
// that this engine send the specified container to it
|
||||
// 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 avaliable. Otherwise, the message can be safely
|
||||
// dropped.
|
||||
Get(validatorID ids.ShortID, requestID uint32, containerID ids.ID)
|
||||
|
||||
// Put the container with the specified ID and body.
|
||||
// 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)
|
||||
Put(
|
||||
validatorID ids.ShortID,
|
||||
requestID uint32,
|
||||
containerID ids.ID,
|
||||
container []byte,
|
||||
)
|
||||
|
||||
// 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, requestID, and containerID are assumed to be the same as
|
||||
// those sent in the Get message.
|
||||
GetFailed(validatorID ids.ShortID, requestID uint32, containerID ids.ID)
|
||||
}
|
||||
|
||||
// QueryHandler defines how a consensus engine reacts to query messages from
|
||||
// other validators
|
||||
type QueryHandler interface {
|
||||
// Notify this engine that the specified validator queried it about the
|
||||
// specified container. That is, the validator would like to know whether
|
||||
// this engine prefers the specified container. If the ancestry of the
|
||||
// container is incomplete, or the container is unknown, request the missing
|
||||
// data. Once complete, sends this validator the current preferences.
|
||||
// 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)
|
||||
|
||||
// Notify this engine that the specified validator queried it about the
|
||||
// specified container. That is, the validator would like to know whether
|
||||
// this engine prefers the specified container. If the ancestry of the
|
||||
// container is incomplete, request it. Once complete, sends this validator
|
||||
// the current preferences.
|
||||
PushQuery(validatorID ids.ShortID, requestID uint32, containerID ids.ID, container []byte)
|
||||
// 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,
|
||||
)
|
||||
|
||||
// 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.Set)
|
||||
|
||||
// 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)
|
||||
}
|
||||
|
||||
|
|
@ -110,11 +192,16 @@ type QueryHandler interface {
|
|||
// other components of this validator
|
||||
type InternalHandler interface {
|
||||
// Startup this engine.
|
||||
//
|
||||
// This function will be called once the environment is configured to be
|
||||
// able to run the engine.
|
||||
Startup()
|
||||
|
||||
// Shutdown this engine.
|
||||
//
|
||||
// This function will be called when the environment is exiting.
|
||||
Shutdown()
|
||||
|
||||
// Notify this engine that the vm has sent a message to it.
|
||||
// Notify this engine of a message from the virtual machine.
|
||||
Notify(Message)
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue