notification

Documentation

Overview

Package notification synchronizes ecrd notifications to any number of handlers. Typical use:

1. Create a Notifier with NewNotifier.
2. Grab ecrd configuration settings with EcrdHandlers.
3. Create an ecrd/rpcclient.Client with the settings from step 2.
4. Add handlers with the Register*Group methods. You can add more than one handler (a "group") at a time. Groups are run sequentially in the order that they are registered, but the handlers within a group are run asynchronously.
5. Set the previous best known block with SetPreviousBlock. By this point, it should be certain that all of the data consumers are synced to the best block.
6. **After all handlers have been added**, start the Notifier with Listen, providing as an argument the ecrd client created in step 3.

Index

• Constants
• func DisableLog()
• func UseLogger(logger slog.Logger)
• type BlockHandler
• type BlockHandlerLite
• type BranchTips
• type ContextualError
  • func (e *ContextualError) Cause() string
  • func (e *ContextualError) Error() string
• type ECRDNode
• type Notifier
  • func NewNotifier(ctx context.Context) *Notifier
  • func (notifier *Notifier) EcrdHandlers() *rpcclient.NotificationHandlers
  • func (notifier *Notifier) Listen(ecrdClient ECRDNode) *ContextualError
  • func (notifier *Notifier) RegisterBlockHandlerGroup(handlers ...BlockHandler)
  • func (notifier *Notifier) RegisterBlockHandlerLiteGroup(handlers ...BlockHandlerLite)
  • func (notifier *Notifier) RegisterReorgHandlerGroup(handlers ...ReorgHandler)
  • func (notifier *Notifier) RegisterTxHandlerGroup(handlers ...TxHandler)
  • func (notifier *Notifier) SetPreviousBlock(prevHash chainhash.Hash, prevHeight uint32)
• type ReorgHandler
• type TxHandler

Constants

const SyncHandlerDeadline = time.Minute * 5

SyncHandlerDeadline is a hard deadline for handlers to finish handling before an error is logged.

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info.

Types

type BlockHandler

type BlockHandler func(*wire.BlockHeader) error

BlockHandler is a function that will be called when ecrd reports a new block.

type BlockHandlerLite

type BlockHandlerLite func(uint32, string) error

BlockHandlerLite is a simpler trigger using only bultin types, also called when ecrd reports a new block.

type BranchTips

type BranchTips struct {
	OldChainHead   chainhash.Hash
	OldChainHeight int32
	NewChainHead   chainhash.Hash
	NewChainHeight int32
}

BranchTips describes the old and new chain tips involved in a reorganization.

type ContextualError

type ContextualError struct {
	RootErr error
	Err     error
}

ContextualError models an error and its root error and is returned by registerNodeNtfnHandlers

func (*ContextualError) Cause

func (e *ContextualError) Cause() string

Cause returns the root error string

func (*ContextualError) Error

func (e *ContextualError) Error() string

type ECRDNode

type ECRDNode interface {
	rpcutils.BlockFetcher
	NotifyBlocks() error
	NotifyNewTransactions(bool) error
	NotifyWinningTickets() error
}

ECRDNode is an interface to wrap a ecrd rpcclient.Client. The interface allows testing with a dummy node.

type Notifier

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

Notifier handles block, tx, and reorg notifications from a ecrd node. Handler functions are registered with the Register*Handlers methods. To start the Notifier, Listen must be called with a ecrd rpcclient.Client only after all handlers are registered.

func NewNotifier

func NewNotifier(ctx context.Context) *Notifier

NewNotifier is the constructor for a Notifier.

func (*Notifier) EcrdHandlers

func (notifier *Notifier) EcrdHandlers() *rpcclient.NotificationHandlers

EcrdHandlers creates a set of handlers to be passed to the ecrd rpcclient.Client as a parameter of its constructor.

func (*Notifier) Listen

func (notifier *Notifier) Listen(ecrdClient ECRDNode) *ContextualError

Listen must be called once, but only after all handlers are registered.

func (*Notifier) RegisterBlockHandlerGroup

func (notifier *Notifier) RegisterBlockHandlerGroup(handlers ...BlockHandler)

RegisterBlockHandlerGroup adds a group of block handlers. Groups are run sequentially in the order they are registered, but the handlers within the group are run asynchronously. Handlers registered with RegisterBlockHandlerGroup are FIFO'd together with handlers registered with RegisterBlockHandlerLiteGroup.

func (*Notifier) RegisterBlockHandlerLiteGroup

func (notifier *Notifier) RegisterBlockHandlerLiteGroup(handlers ...BlockHandlerLite)

RegisterBlockHandlerLiteGroup adds a group of block handlers. Groups are run sequentially in the order they are registered, but the handlers within the group are run asynchronously. This method differs from RegisterBlockHandlerGroup in that the handlers take no arguments, so their packages don't necessarily need to import ecrd/wire. Handlers registered with RegisterBlockHandlerLiteGroup are FIFO'd together with handlers registered with RegisterBlockHandlerGroup.

func (*Notifier) RegisterReorgHandlerGroup

func (notifier *Notifier) RegisterReorgHandlerGroup(handlers ...ReorgHandler)

RegisterReorgHandlerGroup adds a group of reorg handlers. Groups are run sequentially in the order they are registered, but the handlers within the group are run asynchronously.

func (*Notifier) RegisterTxHandlerGroup

func (notifier *Notifier) RegisterTxHandlerGroup(handlers ...TxHandler)

RegisterTxHandlerGroup adds a group of tx handlers. Groups are run sequentially in the order they are registered, but the handlers within the group are run asynchronously.

func (*Notifier) SetPreviousBlock

func (notifier *Notifier) SetPreviousBlock(prevHash chainhash.Hash, prevHeight uint32)

SetPreviousBlock modifies the height and hash of the best block. This data is required to avoid connecting new blocks that are not next in the chain. It is only necessary to call SetPreviousBlock if blocks are connected or disconnected by a mechanism other than (*Notifier).processBlock, which keeps this data up-to-date. For example, signalReorg will use SetPreviousBlock after the reorg is complete.

type ReorgHandler

type ReorgHandler func(*txhelpers.ReorgData) error

ReorgHandler is a function that will be called when ecrd reports a reorg.

type TxHandler

type TxHandler func(*chainjson.TxRawResult) error

TxHandler is a function that will be called when ecrd reports new mempool transactions.