chainntnfs: add cross interface implementation tests

This commit refactors the existing chainntnfns package in order to
allow more easily allow integration into the main system, by allowing
one to gain access to a set of end-to-end tests for a particular
ChainNotifier implementation.

In order to achieve this, the existing set of tests for the only
concrete implementation (`BtcdNoitifer`) have been refactored to test
against all “registered” notifier interfaces registered. This is
achieved by creating the concept of a “driver” for each concrete
`ChainNotifer` implementation. Once a the package of a particular
driver is imported, solely for the side effects, the init() method
automatically registers the driver.

Additionally, the documentation in various areas of the package have
been cleaned up a bit.

chainntnfs/btcdnotify/btcd.go

@@ -0,0 +1,378 @@
+package btcdnotify
+
+import (
+	"container/heap"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/lightningnetwork/lnd/chainntnfs"
+	"github.com/roasbeef/btcd/btcjson"
+	"github.com/roasbeef/btcd/wire"
+	"github.com/roasbeef/btcrpcclient"
+	"github.com/roasbeef/btcutil"
+)
+
+const (
+
+	// notifierType uniquely identifies this concrete implementation of the
+	// ChainNotifier interface.
+	notifierType = "btcd"
+)
+
+// BtcdNotifier implements the ChainNotifier interface using btcd's websockets
+// notifications. Multiple concurrent clients are supported. All notifications
+// are achieved via non-blocking sends on client channels.
+type BtcdNotifier struct {
+	started int32 // To be used atomically.
+	stopped int32 // To be used atomically.
+
+	chainConn *btcrpcclient.Client
+
+	notificationRegistry chan interface{}
+
+	// TODO(roasbeef): make map point to slices? Would allow for multiple
+	// clients to listen for same spend. Would we ever need this?
+	spendNotifications map[wire.OutPoint]*spendNotification
+	confNotifications  map[wire.ShaHash]*confirmationsNotification
+	confHeap           *confirmationHeap
+
+	connectedBlockHashes    chan *blockNtfn
+	disconnectedBlockHashes chan *blockNtfn
+	relevantTxs             chan *btcutil.Tx
+
+	wg   sync.WaitGroup
+	quit chan struct{}
+}
+
+// Ensure BtcdNotifier implements the ChainNotifier interface at compile time.
+var _ chainntnfs.ChainNotifier = (*BtcdNotifier)(nil)
+
+// New returns a new BtcdNotifier instance. This function assumes the btcd node
+// detailed in the passed configuration is already running, and
+// willing to accept new websockets clients.
+func New(config *btcrpcclient.ConnConfig) (*BtcdNotifier, error) {
+	notifier := &BtcdNotifier{
+		notificationRegistry: make(chan interface{}),
+
+		spendNotifications: make(map[wire.OutPoint]*spendNotification),
+		confNotifications:  make(map[wire.ShaHash]*confirmationsNotification),
+		confHeap:           newConfirmationHeap(),
+
+		connectedBlockHashes:    make(chan *blockNtfn, 20),
+		disconnectedBlockHashes: make(chan *blockNtfn, 20),
+		relevantTxs:             make(chan *btcutil.Tx, 100),
+
+		quit: make(chan struct{}),
+	}
+
+	ntfnCallbacks := &btcrpcclient.NotificationHandlers{
+		OnBlockConnected:    notifier.onBlockConnected,
+		OnBlockDisconnected: notifier.onBlockDisconnected,
+		OnRedeemingTx:       notifier.onRedeemingTx,
+	}
+
+	// Disable connecting to btcd within the btcrpcclient.New method. We
+	// defer establishing the connection to our .Start() method.
+	config.DisableConnectOnNew = true
+	config.DisableAutoReconnect = false
+	chainConn, err := btcrpcclient.New(config, ntfnCallbacks)
+	if err != nil {
+		return nil, err
+	}
+	notifier.chainConn = chainConn
+
+	return notifier, nil
+}
+
+// Start connects to the running btcd node over websockets, registers for block
+// notifications, and finally launches all related helper goroutines.
+func (b *BtcdNotifier) Start() error {
+	// Already started?
+	if atomic.AddInt32(&b.started, 1) != 1 {
+		return nil
+	}
+
+	// Connect to btcd, and register for notifications on connected, and
+	// disconnected blocks.
+	if err := b.chainConn.Connect(20); err != nil {
+		return err
+	}
+	if err := b.chainConn.NotifyBlocks(); err != nil {
+		return err
+	}
+
+	b.wg.Add(1)
+	go b.notificationDispatcher()
+
+	return nil
+}
+
+// Stop shutsdown the BtcdNotifier.
+func (b *BtcdNotifier) Stop() error {
+	// Already shutting down?
+	if atomic.AddInt32(&b.stopped, 1) != 1 {
+		return nil
+	}
+
+	// Shutdown the rpc client, this gracefully disconnects from btcd, and
+	// cleans up all related resources.
+	b.chainConn.Shutdown()
+
+	close(b.quit)
+	b.wg.Wait()
+
+	// Notify all pending clients of our shutdown by closing the related
+	// notification channels.
+	for _, spendClient := range b.spendNotifications {
+		close(spendClient.spendChan)
+	}
+	for _, confClient := range b.confNotifications {
+		close(confClient.finConf)
+		close(confClient.negativeConf)
+	}
+
+	return nil
+}
+
+// blockNtfn packages a notification of a connected/disconnected block along
+// with its height at the time.
+type blockNtfn struct {
+	sha    *wire.ShaHash
+	height int32
+}
+
+// onBlockConnected implements on OnBlockConnected callback for btcrpcclient.
+func (b *BtcdNotifier) onBlockConnected(hash *wire.ShaHash, height int32, t time.Time) {
+	select {
+	case b.connectedBlockHashes <- &blockNtfn{hash, height}:
+	case <-b.quit:
+	}
+}
+
+// onBlockDisconnected implements on OnBlockDisconnected callback for btcrpcclient.
+func (b *BtcdNotifier) onBlockDisconnected(hash *wire.ShaHash, height int32, t time.Time) {
+	b.onBlockDisconnected(hash, height, t)
+}
+
+// onRedeemingTx implements on OnRedeemingTx callback for btcrpcclient.
+func (b *BtcdNotifier) onRedeemingTx(transaction *btcutil.Tx, details *btcjson.BlockDetails) {
+	select {
+	case b.relevantTxs <- transaction:
+	case <-b.quit:
+	}
+}
+
+// notificationDispatcher is the primary goroutine which handles client
+// notification registrations, as well as notification dispatches.
+func (b *BtcdNotifier) notificationDispatcher() {
+out:
+	for {
+		select {
+		case registerMsg := <-b.notificationRegistry:
+			switch msg := registerMsg.(type) {
+			case *spendNotification:
+				b.spendNotifications[*msg.targetOutpoint] = msg
+			case *confirmationsNotification:
+				chainntnfs.Log.Infof("New confirmations "+
+					"subscription: txid=%v, numconfs=%v",
+					*msg.txid, msg.numConfirmations)
+				b.confNotifications[*msg.txid] = msg
+			}
+		case staleBlockHash := <-b.disconnectedBlockHashes:
+			// TODO(roasbeef): re-orgs
+			//  * second channel to notify of confirmation decrementing
+			//    re-org?
+			//  * notify of negative confirmations
+			fmt.Println(staleBlockHash)
+		case connectedBlock := <-b.connectedBlockHashes:
+			newBlock, err := b.chainConn.GetBlock(connectedBlock.sha)
+			if err != nil {
+				continue
+			}
+
+			chainntnfs.Log.Infof("New block: height=%v, sha=%v",
+				connectedBlock.height, connectedBlock.sha)
+
+			newHeight := connectedBlock.height
+			for _, tx := range newBlock.Transactions() {
+				// Check if the inclusion of this transaction
+				// within a block by itself triggers a block
+				// confirmation threshold, if so send a
+				// notification. Otherwise, place the notification
+				// on a heap to be triggered in the future once
+				// additional confirmations are attained.
+				txSha := tx.Sha()
+				b.checkConfirmationTrigger(txSha, newHeight)
+			}
+
+			// A new block has been connected to the main
+			// chain. Send out any N confirmation notifications
+			// which may have been triggered by this new block.
+			b.notifyConfs(newHeight)
+		case newSpend := <-b.relevantTxs:
+			// First, check if this transaction spends an output
+			// that has an existing spend notification for it.
+			for i, txIn := range newSpend.MsgTx().TxIn {
+				prevOut := txIn.PreviousOutPoint
+
+				// If this transaction indeed does spend an
+				// output which we have a registered notification
+				// for, then create a spend summary, finally
+				// sending off the details to the notification
+				// subscriber.
+				if ntfn, ok := b.spendNotifications[prevOut]; ok {
+					spenderSha := newSpend.Sha()
+					spendDetails := &chainntnfs.SpendDetail{
+						SpentOutPoint: ntfn.targetOutpoint,
+						SpenderTxHash: spenderSha,
+						// TODO(roasbeef): copy tx?
+						SpendingTx:        newSpend.MsgTx(),
+						SpenderInputIndex: uint32(i),
+					}
+
+					ntfn.spendChan <- spendDetails
+					delete(b.spendNotifications, prevOut)
+				}
+			}
+		case <-b.quit:
+			break out
+		}
+	}
+	b.wg.Done()
+}
+
+// notifyConfs examines the current confirmation heap, sending off any
+// notifications which have been triggered by the connection of a new block at
+// newBlockHeight.
+func (b *BtcdNotifier) notifyConfs(newBlockHeight int32) {
+	// If the heap is empty, we have nothing to do.
+	if b.confHeap.Len() == 0 {
+		return
+	}
+
+	// Traverse our confirmation heap. The heap is a
+	// min-heap, so the confirmation notification which requires
+	// the smallest block-height will always be at the top
+	// of the heap. If a confirmation notification is eligible
+	// for triggering, then fire it off, and check if another
+	// is eligible until there are no more eligible entries.
+	nextConf := heap.Pop(b.confHeap).(*confEntry)
+	for nextConf.triggerHeight <= uint32(newBlockHeight) {
+		nextConf.finConf <- newBlockHeight
+
+		if b.confHeap.Len() == 0 {
+			return
+		}
+
+		nextConf = heap.Pop(b.confHeap).(*confEntry)
+	}
+
+	heap.Push(b.confHeap, nextConf)
+}
+
+// checkConfirmationTrigger determines if the passed txSha included at blockHeight
+// triggers any single confirmation notifications. In the event that the txid
+// matches, yet needs additional confirmations, it is added to the confirmation
+// heap to be triggered at a later time.
+// TODO(roasbeef): perhaps lookup, then track by inputs instead?
+func (b *BtcdNotifier) checkConfirmationTrigger(txSha *wire.ShaHash, blockHeight int32) {
+	// If a confirmation notification has been registered
+	// for this txid, then either trigger a notification
+	// event if only a single confirmation notification was
+	// requested, or place the notification on the
+	// confirmation heap for future usage.
+	if confNtfn, ok := b.confNotifications[*txSha]; ok {
+		delete(b.confNotifications, *txSha)
+		if confNtfn.numConfirmations == 1 {
+			chainntnfs.Log.Infof("Dispatching single conf "+
+				"notification, sha=%v, height=%v", txSha,
+				blockHeight)
+			confNtfn.finConf <- blockHeight
+			return
+		}
+
+		// The registered notification requires more
+		// than one confirmation before triggering. So
+		// we create a heapConf entry for this notification.
+		// The heapConf allows us to easily keep track of
+		// which notification(s) we should fire off with
+		// each incoming block.
+		confNtfn.initialConfirmHeight = uint32(blockHeight)
+		finalConfHeight := uint32(confNtfn.initialConfirmHeight + confNtfn.numConfirmations - 1)
+		heapEntry := &confEntry{
+			confNtfn,
+			finalConfHeight,
+		}
+		heap.Push(b.confHeap, heapEntry)
+	}
+}
+
+// spendNotification couples a target outpoint along with the channel used for
+// notifications once a spend of the outpoint has been detected.
+type spendNotification struct {
+	targetOutpoint *wire.OutPoint
+
+	spendChan chan *chainntnfs.SpendDetail
+}
+
+// RegisterSpendNotification registers an intent to be notified once the target
+// outpoint has been spent by a transaction on-chain. Once a spend of the target
+// outpoint has been detected, the details of the spending event will be sent
+// across the 'Spend' channel.
+func (b *BtcdNotifier) RegisterSpendNtfn(outpoint *wire.OutPoint) (*chainntnfs.SpendEvent, error) {
+	if err := b.chainConn.NotifySpent([]*wire.OutPoint{outpoint}); err != nil {
+		return nil, err
+	}
+
+	ntfn := &spendNotification{
+		targetOutpoint: outpoint,
+		spendChan:      make(chan *chainntnfs.SpendDetail, 1),
+	}
+
+	b.notificationRegistry <- ntfn
+
+	return &chainntnfs.SpendEvent{ntfn.spendChan}, nil
+}
+
+// confirmationNotification represents a client's intent to receive a
+// notification once the target txid reaches numConfirmations confirmations.
+type confirmationsNotification struct {
+	txid *wire.ShaHash
+
+	initialConfirmHeight uint32
+	numConfirmations     uint32
+
+	finConf      chan int32
+	negativeConf chan int32 // TODO(roasbeef): re-org funny business
+}
+
+// RegisterConfirmationsNotification registers a notification with BtcdNotifier
+// which will be triggered once the txid reaches numConfs number of
+// confirmations.
+func (b *BtcdNotifier) RegisterConfirmationsNtfn(txid *wire.ShaHash,
+	numConfs uint32) (*chainntnfs.ConfirmationEvent, error) {
+
+	ntfn := &confirmationsNotification{
+		txid:             txid,
+		numConfirmations: numConfs,
+		finConf:          make(chan int32, 1),
+		negativeConf:     make(chan int32, 1),
+	}
+
+	b.notificationRegistry <- ntfn
+
+	return &chainntnfs.ConfirmationEvent{
+		Confirmed:    ntfn.finConf,
+		NegativeConf: ntfn.negativeConf,
+	}, nil
+}
+
+// RegisterBlockEpochNtfn returns a BlockEpochEvent which subscribes the
+// caller to receive notificationsm, of each new block connected to the main
+// chain.
+func (b *BtcdNotifier) RegisterBlockEpochNtfn(targetHeight int32) (*chainntnfs.BlockEpochEvent, error) {
+	// TODO(roasbeef): implement
+	return nil, nil
+}

