chainntfns: document the ChainNotifier interface

chainntfs/chainntfs.go

@@ -2,21 +2,36 @@ package chainntnfs
 
 import "github.com/btcsuite/btcd/wire"
 
-// ChainNotifier ...
-// TODO(roasbeef): finish
-//  * multiple backends for interface
-//   * btcd - websockets
-//   * core - rpc polling or ZeroMQ
-//   * direct p2p
-//   * random bitcoin API?
-//   * electrum?
-//   * SPV bloomfilter
-//   * other stuff maybe...
+// 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.
 	RegisterSpendNtfn(outpoint *wire.OutPoint) (*SpendEvent, 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
 }
 
@@ -24,7 +39,17 @@ type ChainNotifier interface {
 // inputs to funding tx also, consider channel closed if funding tx re-org'd
 // out and inputs double spent.
 
-// ConfirmationEvent ...
+// 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 struct{} // MUST be buffered.
 
@@ -36,7 +61,11 @@ type ConfirmationEvent struct {
 	NegativeConf chan int32 // MUST be buffered.
 }
 
-// SpendDetail ...
+// 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
@@ -44,7 +73,9 @@ type SpendDetail struct {
 	SpenderInputIndex uint32
 }
 
-// SpendEvent ...
+// 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.
 }