notification

Documentation

Overview

Package notification syncronizes bitumd notifications to any number of handlers. Typical use:

1. Create a Notifier with NewNotifier.
2. Grab bitumd configuration settings with BitumdHandlers.
3. Create an bitumd/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 bitumd client created in step 3.

Index

• Constants
• func DisableLog()
• func UseLogger(logger slog.Logger)
• type BITUMDNode
• type BlockHandler
• type BlockHandlerLite
• type BranchTips
• type ContextualError
  • func (e *ContextualError) Cause() string
  • func (e *ContextualError) Error() string
• type Notifier
  • func NewNotifier(ctx context.Context) *Notifier
  • func (notifier *Notifier) BitumdHandlers() *rpcclient.NotificationHandlers
  • func (notifier *Notifier) Listen(bitumdClient BITUMDNode) *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

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 BITUMDNode

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

BITUMDNode is an interface to wrap a bitumd rpcclient.Client. The interface allows testing with a dummy node.

type BlockHandler

type BlockHandler func(*wire.BlockHeader) error

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

type BlockHandlerLite

type BlockHandlerLite func(uint32, string) error

BlockHandlerLite is a simpler trigger using only bultin types, also called when bitumd 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 Notifier

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

Notifier handles block, tx, and reorg notifications from a bitumd node. Handler functions are registered with the Register*Handlers methods. To start the Notifier, Listen must be called with a bitumd 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) BitumdHandlers

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

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

func (*Notifier) Listen

func (notifier *Notifier) Listen(bitumdClient BITUMDNode) *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 bitumd/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 bitumd reports a reorg.

type TxHandler

type TxHandler func(*bitumjson.TxRawResult) error

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