chainntnfs/btcdnotify/confheap.go

@@ -0,0 +1,54 @@
+package btcdnotify
+
+// confEntry represents an entry in the min-confirmation heap. .
+type confEntry struct {
+	*confirmationsNotification
+
+	triggerHeight uint32
+}
+
+// confirmationHeap is a list of confEntries sorted according to nearest
+// "confirmation" height.Each entry within the min-confirmation heap is sorted
+// according to the smallest dleta from the current blockheight to the
+// triggerHeight of the next entry confirmationHeap
+type confirmationHeap struct {
+	items []*confEntry
+}
+
+// newConfirmationHeap returns a new confirmationHeap with zero items.
+func newConfirmationHeap() *confirmationHeap {
+	var confItems []*confEntry
+	return &confirmationHeap{confItems}
+}
+
+// Len returns the number of items in the priority queue. It is part of the
+// heap.Interface implementation.
+func (c *confirmationHeap) Len() int { return len(c.items) }
+
+// Less returns whether the item in the priority queue with index i should sort
+// before the item with index j. It is part of the heap.Interface implementation.
+func (c *confirmationHeap) Less(i, j int) bool {
+	return c.items[i].triggerHeight < c.items[j].triggerHeight
+}
+
+// Swap swaps the items at the passed indices in the priority queue. It is
+// part of the heap.Interface implementation.
+func (c *confirmationHeap) Swap(i, j int) {
+	c.items[i], c.items[j] = c.items[j], c.items[i]
+}
+
+// Push pushes the passed item onto the priority queue. It is part of the
+// heap.Interface implementation.
+func (c *confirmationHeap) Push(x interface{}) {
+	c.items = append(c.items, x.(*confEntry))
+}
+
+// Pop removes the highest priority item (according to Less) from the priority
+// queue and returns it.  It is part of the heap.Interface implementation.
+func (c *confirmationHeap) Pop() interface{} {
+	n := len(c.items)
+	x := c.items[n-1]
+	c.items[n-1] = nil
+	c.items = c.items[0 : n-1]
+	return x
+}

