tmengine

Documentation

Overview

Package tmengine contains the Engine and its supporting types which are used to actually create a consensus engine.

Index

• type Engine
  • func New(ctx context.Context, log *slog.Logger, opts ...Opt) (*Engine, error)
  • func (e *Engine) HandlePrecommitProofs(ctx context.Context, p tmconsensus.PrecommitSparseProof) tmconsensus.HandleVoteProofsResult
  • func (e *Engine) HandlePrevoteProofs(ctx context.Context, p tmconsensus.PrevoteSparseProof) tmconsensus.HandleVoteProofsResult
  • func (e *Engine) HandleProposedHeader(ctx context.Context, ph tmconsensus.ProposedHeader) tmconsensus.HandleProposedHeaderResult
  • func (e *Engine) Wait()
• type LinearTimeoutStrategy
  • func (s LinearTimeoutStrategy) CommitWaitTimeout(_ uint64, round uint32) time.Duration
  • func (s LinearTimeoutStrategy) PrecommitDelayTimeout(_ uint64, round uint32) time.Duration
  • func (s LinearTimeoutStrategy) PrevoteDelayTimeout(_ uint64, round uint32) time.Duration
  • func (s LinearTimeoutStrategy) ProposalTimeout(_ uint64, round uint32) time.Duration
• type Metrics
• type Mirror
  • func NewMirror(ctx context.Context, log *slog.Logger, opts ...Opt) (Mirror, error)
• type Opt
  • func WithActionStore(s tmstore.ActionStore) Opt
  • func WithAssertEnv(assertEnv gassert.Env) Opt
  • func WithBlockDataArrivalChannel(ch <-chan tmelink.BlockDataArrival) Opt
  • func WithBlockFinalizationChannel(ch chan<- tmdriver.FinalizeBlockRequest) Opt
  • func WithCommittedHeaderStore(s tmstore.CommittedHeaderStore) Opt
  • func WithCommonMessageSignatureProofScheme(s gcrypto.CommonMessageSignatureProofScheme) Opt
  • func WithConsensusStrategy(cs tmconsensus.ConsensusStrategy) Opt
  • func WithFinalizationStore(s tmstore.FinalizationStore) Opt
  • func WithGenesis(g *tmconsensus.ExternalGenesis) Opt
  • func WithGossipStrategy(gs tmgossip.Strategy) Opt
  • func WithHashScheme(h tmconsensus.HashScheme) Opt
  • func WithInitChainChannel(ch chan<- tmdriver.InitChainRequest) Opt
  • func WithInternalRoundTimer(rt roundTimer) Opt
  • func WithLagStateChannel(ch chan<- tmelink.LagState) Opt
  • func WithMetricsChannel(ch chan<- Metrics) Opt
  • func WithMirrorStore(s tmstore.MirrorStore) Opt
  • func WithReplayedHeaderRequestChannel(ch <-chan tmelink.ReplayedHeaderRequest) Opt
  • func WithRoundStore(s tmstore.RoundStore) Opt
  • func WithSignatureScheme(s tmconsensus.SignatureScheme) Opt
  • func WithSigner(s tmconsensus.Signer) Opt
  • func WithStateMachineStore(s tmstore.StateMachineStore) Opt
  • func WithTimeoutStrategy(ctx context.Context, s TimeoutStrategy) Opt
  • func WithValidatorStore(s tmstore.ValidatorStore) Opt
  • func WithWatchdog(wd *gwatchdog.Watchdog) Opt
• type TimeoutStrategy

Types

type Engine

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

Engine is the entrypoint to a working consensus engine.

func New

func New(ctx context.Context, log *slog.Logger, opts ...Opt) (*Engine, error)

func (*Engine) HandlePrecommitProofs

func (e *Engine) HandlePrecommitProofs(ctx context.Context, p tmconsensus.PrecommitSparseProof) tmconsensus.HandleVoteProofsResult

func (*Engine) HandlePrevoteProofs

func (e *Engine) HandlePrevoteProofs(ctx context.Context, p tmconsensus.PrevoteSparseProof) tmconsensus.HandleVoteProofsResult

