Documentation ¶
Index ¶
- Variables
- func BackEnds() []string
- type BitcoindClient
- func (c *BitcoindClient) BackEnd() string
- func (c *BitcoindClient) BlockStamp() (*am.BlockStamp, error)
- func (c *BitcoindClient) FilterBlocks(req *FilterBlocksRequest) (*FilterBlocksResponse, error)
- func (c *BitcoindClient) GetBestBlock() (*chainhash.Hash, int32, error)
- func (c *BitcoindClient) GetBlock(hash *chainhash.Hash) (*wire.Block, error)
- func (c *BitcoindClient) GetBlockHash(height int64) (*chainhash.Hash, error)
- func (c *BitcoindClient) GetBlockHeader(hash *chainhash.Hash) (*wire.BlockHeader, error)
- func (c *BitcoindClient) GetBlockHeaderVerbose(hash *chainhash.Hash) (*btcjson.GetBlockHeaderVerboseResult, error)
- func (c *BitcoindClient) GetBlockHeight(hash *chainhash.Hash) (int32, error)
- func (c *BitcoindClient) GetBlockVerbose(hash *chainhash.Hash) (*btcjson.GetBlockVerboseResult, error)
- func (c *BitcoindClient) GetRawTransactionVerbose(hash *chainhash.Hash) (*btcjson.TxRawResult, error)
- func (c *BitcoindClient) GetTxOut(txHash *chainhash.Hash, index uint32, mempool bool) (*btcjson.GetTxOutResult, error)
- func (c *BitcoindClient) LoadTxFilter(reset bool, filters ...interface{}) (e error)
- func (c *BitcoindClient) Notifications() <-chan interface{}
- func (c *BitcoindClient) NotifyBlocks() (e error)
- func (c *BitcoindClient) NotifyReceived(addrs []btcaddr.Address) (e error)
- func (c *BitcoindClient) NotifySpent(outPoints []*wire.OutPoint) (e error)
- func (c *BitcoindClient) NotifyTx(txids []chainhash.Hash) (e error)
- func (c *BitcoindClient) Rescan(blockHash *chainhash.Hash, addresses []btcaddr.Address, ...) (e error)
- func (c *BitcoindClient) RescanBlocks(blockHashes []chainhash.Hash) ([]btcjson.RescannedBlock, error)
- func (c *BitcoindClient) SendRawTransaction(tx *wire.MsgTx, allowHighFees bool) (*chainhash.Hash, error)
- func (c *BitcoindClient) SetBirthday(t time.Time)
- func (c *BitcoindClient) Start() (e error)
- func (c *BitcoindClient) Stop()
- func (c *BitcoindClient) WaitForShutdown()
- type BitcoindConn
- type BlockConnected
- type BlockDisconnected
- type BlockFilterer
- type ClientConnected
- type ConcurrentQueue
- type FilterBlocksRequest
- type FilterBlocksResponse
- type FilteredBlockConnected
- type Interface
- type RPCClient
- func (c *RPCClient) BackEnd() string
- func (c *RPCClient) BlockStamp() (*waddrmgr.BlockStamp, error)
- func (c *RPCClient) FilterBlocks(req *FilterBlocksRequest) (*FilterBlocksResponse, error)
- func (c *RPCClient) Notifications() <-chan interface{}
- func (c *RPCClient) POSTClient() (*rpcclient.Client, error)
- func (c *RPCClient) Rescan(startHash *chainhash.Hash, addrs []btcaddr.Address, ...) (e error)
- func (c *RPCClient) Start() (e error)
- func (c *RPCClient) Stop()
- func (c *RPCClient) WaitForShutdown()
- type RelevantTx
- type RescanFinished
- type RescanProgress
Constants ¶
This section is empty.
Variables ¶
var ( // ErrBitcoindClientShuttingDown is an error returned when we attempt to receive a notification for a specific item // and the bitcoind client is in the middle of shutting down. ErrBitcoindClientShuttingDown = errors.New("client is shutting down") )
var F, E, W, I, D, T log.LevelPrinter = log.GetLogPrinterSet(subsystem)
Functions ¶
Types ¶
type BitcoindClient ¶
type BitcoindClient struct {
// contains filtered or unexported fields
}
BitcoindClient represents a persistent client connection to a bitcoind server for information regarding the current best block chain.
func (*BitcoindClient) BackEnd ¶
func (c *BitcoindClient) BackEnd() string
BackEnd returns the name of the driver.
func (*BitcoindClient) BlockStamp ¶
func (c *BitcoindClient) BlockStamp() (*am.BlockStamp, error)
BlockStamp returns the latest block notified by the client, or an error if the client has been shut down.
func (*BitcoindClient) FilterBlocks ¶
func (c *BitcoindClient) FilterBlocks( req *FilterBlocksRequest, ) (*FilterBlocksResponse, error)
FilterBlocks scans the blocks contained in the FilterBlocksRequest for any addresses of interest. Each block will be fetched and filtered sequentially, returning a FilterBlocksResponse for the first block containing a matching address. If no matches are found in the range of blocks requested, the returned response will be nil.
NOTE: This is part of the chainclient.Interface interface.
func (*BitcoindClient) GetBestBlock ¶
func (c *BitcoindClient) GetBestBlock() (*chainhash.Hash, int32, error)
GetBestBlock returns the highest block known to bitcoind.
func (*BitcoindClient) GetBlockHash ¶
func (c *BitcoindClient) GetBlockHash(height int64) (*chainhash.Hash, error)
GetBlockHash returns a block hash from the height.
func (*BitcoindClient) GetBlockHeader ¶
func (c *BitcoindClient) GetBlockHeader( hash *chainhash.Hash, ) (*wire.BlockHeader, error)
GetBlockHeader returns a block header from the hash.
func (*BitcoindClient) GetBlockHeaderVerbose ¶
func (c *BitcoindClient) GetBlockHeaderVerbose( hash *chainhash.Hash, ) (*btcjson.GetBlockHeaderVerboseResult, error)
GetBlockHeaderVerbose returns a block header from the hash.
func (*BitcoindClient) GetBlockHeight ¶
func (c *BitcoindClient) GetBlockHeight(hash *chainhash.Hash) (int32, error)
GetBlockHeight returns the height for the hash, if known, or returns an error.
func (*BitcoindClient) GetBlockVerbose ¶
func (c *BitcoindClient) GetBlockVerbose( hash *chainhash.Hash, ) (*btcjson.GetBlockVerboseResult, error)
GetBlockVerbose returns a verbose block from the hash.
func (*BitcoindClient) GetRawTransactionVerbose ¶
func (c *BitcoindClient) GetRawTransactionVerbose( hash *chainhash.Hash, ) (*btcjson.TxRawResult, error)
GetRawTransactionVerbose returns a transaction from the tx hash.
func (*BitcoindClient) GetTxOut ¶
func (c *BitcoindClient) GetTxOut( txHash *chainhash.Hash, index uint32, mempool bool, ) (*btcjson.GetTxOutResult, error)
GetTxOut returns a txout from the outpoint info provided.
func (*BitcoindClient) LoadTxFilter ¶
func (c *BitcoindClient) LoadTxFilter( reset bool, filters ...interface{}, ) (e error)
LoadTxFilter uses the given filters to what we should match transactions against to determine if they are relevant to the client. The reset argument is used to reset the current filters.
The current filters supported are of the following types:
[]util.Address []wire.OutPoint []*wire.OutPoint map[wire.OutPoint]util.Address []chainhash.Hash []*chainhash.Hash
func (*BitcoindClient) Notifications ¶
func (c *BitcoindClient) Notifications() <-chan interface{}
Notifications returns a channel to retrieve notifications from.
NOTE: This is part of the chainclient.Interface interface.
func (*BitcoindClient) NotifyBlocks ¶
func (c *BitcoindClient) NotifyBlocks() (e error)
NotifyBlocks allows the chain backend to notify the caller whenever a block is connected or disconnected.
NOTE: This is part of the chainclient.Interface interface.
func (*BitcoindClient) NotifyReceived ¶
func (c *BitcoindClient) NotifyReceived(addrs []btcaddr.Address) (e error)
NotifyReceived allows the chain backend to notify the caller whenever a transaction pays to any of the given addresses.
NOTE: This is part of the chainclient.Interface interface.
func (*BitcoindClient) NotifySpent ¶
func (c *BitcoindClient) NotifySpent(outPoints []*wire.OutPoint) (e error)
NotifySpent allows the chain backend to notify the caller whenever a transaction spends any of the given outpoints.
func (*BitcoindClient) NotifyTx ¶
func (c *BitcoindClient) NotifyTx(txids []chainhash.Hash) (e error)
NotifyTx allows the chain backend to notify the caller whenever any of the given transactions confirm within the chain.
func (*BitcoindClient) Rescan ¶
func (c *BitcoindClient) Rescan( blockHash *chainhash.Hash, addresses []btcaddr.Address, outPoints map[wire.OutPoint]btcaddr.Address, ) (e error)
Rescan rescans from the block with the given hash until the current block, after adding the passed addresses and outpoints to the client's watch list.
func (*BitcoindClient) RescanBlocks ¶
func (c *BitcoindClient) RescanBlocks( blockHashes []chainhash.Hash, ) ([]btcjson.RescannedBlock, error)
RescanBlocks rescans any blocks passed, returning only the blocks that matched as []json.BlockDetails.
func (*BitcoindClient) SendRawTransaction ¶
func (c *BitcoindClient) SendRawTransaction( tx *wire.MsgTx, allowHighFees bool, ) (*chainhash.Hash, error)
SendRawTransaction sends a raw transaction via bitcoind.
func (*BitcoindClient) SetBirthday ¶
func (c *BitcoindClient) SetBirthday(t time.Time)
SetBirthday sets the birthday of the bitcoind rescan client.
NOTE: This should be done before the client has been started in order for it to properly carry its duties.
func (*BitcoindClient) Start ¶
func (c *BitcoindClient) Start() (e error)
Start initializes the bitcoind rescan client using the backing bitcoind connection and starts all goroutines necessary in order to process rescans and ZMQ notifications.
NOTE: This is part of the chainclient.Interface interface.
func (*BitcoindClient) Stop ¶
func (c *BitcoindClient) Stop()
Stop stops the bitcoind rescan client from processing rescans and ZMQ notifications.
NOTE: This is part of the chainclient.Interface interface.
func (*BitcoindClient) WaitForShutdown ¶
func (c *BitcoindClient) WaitForShutdown()
WaitForShutdown blocks until the client has finished disconnecting and all handlers have exited.
NOTE: This is part of the chainclient.Interface interface.
type BitcoindConn ¶
type BitcoindConn struct {
// contains filtered or unexported fields
}
BitcoindConn represents a persistent client connection to a bitcoind node that listens for events read from a ZMQ connection.
func NewBitcoindConn ¶
func NewBitcoindConn( chainParams *chaincfg.Params, host, user, pass, zmqBlockHost, zmqTxHost string, zmqPollInterval time.Duration, ) (*BitcoindConn, error)
NewBitcoindConn creates a client connection to the node described by the host string. The connection is not established immediately, but must be done using the Start method. If the remote node does not operate on the same bitcoin network as described by the passed chain parameters, the connection will be disconnected.
func (*BitcoindConn) AddClient ¶
func (c *BitcoindConn) AddClient(client *BitcoindClient)
AddClient adds a client to the set of active rescan clients of the current chain connection. This allows the connection to include the specified client in its notification delivery.
NOTE: This function is safe for concurrent access.
func (*BitcoindConn) NewBitcoindClient ¶
func (c *BitcoindConn) NewBitcoindClient() *BitcoindClient
NewBitcoindClient returns a bitcoind client using the current bitcoind connection. This allows us to share the same connection using multiple clients.
func (*BitcoindConn) RemoveClient ¶
func (c *BitcoindConn) RemoveClient(id uint64)
RemoveClient removes the client with the given ID from the set of active rescan clients. Once removed, the client will no longer receive block and transaction notifications from the chain connection.
NOTE: This function is safe for concurrent access.
func (*BitcoindConn) Start ¶
func (c *BitcoindConn) Start() (e error)
Start attempts to establish a RPC and ZMQ connection to a bitcoind node. If successful, a goroutine is spawned to read events from the ZMQ connection. It's possible for this function to fail due to a limited number of connection attempts. This is done to prevent waiting forever on the connection to be established in the case that the node is down.
func (*BitcoindConn) Stop ¶
func (c *BitcoindConn) Stop()
Stop terminates the RPC and ZMQ connection to a bitcoind node and removes any active rescan clients.
type BlockConnected ¶
BlockConnected is a notification for a newly-attached block to the best chain.
type BlockDisconnected ¶
BlockDisconnected is a notifcation that the block described by the BlockStamp was reorganized out of the best chain.
type BlockFilterer ¶
type BlockFilterer struct { // Params specifies the chain netparams of the current network. Params *chaincfg.Params // ExReverseFilter holds a reverse index mapping an external address to the scoped index from which it was derived. ExReverseFilter map[string]am.ScopedIndex // InReverseFilter holds a reverse index mapping an internal address to the scoped index from which it was derived. InReverseFilter map[string]am.ScopedIndex // WatchedOutPoints is a global set of outpoints being tracked by the wallet. This allows the block filterer to // check for spends from an outpoint we own. WatchedOutPoints map[wire.OutPoint]btcaddr.Address // FoundExternal is a two-layer map recording the scope and index of external addresses found in a single block. FoundExternal map[am.KeyScope]map[uint32]struct{} // FoundInternal is a two-layer map recording the scope and index of internal addresses found in a single block. FoundInternal map[am.KeyScope]map[uint32]struct{} // FoundOutPoints is a set of outpoints found in a single block whose address belongs to the wallet. FoundOutPoints map[wire.OutPoint]btcaddr.Address // RelevantTxns records the transactions found in a particular block that contained matches from an address in // either ExReverseFilter or InReverseFilter. RelevantTxns []*wire.MsgTx }
BlockFilterer is used to iteratively scan blocks for a set of addresses of interest. This is done by constructing reverse indexes mapping the addresses to a ScopedIndex, which permits the reconstruction of the exact child derivation paths that reported matches.
Once initialized, a BlockFilterer can be used to scan any number of blocks until a invocation of `FilterBlock` returns true. This allows the reverse indexes to be reused in the event that the set of addresses does not need to be altered. After a match is reported, a new BlockFilterer should be initialized with the updated set of addresses that include any new keys that are now within our look-ahead.
We track internal and external addresses separately in order to conserve the amount of space occupied in memory. Specifically, the account and branch combined contribute only 1-bit of information when using the default scopes used by the wallet. Thus we can avoid storing an additional 64-bits per address of interest by not storing the full derivation paths, and instead opting to allow the caller to contextually infer the account (DefaultAccount) and branch (Internal or External).
func NewBlockFilterer ¶
func NewBlockFilterer( params *chaincfg.Params, req *FilterBlocksRequest, ) *BlockFilterer
NewBlockFilterer constructs the reverse indexes for the current set of external and internal addresses that we are searching for, and is used to scan successive blocks for addresses of interest. A particular block filter can be reused until the first call from `FilterBlock` returns true.
func (*BlockFilterer) FilterBlock ¶
func (bf *BlockFilterer) FilterBlock(block *wire.Block) bool
FilterBlock parses all txns in the provided block, searching for any that contain addresses of interest in either the external or internal reverse filters. This method return true iff the block contains a non-zero number of addresses of interest, or a transaction in the block spends from outpoints controlled by the wallet.
func (*BlockFilterer) FilterOutputAddrs ¶
func (bf *BlockFilterer) FilterOutputAddrs(addrs []btcaddr.Address) bool
FilterOutputAddrs tests the set of addresses against the block filterer's external and internal reverse address indexes. If any are found, they are added to set of external and internal found addresses, respectively. This method returns true iff a non-zero number of the provided addresses are of interest.
func (*BlockFilterer) FilterTx ¶
func (bf *BlockFilterer) FilterTx(tx *wire.MsgTx) bool
FilterTx scans all txouts in the provided txn, testing to see if any found addresses match those contained within the external or internal reverse indexes. This method returns true iff the txn contains a non-zero number of addresses of interest, or the transaction spends from an outpoint that belongs to the wallet.
type ClientConnected ¶
type ClientConnected struct{}
ClientConnected is a notification for when a client connection is opened or reestablished to the chain server.
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.
type FilterBlocksRequest ¶
type FilterBlocksRequest struct { Blocks []wtxmgr.BlockMeta ExternalAddrs map[waddrmgr.ScopedIndex]btcaddr.Address InternalAddrs map[waddrmgr.ScopedIndex]btcaddr.Address WatchedOutPoints map[wire.OutPoint]btcaddr.Address }
FilterBlocksRequest specifies a range of blocks and the set of internal and external addresses of interest, indexed by corresponding scoped-index of the child address. A global set of watched outpoints is also included to monitor for spends.
type FilterBlocksResponse ¶
type FilterBlocksResponse struct { BatchIndex uint32 BlockMeta wtxmgr.BlockMeta FoundExternalAddrs map[waddrmgr.KeyScope]map[uint32]struct{} FoundInternalAddrs map[waddrmgr.KeyScope]map[uint32]struct{} FoundOutPoints map[wire.OutPoint]btcaddr.Address RelevantTxns []*wire.MsgTx }
FilterBlocksResponse reports the set of all internal and external addresses found in response to a FilterBlockRequest, any outpoints found that correspond to those addresses, as well as the relevant transactions that can modify the wallet's balance. The index of the block within the FilterBlocksRequest is returned, such that the caller can reinitiate a request for the subsequent block after updating the addresses of interest.
type FilteredBlockConnected ¶
FilteredBlockConnected is an alternate notification that contains both block and relevant transaction information in one struct, which allows atomic updates.
type Interface ¶
type Interface interface { Start() error Stop() WaitForShutdown() GetBestBlock() (*chainhash.Hash, int32, error) GetBlock(*chainhash.Hash) (*wire.Block, error) GetBlockHash(int64) (*chainhash.Hash, error) GetBlockHeader(*chainhash.Hash) (*wire.BlockHeader, error) FilterBlocks(*FilterBlocksRequest) (*FilterBlocksResponse, error) BlockStamp() (*waddrmgr.BlockStamp, error) SendRawTransaction(*wire.MsgTx, bool) (*chainhash.Hash, error) Rescan( *chainhash.Hash, []btcaddr.Address, map[wire.OutPoint]btcaddr.Address, ) error NotifyReceived([]btcaddr.Address) error NotifyBlocks() error Notifications() <-chan interface{} BackEnd() string }
Interface allows more than one backing blockchain source, such as a pod RPC chain server, or an SPV library, as long as we write a driver for it.
type RPCClient ¶
RPCClient represents a persistent client connection to a bitcoin RPC server for information regarding the current best block chain.
func NewRPCClient ¶
func NewRPCClient( chainParams *chaincfg.Params, connect, user, pass string, certs []byte, tls bool, reconnectAttempts int, quit qu.C, ) (*RPCClient, error)
NewRPCClient creates a client connection to the server described by the connect string. If disableTLS is false, the remote RPC certificate must be provided in the certs slice. The connection is not established immediately, but must be done using the Start method. If the remote server does not operate on the same bitcoin network as described by the passed chain parameters, the connection will be disconnected.
func (*RPCClient) BlockStamp ¶
func (c *RPCClient) BlockStamp() (*waddrmgr.BlockStamp, error)
BlockStamp returns the latest block notified by the client, or an error if the client has been shut down.
func (*RPCClient) FilterBlocks ¶
func (c *RPCClient) FilterBlocks(req *FilterBlocksRequest) ( *FilterBlocksResponse, error, )
FilterBlocks scans the blocks contained in the FilterBlocksRequest for any addresses of interest. For each requested block, the corresponding compact filter will first be checked for matches, skipping those that do not report anything. If the filter returns a positive match, the full block will be fetched and filtered. This method returns a FilterBlocksResponse for the first block containing a matching address. If no matches are found in the range of blocks requested, the returned response will be nil.
func (*RPCClient) Notifications ¶
func (c *RPCClient) Notifications() <-chan interface{}
Notifications returns a channel of parsed notifications sent by the remote bitcoin RPC server. This channel must be continually read or the process may abort for running out memory, as unread notifications are queued for later reads.
func (*RPCClient) POSTClient ¶
POSTClient creates the equivalent HTTP POST rpcclient.Client.
func (*RPCClient) Rescan ¶
func (c *RPCClient) Rescan( startHash *chainhash.Hash, addrs []btcaddr.Address, outPoints map[wire.OutPoint]btcaddr.Address, ) (e error)
Rescan wraps the normal Rescan command with an additional parameter that allows us to map an outpoint to the address in the chain that it pays to. This is useful when using BIP 158 filters as they include the prev pkScript rather than the full outpoint.
func (*RPCClient) Start ¶
Start attempts to establish a client connection with the remote server. If successful, handler goroutines are started to process notifications sent by the server. After a limited number of connection attempts, this function gives up, and therefore will not block forever waiting for the connection to be established to a server that may not exist.
func (*RPCClient) Stop ¶
func (c *RPCClient) Stop()
Stop disconnects the client and signals the shutdown of all goroutines started by Start.
func (*RPCClient) WaitForShutdown ¶
func (c *RPCClient) WaitForShutdown()
WaitForShutdown blocks until both the client has finished disconnecting and all handlers have exited.
type RelevantTx ¶
RelevantTx is a notification for a transaction which spends wallet inputs or pays to a watched address.
type RescanFinished ¶
RescanFinished is a notification that a previous rescan request has finished.