chainntnfs/btcdnotify/driver.go

@@ -0,0 +1,40 @@
+package btcdnotify
+
+import (
+	"fmt"
+
+	"github.com/lightningnetwork/lnd/chainntnfs"
+	"github.com/roasbeef/btcrpcclient"
+)
+
+// createNewNotifier creates a new instance of the ChainNotifier interface
+// implemented by BtcdNotifier.
+func createNewNotifier(args ...interface{}) (chainntnfs.ChainNotifier, error) {
+	if len(args) != 1 {
+		return nil, fmt.Errorf("incorrect number of arguments to .New(...), "+
+			"expected 1, instead passed %v", len(args))
+	}
+
+	config, ok := args[0].(*btcrpcclient.ConnConfig)
+	if !ok {
+		return nil, fmt.Errorf("first argument to btcdnotifier.New is " +
+			"incorrect, expected a *btcrpcclient.ConnConfig")
+	}
+
+	return New(config)
+}
+
+// init registers a driver for the BtcdNotifier concrete implementation of the
+// chainntnfs.ChainNotifier interface.
+func init() {
+	// Register the driver.
+	notifier := &chainntnfs.NotifierDriver{
+		NotifierType: notifierType,
+		New:          createNewNotifier,
+	}
+
+	if err := chainntnfs.RegisterNotifier(notifier); err != nil {
+		panic(fmt.Sprintf("failed to register notifier driver '%s': %v",
+			notifierType, err))
+	}
+}

