chainntnfs

Documentation

Index

• Variables
• func DisableLog()
• func RegisterNotifier(driver *NotifierDriver) error
• func SetLogWriter(w io.Writer, level string) error
• func SupportedNotifiers() []string
• func UseLogger(logger btclog.Logger)
• type BlockEpoch
• type BlockEpochEvent
• type ChainNotifier
• type ConfirmationEvent
• type NotifierDriver
  • func RegisteredNotifiers() []*NotifierDriver
• type SpendDetail
• type SpendEvent

Variables

var Log btclog.Logger

log is a logger that is initialized with no output filters. This means the package will not perform any logging by default until the caller requests it.

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func RegisterNotifier

func RegisterNotifier(driver *NotifierDriver) error

RegisterNotifier registers a NotifierDriver which is capable of driving a concrete ChainNotifier interface. In the case that this driver has already been registered, an error is returned.

NOTE: This function is safe for concurrent access.

func SetLogWriter

func SetLogWriter(w io.Writer, level string) error

SetLogWriter uses a specified io.Writer to output package logging info. This allows a caller to direct package logging output without needing a dependency on seelog. If the caller is also using btclog, UseLogger should be used instead.

func SupportedNotifiers

func SupportedNotifiers() []string

SupportedNotifiers returns a slice of strings that represent the database drivers that have been registered and are therefore supported.

NOTE: This function is safe for concurrent access.

func UseLogger

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type BlockEpoch

type BlockEpoch struct {
	Height int32
	Hash   *wire.ShaHash
}

BlockEpoch represents meta-data concerning each new block connected to the main chain.

type BlockEpochEvent

type BlockEpochEvent struct {
	Epochs chan *BlockEpoch // MUST be buffered.
}

BlockEpochEvent encapsulates an on-going stream of block epoch notifications. Its only field 'Epoochs' will be sent upon for each new block connected to the main-chain.

type ChainNotifier

type ChainNotifier interface {
	// RegisterConfirmationsNtfn registers an intent to be notified once
	// txid reaches numConfs confirmations. The returned ConfirmationEvent
	// should properly notify the client once the specified number of
	// confirmations has been reached for the txid, as well as if the
	// original tx gets re-org'd out of the mainchain.
	RegisterConfirmationsNtfn(txid *wire.ShaHash, numConfs uint32) (*ConfirmationEvent, error)

	// RegisterSpendNtfn registers an intent to be notified once the target
	// outpoint is succesfully spent within a confirmed transaction. The
	// returned SpendEvent will receive a send on the 'Spend' transaction
	// once a transaction spending the input is detected on the blockchain.
	//
	// NOTE: This notifications should be triggered once the transaction is
	// *seen* on the network, not when it has received a single confirmation.
	RegisterSpendNtfn(outpoint *wire.OutPoint) (*SpendEvent, error)

	// RegisterBlockEpochNtfn registers an intent to be notified of each
	// new block connected to the tip of the main chain. The returned
	// BlockEpochEvent struct contains a channel which will be sent upon
	// for each new block discovered.
	RegisterBlockEpochNtfn() (*BlockEpochEvent, error)

	// Start the ChainNotifier. Once started, the implementation should be
	// ready, and able to receive notification registrations from clients.
	Start() error

	// Stops the concrete ChainNotifier. Once stopped, the ChainNotifier
	// should disallow any future requests from potential clients.
	// Additionally, all pending client notifications will be cancelled
	// by closing the related channels on the *Event's.
	Stop() error
}

ChainNotifier represents a trusted source to receive notifications concerning targeted events on the Bitcoin blockchain. The interface specification is intentionally general in order to support a wide array of chain notification implementations such as: btcd's websockets notifications, Bitcoin Core's ZeroMQ notifications, various Bitcoin API services, Electrum servers, etc.

Concrete implementations of ChainNotifier should be able to support multiple concurrent client requests, as well as multiple concurrent notification events. TODO(roasbeef): all events should have a Cancel() method to free up the resource

type ConfirmationEvent

type ConfirmationEvent struct {
	Confirmed chan int32 // MUST be buffered.

	NegativeConf chan int32 // MUST be buffered.
}

ConfirmationEvent encapsulates a confirmation notification. With this struct, callers can be notified of: the instance the target txid reaches the targeted number of confirmations, and also in the event that the original txid becomes disconnected from the blockchain as a result of a re-org.

Once the txid reaches the specified number of confirmations, the 'Confirmed' channel will be sent upon fufulling the notification.

If the event that the original transaction becomes re-org'd out of the main chain, the 'NegativeConf' will be sent upon with a value representing the depth of the re-org.

type NotifierDriver

type NotifierDriver struct {
	// NotifierType is a string which uniquely identifes the ChainNotifier
	// that this driver, drives.
	NotifierType string

	// New creates a new instance of a concrete ChainNotifier
	// implementation given a variadic set up arguments. The function takes
	// a varidaic number of interface paramters in order to provide
	// initialization flexibility, thereby accomodating several potential
	// ChainNotifier implementations.
	New func(args ...interface{}) (ChainNotifier, error)
}

NotifierDriver represents a "driver" for a particular interface. A driver is indentified by a globally unique string identifier along with a 'New()' method which is responsible for initializing a particular ChainNotifier concrete implementation.

func RegisteredNotifiers

func RegisteredNotifiers() []*NotifierDriver

RegisteredNotifiers returns a slice of all currently registered notifiers.

NOTE: This function is safe for concurrent access.

type SpendDetail

type SpendDetail struct {
	SpentOutPoint     *wire.OutPoint
	SpenderTxHash     *wire.ShaHash
	SpendingTx        *wire.MsgTx
	SpenderInputIndex uint32
	SpendingHeight    int32
}

SpendDetail contains details pertaining to a spent output. This struct itself is the spentness notification. It includes the original outpoint which triggered the notification, the hash of the transaction spending the output, the spending transaction itself, and finally the input index which spent the target output.

type SpendEvent

type SpendEvent struct {
	Spend chan *SpendDetail // MUST be buffered.
}

SpendEvent encapsulates a spentness notification. Its only field 'Spend' will be sent upon once the target output passed into RegisterSpendNtfn has been spent on the blockchain.