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
txidhas 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 SupportedNotifiers() []string
- func UseLogger(logger btclog.Logger)
- type BlockEpoch
- type BlockEpochEvent
- type ChainNotifier
- type ConcurrentQueue
- type ConfNtfn
- type ConfirmationEvent
- type NotifierDriver
- type SpendDetail
- type SpendEvent
- type TxConfNotifier
- type TxConfirmation
Constants ¶
This section is empty.
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 UseLogger is 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 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.
Types ¶
type BlockEpoch ¶
type BlockEpoch struct {
// Hash is the block hash of the latest block 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. The heightHint
// parameter is provided as a convenience to light clients. The
// heightHint denotes the earliest height in the blockchain in which the
// target txid _could_ have been included in the chain. This can be
// used to bound the search space when checking to see if a
// notification can immediately be dispatched due to historical data.
//
// NOTE: Dispatching notifications to multiple clients subscribed to
// the same (txid, numConfs) tuple MUST be supported.
RegisterConfirmationsNtfn(txid *chainhash.Hash, numConfs,
heightHint uint32) (*ConfirmationEvent, error)
// RegisterSpendNtfn registers an intent to be notified once the target
// outpoint is successfully spent within a transaction. The returned
// SpendEvent will receive a send on the 'Spend' transaction once a
// transaction spending the input is detected on the blockchain. The
// heightHint parameter is provided as a convenience to light clients.
// The heightHint denotes the earliest height in the blockchain in
// which the target output could have been created.
//
// NOTE: If mempool=true is set, then this notification should be
// triggered on a best-effort basis once the transaction is *seen* on
// the network. If mempool=false, it should only be triggered when the
// spending transaction receives a single confirmation.
//
// NOTE: Dispatching notifications to multiple clients subscribed to a
// spend of the same outpoint MUST be supported.
RegisterSpendNtfn(outpoint *wire.OutPoint, heightHint uint32,
mempool bool) (*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 ConcurrentQueue ¶
type ConcurrentQueue struct {
// contains filtered or unexported fields
}
ConcurrentQueue is a concurrent-safe FIFO queue with unbounded capacity. Clients interact with the queue by pushing items into the in channel and popping items from the out channel. There is a goroutine that manages moving items from the in channel to the out channel in the correct order that must be started by calling Start().
func NewConcurrentQueue ¶
func NewConcurrentQueue(bufferSize int) *ConcurrentQueue
NewConcurrentQueue constructs a ConcurrentQueue. The bufferSize parameter is the capacity of the output channel. When the size of the queue is below this threshold, pushes do not incur the overhead of the less efficient overflow structure.
func (*ConcurrentQueue) ChanIn ¶
func (cq *ConcurrentQueue) ChanIn() chan<- interface{}
ChanIn returns a channel that can be used to push new items into the queue.
func (*ConcurrentQueue) ChanOut ¶
func (cq *ConcurrentQueue) ChanOut() <-chan interface{}
ChanOut returns a channel that can be used to pop items from the queue.
func (*ConcurrentQueue) Start ¶
func (cq *ConcurrentQueue) Start()
Start begins a goroutine that manages moving items from the in channel to the out channel. The queue tries to move items directly to the out channel minimize overhead, but if the out channel is full it pushes items to an overflow queue. This must be called before using the queue.
func (*ConcurrentQueue) Stop ¶
func (cq *ConcurrentQueue) Stop()
Stop ends the goroutine that moves items from the in channel to the out channel. This does not clear the queue state, so the queue can be restarted without dropping items.
type ConfNtfn ¶
type ConfNtfn struct {
// TxID is the hash of the transaction for which confirmation notifications
// are requested.
TxID *chainhash.Hash
// NumConfirmations is the number of confirmations after which the
// notification is to be sent.
NumConfirmations uint32
// Event contains references to the channels that the notifications are to
// be sent over.
Event *ConfirmationEvent
// contains filtered or unexported fields
}
ConfNtfn represents a notifier client's request to receive a notification once the target transaction gets sufficient confirmations. The client is asynchronously notified via the ConfirmationEvent channels.
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.
// Updates is a channel that will sent upon, at every incremental
// confirmation, how many confirmations are left to declare the
// transaction as fully confirmed.
Updates chan uint32 // 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, how many confirmations are left for the target txid to be fully confirmed at every new block height, 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 fulfilling 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.
func NewConfirmationEvent ¶
func NewConfirmationEvent(numConfs uint32) *ConfirmationEvent
NewConfirmationEvent constructs a new ConfirmationEvent with newly opened channels.
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 variadic 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 registered 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 TxConfNotifier ¶
type TxConfNotifier struct {
// contains filtered or unexported fields
}
TxConfNotifier is used to register transaction confirmation notifications and dispatch them as the transactions confirm. A client can request to be notified when a particular transaction has sufficient on-chain confirmations (or be notified immediately if the tx already does), and the TxConfNotifier will watch changes to the blockchain in order to satisfy these requests.
func NewTxConfNotifier ¶
func NewTxConfNotifier(startHeight uint32, reorgSafetyLimit uint32) *TxConfNotifier
NewTxConfNotifier creates a TxConfNotifier. The current height of the blockchain is accepted as a parameter.
func (*TxConfNotifier) ConnectTip ¶
func (tcn *TxConfNotifier) ConnectTip(blockHash *chainhash.Hash, blockHeight uint32, txns []*btcutil.Tx) error
ConnectTip handles a new block extending the current chain. This checks each transaction in the block to see if any watched transactions are included. Also, if any watched transactions now have the required number of confirmations as a result of this block being connected, this dispatches notifications.
func (*TxConfNotifier) DisconnectTip ¶
func (tcn *TxConfNotifier) DisconnectTip(blockHeight uint32) error
DisconnectTip handles the tip of the current chain being disconnected during a chain reorganization. If any watched transactions were included in this block, internal structures are updated to ensure a confirmation notification is not sent unless the transaction is included in the new chain.
func (*TxConfNotifier) Register ¶
func (tcn *TxConfNotifier) Register(ntfn *ConfNtfn, txConf *TxConfirmation) error
Register handles a new notification request. The client will be notified when the transaction gets a sufficient number of confirmations on the blockchain. If the transaction has already been included in a block on the chain, the confirmation details must be given as the txConf argument, otherwise it should be nil. If the transaction already has the sufficient number of confirmations, this dispatches the notification immediately.
func (*TxConfNotifier) TearDown ¶
func (tcn *TxConfNotifier) TearDown()
TearDown is to be called when the owner of the TxConfNotifier is exiting. This closes the event channels of all registered notifications that have not been dispatched yet.
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.
Source Files
Directories