chainntnfs/interface.go

@@ -0,0 +1,182 @@
+package chainntnfs
+
+import (
+	"fmt"
+	"sync"
+
+	"github.com/roasbeef/btcd/wire"
+)
+
+// 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.
+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(targetHeight int32) (*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
+}
+
+// TODO(roasbeef): ln channels should request spend ntfns for counterparty's
+// inputs to funding tx also, consider channel closed if funding tx re-org'd
+// out and inputs double spent.
+
+// TODO(roasbeef): all chans should be receive only.
+
+// 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 ConfirmationEvent struct {
+	Confirmed chan int32 // MUST be buffered.
+	// TODO(roasbeef): all goroutines on ln channel updates should also
+	// have a struct chan that's closed if funding gets re-org out. Need
+	// to sync, to request another confirmation event ntfn, then re-open
+	// channel after confs.
+
+	NegativeConf chan int32 // MUST be buffered.
+}
+
+// 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 SpendDetail struct {
+	SpentOutPoint     *wire.OutPoint
+	SpenderTxHash     *wire.ShaHash
+	SpendingTx        *wire.MsgTx
+	SpenderInputIndex uint32
+	SpendingHeight    int32
+}
+
+// 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.
+type SpendEvent struct {
+	Spend chan *SpendDetail // MUST be buffered.
+}
+
+// BlockEpoch represents meta-data concerning each new block connected to the
+// main chain.
+type BlockEpoch struct {
+	Height int32
+	Hash   *wire.ShaHash
+}
+
+// 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 BlockEpochEvent struct {
+	Epochs chan *BlockEpoch // MUST be buffered.
+}
+
+// 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.
+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)
+}
+
+var (
+	notifiers   = make(map[string]*NotifierDriver)
+	registerMtx sync.Mutex
+)
+
+// RegisteredNotifiers returns a slice of all currently registered notifiers.
+//
+// NOTE: This function is safe for concurrent access.
+func RegisteredNotifiers() []*NotifierDriver {
+	registerMtx.Lock()
+	defer registerMtx.Unlock()
+
+	drivers := make([]*NotifierDriver, 0, len(notifiers))
+	for _, driver := range notifiers {
+		drivers = append(drivers, driver)
+	}
+
+	return drivers
+}
+
+// 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 RegisterNotifier(driver *NotifierDriver) error {
+	registerMtx.Lock()
+	defer registerMtx.Unlock()
+
+	if _, ok := notifiers[driver.NotifierType]; ok {
+		return fmt.Errorf("notifier already registered")
+	}
+
+	notifiers[driver.NotifierType] = driver
+
+	return nil
+}
+
+// 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 SupportedNotifiers() []string {
+	registerMtx.Lock()
+	defer registerMtx.Unlock()
+
+	supportedNotifiers := make([]string, 0, len(notifiers))
+	for driverName := range notifiers {
+		supportedNotifiers = append(supportedNotifiers, driverName)
+	}
+
+	return supportedNotifiers
+}