func (*Engine) HandleProposedHeader

func (e *Engine) HandleProposedHeader(ctx context.Context, ph tmconsensus.ProposedHeader) tmconsensus.HandleProposedHeaderResult

func (*Engine) Wait

func (e *Engine) Wait()

type LinearTimeoutStrategy

type LinearTimeoutStrategy struct {
	ProposalBase      time.Duration
	ProposalIncrement time.Duration

	PrevoteDelayBase      time.Duration
	PrevoteDelayIncrement time.Duration

	PrecommitDelayBase      time.Duration
	PrecommitDelayIncrement time.Duration

	CommitWaitBase      time.Duration
	CommitWaitIncrement time.Duration
}

LinearTimeoutStrategy provides timeout durations that increase linearly with round increases. If any of the provided values are zero, reasonable defaults are used.

func (LinearTimeoutStrategy) CommitWaitTimeout

func (s LinearTimeoutStrategy) CommitWaitTimeout(_ uint64, round uint32) time.Duration

func (LinearTimeoutStrategy) PrecommitDelayTimeout

func (s LinearTimeoutStrategy) PrecommitDelayTimeout(_ uint64, round uint32) time.Duration

func (LinearTimeoutStrategy) PrevoteDelayTimeout

func (s LinearTimeoutStrategy) PrevoteDelayTimeout(_ uint64, round uint32) time.Duration

func (LinearTimeoutStrategy) ProposalTimeout

func (s LinearTimeoutStrategy) ProposalTimeout(_ uint64, round uint32) time.Duration

type Metrics

type Metrics = tmemetrics.Metrics

Metrics are the metrics for subsystems within the Engine. The fields in this type should not be considered stable and may change without notice between releases.

The type alias is somewhat unfortunate, but the alternative would be creating yet another package...

type Mirror

type Mirror interface {
	tmconsensus.FineGrainedConsensusHandler

	// Wait blocks until the Mirror is finished.
	// Stop the mirror by canceling the context passed to [NewMirror].
	Wait()
}

The Mirror follows the state of the active validators on the network, replicating the blocks and votes they produce.

The Mirror is normally an internal component of a full Engine including a state machine connected to a user-defined application. However, in some cases, it may be desirable to run a Mirror by itself for the sake of tracking the state of the rest of the network.

func NewMirror

func NewMirror(ctx context.Context, log *slog.Logger, opts ...Opt) (Mirror, error)

type Opt

type Opt func(*Engine, *tmstate.StateMachineConfig) error

Opt is an option for the Engine. The underlying function signature for Opt is subject to change at any time. Only Opt values returned by With* functions may be considered stable values.

func WithActionStore

func WithActionStore(s tmstore.ActionStore) Opt

WithActionStore sets the engine's action store. This option is required if using a non-nil signer.

func WithAssertEnv

func WithAssertEnv(assertEnv gassert.Env) Opt

WithAssertEnv sets the assert environment on the engine ands its subcomponents. It is safe to exclude this option in builds that do not have the "debug" build tag. However, in debug builds, omitting this option will cause a runtime panic.

func WithBlockDataArrivalChannel

func WithBlockDataArrivalChannel(ch <-chan tmelink.BlockDataArrival) Opt

WithAppDataArrivalChannel sets the channel that the engine reads from in order to refresh the consensus strategy, in the event that application data is received later than a proposed block is received.

func WithBlockFinalizationChannel

func WithBlockFinalizationChannel(ch chan<- tmdriver.FinalizeBlockRequest) Opt

WithBlockFinalizationChannel sets the channel that the engine sends on when a block is due to be finalized. The application must receive from this channel. This option is required.

func WithCommittedHeaderStore

func WithCommittedHeaderStore(s tmstore.CommittedHeaderStore) Opt

WithCommittedHeaderStore sets the engine's committed header store. This option is required.

func WithCommonMessageSignatureProofScheme

func WithCommonMessageSignatureProofScheme(s gcrypto.CommonMessageSignatureProofScheme) Opt

WithCommonMessageSignatureProofScheme sets the engine's common message signature proof scheme. This option is required.

