headtracker

Documentation

Index

• Constants
• type FinalizedMissingError
  • func (e FinalizedMissingError[BLOCK_HASH]) Error() string
• type HeadBroadcaster
  • func NewHeadBroadcaster[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable](lggr logger.Logger) HeadBroadcaster[H, BLOCK_HASH]
• type HeadHandler
• type HeadListener
  • func NewHeadListener[HTH types.Head[BLOCK_HASH, ID], S chains.Subscription, ID chains.ID, ...](lggr logger.Logger, client CLIENT, config types.Config, ...) HeadListener[HTH, BLOCK_HASH]
• type HeadSaver
• type HeadTrackable
• type HeadTracker
  • func NewHeadTracker[HTH types.Head[BLOCK_HASH, ID], S chains.Subscription, ID chains.ID, ...](lggr logger.Logger, client types.Client[HTH, S, ID, BLOCK_HASH], ...) HeadTracker[HTH, BLOCK_HASH]

Constants

const HeadsBufferSize = 10

HeadsBufferSize - The buffer is used when heads sampling is disabled, to ensure the callback is run for every head

const TrackableCallbackTimeout = 2 * time.Second

Types

type FinalizedMissingError

type FinalizedMissingError[BLOCK_HASH chains.Hashable] struct {
	Finalized, Canonical BLOCK_HASH
}

func (FinalizedMissingError[BLOCK_HASH]) Error

func (e FinalizedMissingError[BLOCK_HASH]) Error() string

type HeadBroadcaster

type HeadBroadcaster[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	services.Service
	BroadcastNewLongestChain(H)
	Subscribe(callback HeadTrackable[H, BLOCK_HASH]) (currentLongestChain H, unsubscribe func())
}

HeadBroadcaster relays new Heads to all subscribers.

func NewHeadBroadcaster

func NewHeadBroadcaster[
	H chains.Head[BLOCK_HASH],
	BLOCK_HASH chains.Hashable,
](
	lggr logger.Logger,
) HeadBroadcaster[H, BLOCK_HASH]

NewHeadBroadcaster creates a new HeadBroadcaster

type HeadHandler

type HeadHandler[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] func(ctx context.Context, header H) error

HeadHandler is a callback that handles incoming heads

type HeadListener

type HeadListener[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	services.Service

	// ListenForNewHeads runs the listen loop (not thread safe)
	ListenForNewHeads(ctx context.Context)

	// ReceivingHeads returns true if the listener is receiving heads (thread safe)
	ReceivingHeads() bool

	// Connected returns true if the listener is connected (thread safe)
	Connected() bool

	// HealthReport returns report of errors within HeadListener
	HealthReport() map[string]error
}

HeadListener is a chain agnostic interface that manages connection of Client that receives heads from the blockchain node

func NewHeadListener

func NewHeadListener[
	HTH types.Head[BLOCK_HASH, ID],
	S chains.Subscription,
	ID chains.ID,
	BLOCK_HASH chains.Hashable,
	CLIENT types.Client[HTH, S, ID, BLOCK_HASH],
](
	lggr logger.Logger,
	client CLIENT,
	config types.Config,
	onSubscription func(context.Context),
	handleNewHead HeadHandler[HTH, BLOCK_HASH],
) HeadListener[HTH, BLOCK_HASH]

type HeadSaver

type HeadSaver[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	// Save updates the latest block number, if indeed the latest, and persists
	// this number in case of reboot.
	Save(ctx context.Context, head H) error
	// Load loads latest heads up to latestFinalized - historyDepth, returns the latest chain.
	Load(ctx context.Context, latestFinalized int64) (H, error)
	// LatestChain returns the block header with the highest number that has been seen, or nil.
	LatestChain() H
	// Chain returns a head for the specified hash, or nil.
	Chain(hash BLOCK_HASH) H
	// MarkFinalized - marks matching block and all it's direct ancestors as finalized
	MarkFinalized(ctx context.Context, latestFinalized H) error
}

HeadSaver is an chain agnostic interface for saving and loading heads Different chains will instantiate generic HeadSaver type with their native Head and BlockHash types.

type HeadTrackable

type HeadTrackable[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	// OnNewLongestChain sends a new head when it becomes available. Subscribers can recursively trace the parent
	// of the head to the finalized block back.
	OnNewLongestChain(ctx context.Context, head H)
}

HeadTrackable is implemented by the core txm to be able to receive head events from any chain. Chain implementations should notify head events to the core txm via this interface.

type HeadTracker

type HeadTracker[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	services.Service
	// Backfill given a head will fill in any missing heads up to latestFinalized
	Backfill(ctx context.Context, headWithChain H) (err error)
	LatestChain() H
	// LatestAndFinalizedBlock - returns latest and latest finalized blocks.
	// NOTE: Returns latest finalized block as is, ignoring the FinalityTagBypass feature flag.
	LatestAndFinalizedBlock(ctx context.Context) (latest, finalized H, err error)
}

HeadTracker holds and stores the block experienced by a particular node in a thread safe manner.

func NewHeadTracker

func NewHeadTracker[
	HTH types.Head[BLOCK_HASH, ID],
	S chains.Subscription,
	ID chains.ID,
	BLOCK_HASH chains.Hashable,
](
	lggr logger.Logger,
	client types.Client[HTH, S, ID, BLOCK_HASH],
	config types.Config,
	htConfig types.HeadTrackerConfig,
	headBroadcaster HeadBroadcaster[HTH, BLOCK_HASH],
	headSaver HeadSaver[HTH, BLOCK_HASH],
	mailMon *mailbox.Monitor,
	getNilHead func() HTH,
) HeadTracker[HTH, BLOCK_HASH]

NewHeadTracker instantiates a new HeadTracker using HeadSaver to persist new block numbers.