chainntnfs/interface_test.go

@@ -0,0 +1,342 @@
+package chainntnfs_test
+
+import (
+	"bytes"
+	"testing"
+	"time"
+
+	"github.com/lightningnetwork/lnd/chainntnfs"
+	_ "github.com/lightningnetwork/lnd/chainntnfs/btcdnotify"
+
+	"github.com/roasbeef/btcd/btcec"
+	"github.com/roasbeef/btcd/chaincfg"
+	"github.com/roasbeef/btcd/rpctest"
+	"github.com/roasbeef/btcd/txscript"
+	"github.com/roasbeef/btcd/wire"
+	"github.com/roasbeef/btcutil"
+)
+
+var (
+	testPrivKey = []byte{
+		0x81, 0xb6, 0x37, 0xd8, 0xfc, 0xd2, 0xc6, 0xda,
+		0x63, 0x59, 0xe6, 0x96, 0x31, 0x13, 0xa1, 0x17,
+		0xd, 0xe7, 0x95, 0xe4, 0xb7, 0x25, 0xb8, 0x4d,
+		0x1e, 0xb, 0x4c, 0xfd, 0x9e, 0xc5, 0x8c, 0xe9,
+	}
+
+	netParams       = &chaincfg.SimNetParams
+	privKey, pubKey = btcec.PrivKeyFromBytes(btcec.S256(), testPrivKey)
+	addrPk, _       = btcutil.NewAddressPubKey(pubKey.SerializeCompressed(),
+		netParams)
+	testAddr = addrPk.AddressPubKeyHash()
+)
+
+func getTestTxId(miner *rpctest.Harness) (*wire.ShaHash, error) {
+	script, err := txscript.PayToAddrScript(testAddr)
+	if err != nil {
+		return nil, err
+	}
+
+	outputs := []*wire.TxOut{&wire.TxOut{2e8, script}}
+	return miner.CoinbaseSpend(outputs)
+}
+
+func testSingleConfirmationNotification(miner *rpctest.Harness,
+	notifier chainntnfs.ChainNotifier, t *testing.T) {
+
+	// We'd like to test the case of being notified once a txid reaches
+	// a *single* confirmation.
+	//
+	// So first, let's send some coins to "ourself", obtainig a txid.
+	// We're spending from a coinbase output here, so we use the dedicated
+	// function.
+
+	txid, err := getTestTxId(miner)
+	if err != nil {
+		t.Fatalf("unable to create test addr: %v", err)
+	}
+
+	// Now that we have a txid, register a confirmation notiication with
+	// the chainntfn source.
+	numConfs := uint32(1)
+	confIntent, err := notifier.RegisterConfirmationsNtfn(txid, numConfs)
+	if err != nil {
+		t.Fatalf("unable to register ntfn: %v", err)
+	}
+
+	// Now generate a single block, the transaction should be included which
+	// should trigger a notification event.
+	if _, err := miner.Node.Generate(1); err != nil {
+		t.Fatalf("unable to generate single block: %v", err)
+	}
+
+	confSent := make(chan int32)
+	go func() {
+		confSent <- <-confIntent.Confirmed
+	}()
+
+	select {
+	case <-confSent:
+		break
+	case <-time.After(2 * time.Second):
+		t.Fatalf("confirmation notification never received")
+	}
+}
+
+func testMultiConfirmationNotification(miner *rpctest.Harness,
+	notifier chainntnfs.ChainNotifier, t *testing.T) {
+
+	// We'd like to test the case of being notified once a txid reaches
+	// N confirmations, where N > 1.
+	//
+	// Again, we'll begin by creating a fresh transaction, so we can obtain a fresh txid.
+	txid, err := getTestTxId(miner)
+	if err != nil {
+		t.Fatalf("unable to create test addr: %v", err)
+	}
+
+	numConfs := uint32(6)
+	confIntent, err := notifier.RegisterConfirmationsNtfn(txid, numConfs)
+	if err != nil {
+		t.Fatalf("unable to register ntfn: %v", err)
+	}
+
+	// Now generate a six blocks. The transaction should be included in the
+	// first block, which will be built upon by the other 5 blocks.
+	if _, err := miner.Node.Generate(6); err != nil {
+		t.Fatalf("unable to generate single block: %v", err)
+	}
+
+	confSent := make(chan int32)
+	go func() {
+		confSent <- <-confIntent.Confirmed
+	}()
+
+	select {
+	case <-confSent:
+		break
+	case <-time.After(2 * time.Second):
+		t.Fatalf("confirmation notification never received")
+	}
+}
+
+func testBatchConfirmationNotification(miner *rpctest.Harness,
+	notifier chainntnfs.ChainNotifier, t *testing.T) {
+
+	// We'd like to test a case of serving notifiations to multiple
+	// clients, each requesting to be notified once a txid receives
+	// various numbers of confirmations.
+	confSpread := [6]uint32{1, 2, 3, 6, 20, 22}
+	confIntents := make([]*chainntnfs.ConfirmationEvent, len(confSpread))
+
+	// Create a new txid spending miner coins for each confirmation entry
+	// in confSpread, we collect each conf intent into a slice so we can
+	// verify they're each notified at the proper number of confirmations
+	// below.
+	for i, numConfs := range confSpread {
+		txid, err := getTestTxId(miner)
+		if err != nil {
+			t.Fatalf("unable to create test addr: %v", err)
+		}
+		confIntent, err := notifier.RegisterConfirmationsNtfn(txid, numConfs)
+		if err != nil {
+			t.Fatalf("unable to register ntfn: %v", err)
+		}
+		confIntents[i] = confIntent
+	}
+
+	// Now, for each confirmation intent, generate the delta number of blocks
+	// needed to trigger the confirmation notification. A goroutine is
+	// spawned in order to verify the proper notification is triggered.
+	for i, numConfs := range confSpread {
+		var blocksToGen uint32
+
+		// If this is the last instance, manually index to generate the
+		// proper block delta in order to avoid a panic.
+		if i == len(confSpread)-1 {
+			blocksToGen = confSpread[len(confSpread)-1] - confSpread[len(confSpread)-2]
+		} else {
+			blocksToGen = confSpread[i+1] - confSpread[i]
+		}
+
+		// Generate the number of blocks necessary to trigger this
+		// current confirmation notification.
+		if _, err := miner.Node.Generate(blocksToGen); err != nil {
+			t.Fatalf("unable to generate single block: %v", err)
+		}
+
+		confSent := make(chan int32)
+		go func() {
+			confSent <- <-confIntents[i].Confirmed
+		}()
+
+		select {
+		case <-confSent:
+			continue
+		case <-time.After(2 * time.Second):
+			t.Fatalf("confirmation notification never received: %v", numConfs)
+		}
+	}
+}
+
+func testSpendNotification(miner *rpctest.Harness,
+	notifier chainntnfs.ChainNotifier, t *testing.T) {
+
+	// We'd like to test the spend notifiations for all
+	// ChainNotifier concrete implemenations.
+	//
+	// To do so, we first create a new output to our test target
+	// address.
+	txid, err := getTestTxId(miner)
+	if err != nil {
+		t.Fatalf("unable to create test addr: %v", err)
+	}
+
+	// Mine a single block which should include that txid above.
+	if _, err := miner.Node.Generate(1); err != nil {
+		t.Fatalf("unable to generate single block: %v", err)
+	}
+
+	// Now that we have the txid, fetch the transaction itself.
+	wrappedTx, err := miner.Node.GetRawTransaction(txid)
+	if err != nil {
+		t.Fatalf("unable to get new tx: %v", err)
+	}
+	tx := wrappedTx.MsgTx()
+
+	// Locate the output index sent to us. We need this so we can
+	// construct a spending txn below.
+	outIndex := -1
+	var pkScript []byte
+	for i, txOut := range tx.TxOut {
+		if bytes.Contains(txOut.PkScript, testAddr.ScriptAddress()) {
+			pkScript = txOut.PkScript
+			outIndex = i
+			break
+		}
+	}
+	if outIndex == -1 {
+		t.Fatalf("unable to locate new output")
+	}
+
+	// Now that we've found the output index, register for a spentness
+	// notification for the newly created output.
+	outpoint := wire.NewOutPoint(txid, uint32(outIndex))
+	spentIntent, err := notifier.RegisterSpendNtfn(outpoint)
+	if err != nil {
+		t.Fatalf("unable to register for spend ntfn: %v", err)
+	}
+
+	// Next, create a new transaction spending that output.
+	spendingTx := wire.NewMsgTx()
+	spendingTx.AddTxIn(&wire.TxIn{
+		PreviousOutPoint: *outpoint,
+	})
+	spendingTx.AddTxOut(&wire.TxOut{
+		Value:    1e8,
+		PkScript: pkScript,
+	})
+	sigScript, err := txscript.SignatureScript(spendingTx, 0, pkScript,
+		txscript.SigHashAll, privKey, true)
+	if err != nil {
+		t.Fatalf("unable to sign tx: %v", err)
+	}
+	spendingTx.TxIn[0].SignatureScript = sigScript
+
+	// Broadcast our spending transaction.
+	spenderSha, err := miner.Node.SendRawTransaction(spendingTx, true)
+	if err != nil {
+		t.Fatalf("unable to brodacst tx: %v", err)
+	}
+
+	// Now we mine a single block, which should include our spend. The
+	// notification should also be sent off.
+	if _, err := miner.Node.Generate(1); err != nil {
+		t.Fatalf("unable to generate single block: %v", err)
+	}
+
+	spentNtfn := make(chan *chainntnfs.SpendDetail)
+	go func() {
+		spentNtfn <- <-spentIntent.Spend
+	}()
+
+	select {
+	case ntfn := <-spentNtfn:
+		// We've received the spend nftn. So now verify all the fields
+		// have been set properly.
+		if ntfn.SpentOutPoint != outpoint {
+			t.Fatalf("ntfn includes wrong output, reports %v instead of %v",
+				ntfn.SpentOutPoint, outpoint)
+		}
+		if !bytes.Equal(ntfn.SpenderTxHash.Bytes(), spenderSha.Bytes()) {
+			t.Fatalf("ntfn includes wrong spender tx sha, reports %v intead of %v",
+				ntfn.SpenderTxHash.Bytes(), spenderSha.Bytes())
+		}
+		if ntfn.SpenderInputIndex != 0 {
+			t.Fatalf("ntfn includes wrong spending input index, reports %v, should be %v",
+				ntfn.SpenderInputIndex, 0)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatalf("spend ntfn never received")
+	}
+}
+
+var ntfnTests = []func(node *rpctest.Harness, notifier chainntnfs.ChainNotifier, t *testing.T){
+	testSingleConfirmationNotification,
+	testMultiConfirmationNotification,
+	testBatchConfirmationNotification,
+	testSpendNotification,
+}
+
+// TestInterfaces tests all registered interfaces with a unified set of tests
+// which excersie each of the required methods found within the ChainNotifier
+// interface.
+//
+// NOTE: In the future, when additional implementations of the ChainNotifier
+// interface have been implemented, in order to ensure the new concrete
+// implementation is automatically tested, two steps must be undertaken. First,
+// one needs add a "non-captured" (_) import from the new sub-package. This
+// import should trigger an init() method within the package which registeres
+// the interface. Second, an additional case in the switch within the main loop
+// below needs to be added which properly initializes the interface.
+func TestInterfaces(t *testing.T) {
+	// Initialize the harness around a btcd node which will serve as our
+	// dedicated miner to generate blocks, cause re-orgs, etc. We'll set up
+	// this node with a chain length of 125, so we have plentyyy of BTC to
+	// play around with.
+	miner, err := rpctest.New(netParams, nil, nil)
+	if err != nil {
+		t.Fatalf("unable to create mining node: %v", err)
+	}
+	defer miner.TearDown()
+	if err := miner.SetUp(true, 25); err != nil {
+		t.Fatalf("unable to set up mining node: %v", err)
+	}
+
+	rpcConfig := miner.RPCConfig()
+
+	var notifier chainntnfs.ChainNotifier
+	for _, notifierDriver := range chainntnfs.RegisteredNotifiers() {
+		notifierType := notifierDriver.NotifierType
+
+		switch notifierType {
+		case "btcd":
+			notifier, err = notifierDriver.New(&rpcConfig)
+			if err != nil {
+				t.Fatalf("unable to create %v notifier: %v",
+					notifierType, err)
+			}
+		}
+
+		if err := notifier.Start(); err != nil {
+			t.Fatalf("unable to start notifier %v: %v",
+				notifierType, err)
+		}
+
+		for _, ntfnTest := range ntfnTests {
+			ntfnTest(miner, notifier, t)
+		}
+
+		notifier.Stop()
+	}
+}

chainntnfs/log.go

@@ -0,0 +1,54 @@
+package chainntnfs
+
+import (
+	"errors"
+	"io"
+
+	"github.com/btcsuite/btclog"
+)
+
+// 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.
+var Log btclog.Logger
+
+// The default amount of logging is none.
+func init() {
+	DisableLog()
+}
+
+// DisableLog disables all library log output.  Logging output is disabled
+// by default until either UseLogger or SetLogWriter are called.
+func DisableLog() {
+	Log = btclog.Disabled
+}
+
+// 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.
+func UseLogger(logger btclog.Logger) {
+	Log = logger
+}
+
+// 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 SetLogWriter(w io.Writer, level string) error {
+	if w == nil {
+		return errors.New("nil writer")
+	}
+
+	lvl, ok := btclog.LogLevelFromString(level)
+	if !ok {
+		return errors.New("invalid log level")
+	}
+
+	l, err := btclog.NewLoggerFromWriter(w, lvl)
+	if err != nil {
+		return err
+	}
+
+	UseLogger(l)
+	return nil
+}