tmelink

Documentation

Overview

Package tmelink contains types used by the internals of the github.com/gordian-engine/gordian/tm/tmengine.Engine that need to be exposed outside of the tmengine package. In other words, the types in this package are used to "link" individual components of the engine.

It exists as a separate package to avoid a circular dependency between tmengine and its internal packages.

Index

• type BlockDataArrival
• type LagState
• type LagStatus
  • func (i LagStatus) String() string
• type NetworkViewUpdate
• type ProposedHeaderFetchRequest
• type ProposedHeaderFetcher
• type ReplayedHeaderInternalError
  • func (e ReplayedHeaderInternalError) Error() string
  • func (e ReplayedHeaderInternalError) Unwrap() error
• type ReplayedHeaderOutOfSyncError
  • func (e ReplayedHeaderOutOfSyncError) Error() string
• type ReplayedHeaderRequest
• type ReplayedHeaderResponse
• type ReplayedHeaderValidationError
  • func (e ReplayedHeaderValidationError) Error() string
  • func (e ReplayedHeaderValidationError) Unwrap() error

Types

type BlockDataArrival

type BlockDataArrival struct {
	// The height and round of the arrived block data.
	// The height and round are compared against the state machine's current height and round,
	// and data arriving late or early are safely ignored.
	Height uint64
	Round  uint32

	// The DataID of the proposed block, whose data has arrived.
	ID string
}

BlockDataArrival is shared with the engine's state machine, to indicate that a block's data has arrived.

The mechanism by which block data arrives is driver-dependent; for example, it may be actively fetched upon observing a proposed block, or there may be a subscription interface where the the block data is passively received.

Upon arrival of this data, the driver sends this value on a designated channel so that the consensus strategy may re-evaluate its proposed blocks, now being able to fully evaluate the proposed block with the data.

type LagState

type LagState struct {
	Status LagStatus

	CommittingHeight uint64

	NeedHeight uint64
}

LagState is a value sent from engine internals to the driver, when the engine has an updated belief about whether it is lagging the rest of the network.

LagState is the combination of a LagStatus, an always-preseent committing height, and a sometimes-present "needed" height.

If the Status is LagStatusKnownMissing, then the NeedHeight field will be non-zero, indicating the final needed height to be fully synchronized.

New LagState values are only sent wen the Status field changes. An updated CommittingHeight without a Status change, will not result in a new value being sent.

type LagStatus

type LagStatus uint8

const (
	// At startup, nothing known yet.
	LagStatusInitializing LagStatus = iota

	// We believe we are up to date wtih the network.
	LagStatusUpToDate

	// We think we are behind, but we don't know how many blocks we need yet.
	LagStatusAssumedBehind

	// We know we are missing some range of blocks.
	// This is the only status for which [LagState.NeedHeight] is set.
	LagStatusKnownMissing
)

func (LagStatus) String

func (i LagStatus) String() string

type NetworkViewUpdate

type NetworkViewUpdate struct {
	Committing, Voting, NextRound *tmconsensus.VersionedRoundView

	// The other views are all standard,
	// but this view may be a little less obvious.
	// In the context of the Mirror component of the Engine,
	// as soon as the mirror detects a nil commit for a round,
	// it effectively discards that view and advances the round.
	// In doing so, it risks not distributing the precommits required
	// for all other validators to cross the threshold.
	//
	// In normal operations, one would expect a regular re-broadcast of current state
	// which would eventually bring validators to the same round;
	// but we can instead eagerly distribute the details that caused a round to vote nil.
	NilVotedRound *tmconsensus.VersionedRoundView
}

NetworkViewUpdate is a set of versioned round views, representing the engine's view of the network, that the engine is intended to send to the gossip strategy.

The individual values may be nil during a particular send if the engine has already sent an up-to-date value to the gossip strategy.

type ProposedHeaderFetchRequest

type ProposedHeaderFetchRequest struct {
	// Context associated with the request.
	// Canceling this context will abort the request, if it is still in-flight.
	Ctx context.Context

	// The height to search for the proposed header.
	Height uint64

	// The block hash of the header to search for.
	BlockHash string
}

ProposedHeaderFetchRequest is used to make requests to fetch missed proposed headers.

type ProposedHeaderFetcher

type ProposedHeaderFetcher struct {
	// FetchRequests is the channel for the engine
	// to send requests to fetch a proposed header
	// at a given height and with a given hash.
	//
	// Once a proposed header matching the height and hash has been found,
	// that header is sent to the FetchedProposedHeaders channel.
	//
	// The ProposedHeaderFetchRequest struct has a context field.
	// The context is associated with the fetch for this particular header.
	// Canceling the context will abort any in-progress requests to find the header.
	// If the context is cancelled after the proposed header has been enqueued into FetchedProposedHeaders,
	// there is no effect.
	//
	// A ProposedHeaderFetcher should have an upper limit on the number of outstanding fetch requests.
	// If the number of in-flight requests is at its limit,
	// the send to this channel will block.
	FetchRequests chan<- ProposedHeaderFetchRequest

	// FetchedProposedHeaders is the single channel that sends any header
	// discovered as a result of a call to FetchProposedHeader.
	FetchedProposedHeaders <-chan tmconsensus.ProposedHeader
}

ProposedHeaderFetcher contains the input and output channels to fetch proposed headers. The engine uses this when there are sufficient votes for a proposed header, and the engine does not have the proposed header.

type ReplayedHeaderInternalError

type ReplayedHeaderInternalError struct {
	Err error
}

ReplayedHeaderInternalError indicates an internal error to the engine. Upon receiving this error, the driver may assume the mirror has experienced an unrecoverable error.

func (ReplayedHeaderInternalError) Error

func (e ReplayedHeaderInternalError) Error() string

func (ReplayedHeaderInternalError) Unwrap

func (e ReplayedHeaderInternalError) Unwrap() error

type ReplayedHeaderOutOfSyncError

type ReplayedHeaderOutOfSyncError struct {
	WantHeight, GotHeight uint64
}

ReplayedHeaderOutOfSyncError indicates that the replayed header had an invalid height, either before or after the current voting height.

If many headers are attempting to be replayed concurrently, this may be an expected error type. If the driver is only replaying one block at a time, this likely indicates a critical issue in the driver's logic.

func (ReplayedHeaderOutOfSyncError) Error

func (e ReplayedHeaderOutOfSyncError) Error() string

type ReplayedHeaderRequest

type ReplayedHeaderRequest struct {
	Header tmconsensus.Header
	Proof  tmconsensus.CommitProof

	Resp chan<- ReplayedHeaderResponse
}

ReplayedHeaderRequest is sent from the Driver to the Engine during mirror catchup.

type ReplayedHeaderResponse

type ReplayedHeaderResponse struct {
	Err error
}

ReplayedHeaderResponse is the response to ReplayedHeaderRequest sent from the Engine internals back to the Driver.

If the header was replayed successfully, the Err field is nil.

Otherwise, the error will be of type ReplayedHeaderValidationError, ReplayedHeaderOutOfSyncError, or ReplayedHeaderInternalError.

type ReplayedHeaderValidationError

type ReplayedHeaderValidationError struct {
	Err error
}

ReplayedHeaderValidationError indicates that the engine failed to validate the replayed header,j for example a hash mismatch or insufficient signatures. On this error type, the driver should note that the source of the header may be maliciously constructing headers.

func (ReplayedHeaderValidationError) Error

func (e ReplayedHeaderValidationError) Error() string

func (ReplayedHeaderValidationError) Unwrap

func (e ReplayedHeaderValidationError) Unwrap() error