headtracker

Documentation

Index

• Constants
• type HeadBroadcaster
  • func NewHeadBroadcaster[H types.Head[BLOCK_HASH], BLOCK_HASH types.Hashable](lggr logger.Logger) HeadBroadcaster[H, BLOCK_HASH]
• type HeadListener
  • func NewHeadListener[HTH htrktypes.Head[BLOCK_HASH, ID], S types.Subscription, ID types.ID, ...](lggr logger.Logger, client CLIENT, config htrktypes.Config, ...) HeadListener[HTH, BLOCK_HASH]
• type HeadSaver
• type HeadTrackable
• type HeadTracker
  • func NewHeadTracker[HTH htrktypes.Head[BLOCK_HASH, ID], S types.Subscription, ID types.ID, ...](lggr logger.Logger, client htrktypes.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 HeadBroadcaster

type HeadBroadcaster[H types.Head[BLOCK_HASH], BLOCK_HASH types.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 types.Head[BLOCK_HASH],
	BLOCK_HASH types.Hashable,
](
	lggr logger.Logger,
) HeadBroadcaster[H, BLOCK_HASH]

NewHeadBroadcaster creates a new HeadBroadcaster

type HeadListener

type HeadListener[H types.Head[BLOCK_HASH], BLOCK_HASH types.Hashable] interface {
	// ListenForNewHeads kicks off the listen loop (not thread safe)
	// done() must be executed upon leaving ListenForNewHeads()
	ListenForNewHeads(onSubscribe func(), handleNewHead headHandler[H, BLOCK_HASH], done func())

	// 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 htrktypes.Head[BLOCK_HASH, ID],
	S types.Subscription,
	ID types.ID,
	BLOCK_HASH types.Hashable,
	CLIENT htrktypes.Client[HTH, S, ID, BLOCK_HASH],
](
	lggr logger.Logger,
	client CLIENT,
	config htrktypes.Config,
	chStop chan struct{},
) HeadListener[HTH, BLOCK_HASH]

type HeadSaver

type HeadSaver[H types.Head[BLOCK_HASH], BLOCK_HASH types.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 types.Head[BLOCK_HASH], BLOCK_HASH types.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 types.Head[BLOCK_HASH], BLOCK_HASH types.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 htrktypes.Head[BLOCK_HASH, ID],
	S types.Subscription,
	ID types.ID,
	BLOCK_HASH types.Hashable,
](
	lggr logger.Logger,
	client htrktypes.Client[HTH, S, ID, BLOCK_HASH],
	config htrktypes.Config,
	htConfig htrktypes.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.