chainntnfs

README

chainntnfs

The chainntnfs package implements a set of interfaces which allow callers to receive notifications in response to specific on-chain events. The set of notifications available include:

• Notifications for each new block connected to the current best chain.
• Notifications once a txid has reached a specified number of confirmations.
• Notifications once a target outpoint (txid:index) has been spent.

These notifications are used within lnd in order to properly handle the workflows for: channel funding, cooperative channel closures, forced channel closures, channel contract breaches, sweeping time-locked outputs, and finally pruning the channel graph.

This package is intentionally general enough to be applicable outside the specific use cases within lnd outlined above. The current sole concrete implementation of the ChainNotifier interface depends on btcd.

Installation and Updating

$ go get -u github.com/lightningnetwork/lnd/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
• type TxConfirmation

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 {
	// Hash is the block hash of the latest blcok to be added to the tip of
	// the main chain.
	Hash *chainhash.Hash

	// Height is the height of the latest block to be added to the tip of
	// the main chain.
	Height int32
}

BlockEpoch represents metadata concerning each new block connected to the main chain.

type BlockEpochEvent

type BlockEpochEvent struct {
	// Epochs is a receive only channel that will be sent upon each time a
	// new block is connected to the end of the main chain.
	Epochs <-chan *BlockEpoch // MUST be buffered.

	// Cancel is a closure that should be executed by the caller in the
	// case that they wish to abandon their registered spend notification.
	Cancel func()
}

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

NOTE: If the caller wishes to cancel their registered block epoch notification, the Cancel closure MUST be called.

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.
	//
	// NOTE: Dispatching notifications to multiple clients subscribed to
	// the same (txid, numConfs) tuple MUST be supported.
	RegisterConfirmationsNtfn(txid *chainhash.Hash, 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.
	//
	// NOTE: Dispatching notifications to multiple clients subscribed to a
	// spend of the same outpoint MUST be supported.
	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 is a channel that will be sent upon once the transaction
	// has been fully confirmed. The struct sent will contain all the
	// details of the channel's confirmation.
	Confirmed chan *TxConfirmation // 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 identifies 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 parameters in order to provide
	// initialization flexibility, thereby accommodating several potential
	// ChainNotifier implementations.
	New func(args ...interface{}) (ChainNotifier, error)
}

NotifierDriver represents a "driver" for a particular interface. A driver is identified 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     *chainhash.Hash
	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 is a receive only channel which will be sent upon once the
	// target outpoint has been spent.
	Spend <-chan *SpendDetail // MUST be buffered.

	// Cancel is a closure that should be executed by the caller in the
	// case that they wish to prematurely abandon their regsitered spend
	// notification.
	Cancel func()
}

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.

NOTE: If the caller wishes to cancel their registered spend notification, the Cancel closure MUST be called.

type TxConfirmation

type TxConfirmation struct {
	// BlockHash is the hash of the block that confirmed the original
	// transition.
	BlockHash *chainhash.Hash

	// BlockHeight is the height of the block in which the transaction was
	// confirmed within.
	BlockHeight uint32

	// TxIndex is the index within the block of the ultimate confirmed
	// transaction.
	TxIndex uint32
}

TxConfirmation carries some additional block-level details of the exact block that specified transactions was confirmed within.