func WithConsensusStrategy

func WithConsensusStrategy(cs tmconsensus.ConsensusStrategy) Opt

WithConsensusStrategy sets the engine's consensus strategy. This option is required.

func WithFinalizationStore

func WithFinalizationStore(s tmstore.FinalizationStore) Opt

WithFinalizationStore sets the engine's finalization store. This option is required.

func WithGenesis

func WithGenesis(g *tmconsensus.ExternalGenesis) Opt

WithGenesis sets the engine's ExternalGenesis. This option is required.

func WithGossipStrategy

func WithGossipStrategy(gs tmgossip.Strategy) Opt

WithGossipStrategy sets the engine's gossip strategy. This option is required.

func WithHashScheme

func WithHashScheme(h tmconsensus.HashScheme) Opt

WithHashScheme sets the engine's hash scheme. This option is required.

func WithInitChainChannel

func WithInitChainChannel(ch chan<- tmdriver.InitChainRequest) Opt

WithInitChainChannel sets the init chain channel for the engine to send on. This option is only required if the chain has not yet been initialized.

func WithInternalRoundTimer

func WithInternalRoundTimer(rt roundTimer) Opt

WithInternalRoundTimer sets the round timer, an internal type to the engine's state machine. This is only intended for testing.

Non-test usage should call WithTimeoutStrategy to use an exported type.

func WithLagStateChannel

func WithLagStateChannel(ch chan<- tmelink.LagState) Opt

WithLagStateChannel sets the channel that the engine writes to when its lag state changes. This option is not required, but is strongly recommended.

func WithMetricsChannel

func WithMetricsChannel(ch chan<- Metrics) Opt

WithMetricsChannel sets the channel where the engine emits metrics for its subsystems.

func WithMirrorStore

func WithMirrorStore(s tmstore.MirrorStore) Opt

WithMirrorStore sets the engine's mirror store. This option is required.

func WithReplayedHeaderRequestChannel

func WithReplayedHeaderRequestChannel(ch <-chan tmelink.ReplayedHeaderRequest) Opt

WithReplayedHeaderRequestChannel sets the channel that the engine reads replayed header requests from. This option is not required, but is strongly recommended.

func WithRoundStore

func WithRoundStore(s tmstore.RoundStore) Opt

WithRoundStore sets the engine's round store. This option is required.

func WithSignatureScheme

func WithSignatureScheme(s tmconsensus.SignatureScheme) Opt

WithSignatureScheme sets the engine's signature scheme. This option is required.

func WithSigner

func WithSigner(s tmconsensus.Signer) Opt

WithSigner sets the engine's signer. If omitted or set to nil, the engine will never actively participate in consensus; it will only operate as an observer.

func WithStateMachineStore

func WithStateMachineStore(s tmstore.StateMachineStore) Opt

func WithTimeoutStrategy

func WithTimeoutStrategy(ctx context.Context, s TimeoutStrategy) Opt

WithTimeoutStrategy sets the timeout strategy for calculating state machine timeouts during consensus. The context value controls the lifecycle of the timer.

func WithValidatorStore

func WithValidatorStore(s tmstore.ValidatorStore) Opt

WithValidatorStore sets the engine's validator store. This option is required.

func WithWatchdog

func WithWatchdog(wd *gwatchdog.Watchdog) Opt

WithWatchdog sets the engine's watchdog, propagating it through subsystems of the engine. This option is required. For tests, the caller may use gwatchdog.NewNopWatchdog to avoid creating unnecessary goroutines.

type TimeoutStrategy

type TimeoutStrategy interface {
	ProposalTimeout(height uint64, round uint32) time.Duration
	PrevoteDelayTimeout(height uint64, round uint32) time.Duration
	PrecommitDelayTimeout(height uint64, round uint32) time.Duration
	CommitWaitTimeout(height uint64, round uint32) time.Duration
}

TimeoutStrategy informs the state machine how to calculate timeouts. While the individual methods all include a height parameter, the height will rarely if ever be used in calculating the timeout duration. The height is more intended as a mechanism to coordinate changing the timeouts after a certain height.