neutrino

package module
v0.12.2-0...-aadf665 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 3, 2021 License: MIT Imports: 37 Imported by: 0

README

Neutrino: Privacy-Preserving Bitcoin Light Client

Build Status Godoc Coverage Status

Neutrino is an experimental Bitcoin light client written in Go and designed with mobile Lightning Network clients in mind. It uses a new proposal for compact block filters to minimize bandwidth and storage use on the client side, while attempting to preserve privacy and minimize processor load on full nodes serving light clients.

Mechanism of operation

The light client synchronizes only block headers and a chain of compact block filter headers specifying the correct filters for each block. Filters are loaded lazily and stored in the database upon request; blocks are loaded lazily and not saved. There are multiple known major issues with the client, so it is not recommended to use it with real money at this point.

Usage

The client is instantiated as an object using NewChainService and then started. Upon start, the client sets up its database and other relevant files and connects to the p2p network. At this point, it becomes possible to query the client.

Queries

There are various types of queries supported by the client. There are many ways to access the database, for example, to get block headers by height and hash; in addition, it's possible to get a full block from the network using GetBlockFromNetwork by hash. However, the most useful methods are specifically tailored to scan the blockchain for data relevant to a wallet or a smart contract platform such as a Lightning Network node like lnd. These are described below.

Rescan

Rescan allows a wallet to scan a chain for specific TXIDs, outputs, and addresses. A start and end block may be specified along with other options. If no end block is specified, the rescan continues until stopped. If no start block is specified, the rescan begins with the latest known block. While a rescan runs, it notifies the client of each connected and disconnected block; the notifications follow the btcjson format with the option to use any of the relevant notifications. It's important to note that "recvtx" and "redeemingtx" notifications are only sent when a transaction is confirmed, not when it enters the mempool; the client does not currently support accepting 0-confirmation transactions.

GetUtxo

GetUtxo allows a wallet or smart contract platform to check that a UTXO exists on the blockchain and has not been spent. It is highly recommended to specify a start block; otherwise, in the event that the UTXO doesn't exist on the blockchain, the client will download all the filters back to block 1 searching for it. The client scans from the tip of the chain backwards, stopping when it finds the UTXO having been either spent or created; if it finds neither, it keeps scanning backwards until it hits the specified start block or, if a start block isn't specified, the first block in the blockchain. It returns a SpendReport containing either a TxOut including the PkScript required to spend the output, or containing information about the spending transaction, spending input, and block height in which the spending transaction was seen.

Stopping the client

Calling Stop on the ChainService client allows the user to stop the client; the method doesn't return until the ChainService is cleanly shut down.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrGetUtxoCancelled signals that a GetUtxo request was cancelled.
	ErrGetUtxoCancelled = errors.New("get utxo request cancelled")

	// ErrShuttingDown signals that neutrino received a shutdown request.
	ErrShuttingDown = errors.New("neutrino shutting down")
)
View Source 
var (
	// ConnectionRetryInterval is the base amount of time to wait in
	// between retries when connecting to persistent peers.  It is adjusted
	// by the number of retries such that there is a retry backoff.
	ConnectionRetryInterval = time.Second * 5

	// UserAgentName is the user agent name and is used to help identify
	// ourselves to other bitcoin peers.
	UserAgentName = "neutrino"

	// UserAgentVersion is the user agent version and is used to help
	// identify ourselves to other bitcoin peers.
	UserAgentVersion = "0.12.0-beta"

	// Services describes the services that are supported by the server.
	Services = wire.SFNodeWitness | wire.SFNodeCF

	// RequiredServices describes the services that are required to be
	// supported by outbound peers.
	RequiredServices = wire.SFNodeNetwork | wire.SFNodeWitness | wire.SFNodeCF

	// BanThreshold is the maximum ban score before a peer is banned.
	BanThreshold = uint32(100)

	// BanDuration is the duration of a ban.
	BanDuration = time.Hour * 24

	// TargetOutbound is the number of outbound peers to target.
	TargetOutbound = 8

	// MaxPeers is the maximum number of connections the client maintains.
	MaxPeers = 125

	// DisableDNSSeed disables getting initial addresses for Bitcoin nodes
	// from DNS.
	DisableDNSSeed = false

	// DefaultFilterCacheSize is the size (in bytes) of filters neutrino
	// will keep in memory if no size is specified in the neutrino.Config.
	// Since we utilize the cache during batch filter fetching, it is
	// beneficial if it is able to to keep a whole batch. The current batch
	// size is 1000, so we default to 30 MB, which can fit about 1450 to
	// 2300 mainnet filters.
	DefaultFilterCacheSize uint64 = 3120 * 10 * 1000

	// DefaultBlockCacheSize is the size (in bytes) of blocks neutrino will
	// keep in memory if no size is specified in the neutrino.Config.
	DefaultBlockCacheSize uint64 = 4096 * 10 * 1000 // 40 MB
)

These are exported variables so they can be changed by users.

TODO: Export functional options for these as much as possible so they can be changed call-to-call.

View Source 
var (
	// QueryTimeout specifies how long to wait for a peer to answer a
	// query.
	QueryTimeout = time.Second * 10

	// QueryBatchTimeout is the total time we'll wait for a batch fetch
	// query to complete.
	// TODO(halseth): instead use timeout since last received response?
	QueryBatchTimeout = time.Second * 30

	// QueryPeerCooldown is the time we'll wait before re-assigning a query
	// to a peer that previously failed because of a timeout.
	QueryPeerCooldown = time.Second * 5

	// QueryNumRetries specifies how many times to retry sending a query to
	// each peer before we've concluded we aren't going to get a valid
	// response. This allows to make up for missed messages in some
	// instances.
	QueryNumRetries = 2

	// QueryPeerConnectTimeout specifies how long to wait for the
	// underlying chain service to connect to a peer before giving up
	// on a query in case we don't have any peers.
	QueryPeerConnectTimeout = time.Second * 30

	// QueryEncoding specifies the default encoding (witness or not) for
	// `getdata` and other similar messages.
	QueryEncoding = wire.WitnessEncoding

	// ErrFilterFetchFailed is returned in case fetching a compact filter
	// fails.
	ErrFilterFetchFailed = fmt.Errorf("unable to fetch cfilter")
)
View Source 
var (

	// ErrRescanExit is an error returned to the caller in case the ongoing
	// rescan exits.
	ErrRescanExit = errors.New("rescan exited")
)

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 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.

func VerifyBasicBlockFilter 

func VerifyBasicBlockFilter(filter *gcs.Filter, block *firoutil.Block) (int,
	error)

VerifyBasicBlockFilter asserts that a given block filter was constructed correctly and according to the rules of BIP-0158 to contain both the output's pk scripts as well as the pk scripts the inputs are spending.

Types

type ChainService 

type ChainService struct {
	FilterDB         filterdb.FilterDatabase
	BlockHeaders     headerfs.BlockHeaderStore
	RegFilterHeaders *headerfs.FilterHeaderStore

	FilterCache *lru.Cache
	BlockCache  *lru.Cache
	// contains filtered or unexported fields
}

ChainService is instantiated with functional options.

func NewChainService 

func NewChainService(cfg Config) (*ChainService, error)

NewChainService returns a new chain service configured to connect to the bitcoin network type specified by chainParams. Use start to begin syncing with peers.

func (*ChainService) AddBytesReceived 

func (s *ChainService) AddBytesReceived(bytesReceived uint64)

AddBytesReceived adds the passed number of bytes to the total bytes received counter for the server. It is safe for concurrent access.

func (*ChainService) AddBytesSent 

func (s *ChainService) AddBytesSent(bytesSent uint64)

AddBytesSent adds the passed number of bytes to the total bytes sent counter for the server. It is safe for concurrent access.

func (*ChainService) AddPeer 

func (s *ChainService) AddPeer(sp *ServerPeer)

AddPeer adds a new peer that has already been connected to the server.

func (*ChainService) AddedNodeInfo 

func (s *ChainService) AddedNodeInfo() []*ServerPeer

AddedNodeInfo returns an array of btcjson.GetAddedNodeInfoResult structures describing the persistent (added) nodes.

func (*ChainService) BanPeer 

func (s *ChainService) BanPeer(addr string, reason banman.Reason) error

BanPeer disconnects and bans a peer due to a specific reason for a duration of BanDuration.

func (*ChainService) BestBlock 

func (s *ChainService) BestBlock() (*headerfs.BlockStamp, error)

BestBlock retrieves the most recent block's height and hash where we have both the header and filter header ready.

func (*ChainService) ChainParams 

func (s *ChainService) ChainParams() chaincfg.Params

ChainParams returns a copy of the ChainService's chaincfg.Params.

func (*ChainService) ConnectNode 

func (s *ChainService) ConnectNode(addr string, permanent bool) error

ConnectNode adds `addr' as a new outbound peer. If permanent is true then the peer will be persistent and reconnect if the connection is lost. It is an error to call this with an already existing peer.

func (*ChainService) ConnectedCount 

func (s *ChainService) ConnectedCount() int32

ConnectedCount returns the number of currently connected peers.

func (*ChainService) ConnectedPeers 

func (s *ChainService) ConnectedPeers() (<-chan query.Peer, func(), error)

ConnectedPeers is a function that returns a channel where all connected peers will be sent. It is assumed that all current peers will be sent imemdiately, and new peers as they connect.

func (*ChainService) DisconnectNodeByAddr 

func (s *ChainService) DisconnectNodeByAddr(addr string) error

DisconnectNodeByAddr disconnects a peer by target address. Both outbound and inbound nodes will be searched for the target node. An error message will be returned if the peer was not found.

func (*ChainService) DisconnectNodeByID 

func (s *ChainService) DisconnectNodeByID(id int32) error

DisconnectNodeByID disconnects a peer by target node id. Both outbound and inbound nodes will be searched for the target node. An error message will be returned if the peer was not found.

func (*ChainService) ForAllPeers 

func (s *ChainService) ForAllPeers(closure func(sp *ServerPeer))

ForAllPeers runs a closure over all peers (outbound and persistent) to which the ChainService is connected. Nothing is returned because the peerState's ForAllPeers method doesn't return anything as the closure passed to it doesn't return anything.

func (*ChainService) GetBlock 

func (s *ChainService) GetBlock(blockHash chainhash.Hash,
	options ...QueryOption) (*firoutil.Block, error)

GetBlock gets a block by requesting it from the network, one peer at a time, until one answers. If the block is found in the cache, it will be returned immediately.

func (*ChainService) GetBlockHash 

func (s *ChainService) GetBlockHash(height int64) (*chainhash.Hash, error)

GetBlockHash returns the block hash at the given height.

func (*ChainService) GetBlockHeader 

func (s *ChainService) GetBlockHeader(
	blockHash *chainhash.Hash) (*wire.BlockHeader, error)

GetBlockHeader returns the block header for the given block hash, or an error if the hash doesn't exist or is unknown.

func (*ChainService) GetBlockHeight 

func (s *ChainService) GetBlockHeight(hash *chainhash.Hash) (int32, error)

GetBlockHeight gets the height of a block by its hash. An error is returned if the given block hash is unknown.

func (*ChainService) GetCFilter 

func (s *ChainService) GetCFilter(blockHash chainhash.Hash,
	filterType wire.FilterType, options ...QueryOption) (*gcs.Filter, error)

GetCFilter gets a cfilter from the database. Failing that, it requests the cfilter from the network and writes it to the database. If extended is true, an extended filter will be queried for. Otherwise, we'll fetch the regular filter.

func (*ChainService) GetUtxo 

func (s *ChainService) GetUtxo(options ...RescanOption) (*SpendReport, error)

GetUtxo gets the appropriate TxOut or errors if it's spent. The option WatchOutPoints (with a single outpoint) is required. StartBlock can be used to give a hint about which block the transaction is in, and TxIdx can be used to give a hint of which transaction in the block matches it (coinbase is 0, first normal transaction is 1, etc.).

TODO(roasbeef): WTB utxo-commitments.

func (*ChainService) IsBanned 

func (s *ChainService) IsBanned(addr string) bool

IsBanned returns true if the peer is banned, and false otherwise.

func (*ChainService) IsCurrent 

func (s *ChainService) IsCurrent() bool

IsCurrent lets the caller know whether the chain service's block manager thinks its view of the network is current.

func (*ChainService) NetTotals 

func (s *ChainService) NetTotals() (uint64, uint64)

NetTotals returns the sum of all bytes received and sent across the network for all peers. It is safe for concurrent access.

func (*ChainService) OutboundGroupCount 

func (s *ChainService) OutboundGroupCount(key string) int

OutboundGroupCount returns the number of peers connected to the given outbound group key.

func (*ChainService) PeerByAddr 

func (s *ChainService) PeerByAddr(addr string) *ServerPeer

PeerByAddr lets the caller look up a peer address in the service's peer table, if connected to that peer address.

func (*ChainService) Peers 

func (s *ChainService) Peers() []*ServerPeer

Peers returns an array of all connected peers.

func (*ChainService) RemoveNodeByAddr 

func (s *ChainService) RemoveNodeByAddr(addr string) error

RemoveNodeByAddr removes a peer from the list of persistent peers if present. An error will be returned if the peer was not found.

func (*ChainService) RemoveNodeByID 

func (s *ChainService) RemoveNodeByID(id int32) error

RemoveNodeByID removes a peer by node ID from the list of persistent peers if present. An error will be returned if the peer was not found.

func (*ChainService) SendTransaction 

func (s *ChainService) SendTransaction(tx *wire.MsgTx) error

SendTransaction broadcasts the transaction to all currently active peers so it can be propagated to other nodes and eventually mined. An error won't be returned if the transaction already exists within the mempool. Any transaction broadcast through this method will be rebroadcast upon every change of the tip of the chain.

func (*ChainService) Start 

func (s *ChainService) Start() error

Start begins connecting to peers and syncing the blockchain.

func (*ChainService) Stop 

func (s *ChainService) Stop() error

Stop gracefully shuts down the server by stopping and disconnecting all peers and the main listener.

func (*ChainService) UpdatePeerHeights 

func (s *ChainService) UpdatePeerHeights(latestBlkHash *chainhash.Hash,
	latestHeight int32, updateSource *ServerPeer)

UpdatePeerHeights updates the heights of all peers who have have announced the latest connected main chain block, or a recognized orphan. These height updates allow us to dynamically refresh peer heights, ensuring sync peer selection has access to the latest block heights for each peer.

type ChainSource 

type ChainSource interface {
	// ChainParams returns the parameters of the current chain.
	ChainParams() chaincfg.Params

	// BestBlock retrieves the most recent block's height and hash where we
	// have both the header and filter header ready.
	BestBlock() (*headerfs.BlockStamp, error)

	// GetBlockHeaderByHeight returns the header of the block with the given
	// height.
	GetBlockHeaderByHeight(uint32) (*wire.BlockHeader, error)

	// GetBlockHeader returns the header of the block with the given hash.
	GetBlockHeader(*chainhash.Hash) (*wire.BlockHeader, uint32, error)

	// GetBlock returns the block with the given hash.
	GetBlock(chainhash.Hash, ...QueryOption) (*firoutil.Block, error)

	// GetFilterHeaderByHeight returns the filter header of the block with
	// the given height.
	GetFilterHeaderByHeight(uint32) (*chainhash.Hash, error)

	// GetCFilter returns the filter of the given type for the block with
	// the given hash.
	GetCFilter(chainhash.Hash, wire.FilterType,
		...QueryOption) (*gcs.Filter, error)

	// Subscribe returns a block subscription that delivers block
	// notifications in order. The bestHeight parameter can be used to
	// signal that a backlog of notifications should be delivered from this
	// height. When providing a bestHeight of 0, a backlog will not be
	// delivered.
	//
	// TODO(wilmer): extend with best hash as well.
	Subscribe(bestHeight uint32) (*blockntfns.Subscription, error)
}

ChainSource is an interface that's in charge of retrieving information about the existing chain.

type Config 

type Config struct {
	// DataDir is the directory that neutrino will store all header
	// information within.
	DataDir string

	// Database is an *open* database instance that we'll use to storm
	// indexes of the chain.
	Database walletdb.DB

	// ChainParams is the chain that we're running on.
	ChainParams chaincfg.Params

	// ConnectPeers is a slice of hosts that should be connected to on
	// startup, and be established as persistent peers.
	//
	// NOTE: If specified, we'll *only* connect to this set of peers and
	// won't attempt to automatically seek outbound peers.
	ConnectPeers []string

	// AddPeers is a slice of hosts that should be connected to on startup,
	// and be maintained as persistent peers.
	AddPeers []string

	// Dialer is an optional function closure that will be used to
	// establish outbound TCP connections. If specified, then the
	// connection manager will use this in place of net.Dial for all
	// outbound connection attempts.
	Dialer func(addr net.Addr) (net.Conn, error)

	// NameResolver is an optional function closure that will be used to
	// lookup the IP of any host. If specified, then the address manager,
	// along with regular outbound connection attempts will use this
	// instead.
	NameResolver func(host string) ([]net.IP, error)

	// FilterCacheSize indicates the size (in bytes) of filters the cache will
	// hold in memory at most.
	FilterCacheSize uint64

	// BlockCache is an LRU block cache. If none is provided then the a new
	// one will be instantiated.
	BlockCache *lru.Cache

	// BlockCacheSize indicates the size (in bytes) of blocks the block
	// cache will hold in memory at most. If a BlockCache is provided then
	// BlockCacheSize is ignored.
	BlockCacheSize uint64

	// persistToDisk indicates whether the filter should also be written
	// to disk in addition to the memory cache. For "normal" wallets, they'll
	// almost never need to re-match a filter once it's been fetched unless
	// they're doing something like a key import.
	PersistToDisk bool

	// AssertFilterHeader is an optional field that allows the creator of
	// the ChainService to ensure that if any chain data exists, it's
	// compliant with the expected filter header state. If neutrino starts
	// up and this filter header state has diverged, then it'll remove the
	// current on disk filter headers to sync them anew.
	AssertFilterHeader *headerfs.FilterHeader

	// BroadcastTimeout is the amount of time we'll wait before giving up on
	// a transaction broadcast attempt. Broadcasting transactions consists
	// of three steps:
	//
	// 1. Neutrino sends an inv for the transaction.
	// 2. The recipient node determines if the inv is known, and if it's
	//    not, replies with a getdata message.
	// 3. Neutrino sends the raw transaction.
	BroadcastTimeout time.Duration
}

Config is a struct detailing the configuration of the chain service.

type GetUtxoRequest 

type GetUtxoRequest struct {
	// Input is the target outpoint with script to watch for spentness.
	Input *InputWithScript

	// BirthHeight is the height at which we expect to find the original
	// unspent outpoint. This is also the height used when starting the
	// search for spends.
	BirthHeight uint32
	// contains filtered or unexported fields
}

GetUtxoRequest is a request to scan for InputWithScript from the height BirthHeight.

func (*GetUtxoRequest) Result 

func (r *GetUtxoRequest) Result(cancel <-chan struct{}) (*SpendReport, error)

Result is callback returning either a spend report or an error.

type GetUtxoRequestPQ 

type GetUtxoRequestPQ []*GetUtxoRequest

A GetUtxoRequestPQ implements heap.Interface and holds GetUtxoRequests. The queue maintains that heap.Pop() will always return the GetUtxo request with the least starting height. This allows us to add new GetUtxo requests to an already running batch.

func (*GetUtxoRequestPQ) IsEmpty 

func (pq *GetUtxoRequestPQ) IsEmpty() bool

IsEmpty returns true if the queue has no elements.

func (GetUtxoRequestPQ) Len 

func (pq GetUtxoRequestPQ) Len() int

func (GetUtxoRequestPQ) Less 

func (pq GetUtxoRequestPQ) Less(i, j int) bool

func (*GetUtxoRequestPQ) Peek 

func (pq *GetUtxoRequestPQ) Peek() *GetUtxoRequest

Peek returns the least height element in the queue without removing it.

func (*GetUtxoRequestPQ) Pop 

func (pq *GetUtxoRequestPQ) Pop() interface{}

Pop is called by the heap.Interface implementation to remove an element from the end of the backing store. The heap library will then maintain the heap invariant.

func (*GetUtxoRequestPQ) Push 

func (pq *GetUtxoRequestPQ) Push(x interface{})

Push is called by the heap.Interface implementation to add an element to the end of the backing store. The heap library will then maintain the heap invariant.

func (GetUtxoRequestPQ) Swap 

func (pq GetUtxoRequestPQ) Swap(i, j int)

type InputWithScript 

type InputWithScript struct {
	// OutPoint identifies the previous output to watch.
	OutPoint wire.OutPoint

	// PkScript is the script of the previous output.
	PkScript []byte
}

InputWithScript couples an previous outpoint along with its input script. We'll use the prev script to match the filter itself, but then scan for the particular outpoint when we need to make a notification decision.

type QueryOption 

type QueryOption func(*queryOptions)

QueryOption is a functional option argument to any of the network query methods, such as GetBlock and GetCFilter (when that resorts to a network query). These are always processed in order, with later options overriding earlier ones.

func DoneChan 

func DoneChan(doneChan chan<- struct{}) QueryOption

DoneChan allows the caller to pass a channel that will get closed when the query is finished.

func Encoding 

func Encoding(encoding wire.MessageEncoding) QueryOption

Encoding is a query option that allows the caller to set a message encoding for the query messages.

func MaxBatchSize 

func MaxBatchSize(maxSize int64) QueryOption

MaxBatchSize allows the caller to limit the number of items fetched in a batch.

func NumRetries 

func NumRetries(numRetries uint8) QueryOption

NumRetries is a query option that lets the query know the maximum number of times each peer should be queried. The default is one.

func OptimisticBatch 

func OptimisticBatch() QueryOption

OptimisticBatch allows the caller to tell that items following the requested one should be included in the query.

func OptimisticReverseBatch 

func OptimisticReverseBatch() QueryOption

OptimisticReverseBatch allows the caller to tell that items preceding the requested one should be included in the query.

func PeerConnectTimeout 

func PeerConnectTimeout(timeout time.Duration) QueryOption

PeerConnectTimeout is a query option that lets the query know how long to wait for the underlying chain service to connect to a peer before giving up on a query in case we don't have any peers.

func Timeout 

func Timeout(timeout time.Duration) QueryOption

Timeout is a query option that lets the query know how long to wait for each peer we ask the query to answer it before moving on.

type Rescan 

type Rescan struct {
	// contains filtered or unexported fields
}

Rescan is an object that represents a long-running rescan/notification client with updateable filters. It's meant to be close to a drop-in replacement for the btcd rescan and notification functionality used in wallets. It only contains information about whether a goroutine is running.

func NewRescan 

func NewRescan(chain ChainSource, options ...RescanOption) *Rescan

NewRescan returns a rescan object that runs in another goroutine and has an updatable filter. It returns the long-running rescan object, and a channel which returns any error on termination of the rescan process.

func (*Rescan) Start 

func (r *Rescan) Start() <-chan error

Start kicks off the rescan goroutine, which will begin to scan the chain according to the specified rescan options.

func (*Rescan) Update 

func (r *Rescan) Update(options ...UpdateOption) error

Update sends an update to a long-running rescan/notification goroutine.

func (*Rescan) WaitForShutdown 

func (r *Rescan) WaitForShutdown()

WaitForShutdown waits until all goroutines associated with the rescan have exited. This method is to be called once the passed quitchan (if any) has been closed.

type RescanChainSource 

type RescanChainSource struct {
	*ChainService
}

RescanChainSource is a wrapper type around the ChainService struct that will be used to satisfy the rescan.ChainSource interface.

func (*RescanChainSource) GetBlockHeader 

func (s *RescanChainSource) GetBlockHeader(
	hash *chainhash.Hash) (*wire.BlockHeader, uint32, error)

GetBlockHeader returns the header of the block with the given hash.

func (*RescanChainSource) GetBlockHeaderByHeight 

func (s *RescanChainSource) GetBlockHeaderByHeight(
	height uint32) (*wire.BlockHeader, error)

GetBlockHeaderByHeight returns the header of the block with the given height.

func (*RescanChainSource) GetFilterHeaderByHeight 

func (s *RescanChainSource) GetFilterHeaderByHeight(
	height uint32) (*chainhash.Hash, error)

GetFilterHeaderByHeight returns the filter header of the block with the given height.

func (*RescanChainSource) Subscribe 

func (s *RescanChainSource) Subscribe(
	bestHeight uint32) (*blockntfns.Subscription, error)

Subscribe returns a block subscription that delivers block notifications in order. The bestHeight parameter can be used to signal that a backlog of notifications should be delivered from this height. When providing a height of 0, a backlog will not be delivered.

type RescanOption 

type RescanOption func(ro *rescanOptions)

RescanOption is a functional option argument to any of the rescan and notification subscription methods. These are always processed in order, with later options overriding earlier ones.

func EndBlock 

func EndBlock(endBlock *headerfs.BlockStamp) RescanOption

EndBlock specifies the end block. The hash is checked first; if there's no such hash (zero hash avoids lookup), the height is checked next. If the height is 0 or in the future or the end block isn't specified, the quit channel MUST be specified as Rescan will sync to the tip of the blockchain and continue to stay in sync and pass notifications. This is enforced at runtime.

func NotificationHandlers 

func NotificationHandlers(ntfn rpcclient.NotificationHandlers) RescanOption

NotificationHandlers specifies notification handlers for the rescan. These will always run in the same goroutine as the caller.

func ProgressHandler 

func ProgressHandler(
	handler ScanProgressHandler) RescanOption

ProgressHandler specifies a handler to be used when the utxo scanner reports its progress. The passed handler should be non-blocking for the rescan to continue normally.

func QueryOptions 

func QueryOptions(options ...QueryOption) RescanOption

QueryOptions pass onto the underlying queries.

func QuitChan 

func QuitChan(quit <-chan struct{}) RescanOption

QuitChan specifies the quit channel. This can be used by the caller to let an indefinite rescan (one with no EndBlock set) know it should gracefully shut down. If this isn't specified, an end block MUST be specified as Rescan must know when to stop. This is enforced at runtime.

func StartBlock 

func StartBlock(startBlock *headerfs.BlockStamp) RescanOption

StartBlock specifies the start block. The hash is checked first; if there's no such hash (zero hash avoids lookup), the height is checked next. If the height is 0 or the start block isn't specified, starts from the genesis block. This block is assumed to already be known, and no notifications will be sent for this block. The rescan uses the latter of StartBlock and StartTime.

func StartTime 

func StartTime(startTime time.Time) RescanOption

StartTime specifies the start time. The time is compared to the timestamp of each block, and the rescan only begins once the first block crosses that timestamp. When using this, it is advisable to use a margin of error and start rescans slightly earlier than required. The rescan uses the latter of StartBlock and StartTime.

func TxIdx 

func TxIdx(txIdx uint32) RescanOption

TxIdx specifies a hint transaction index into the block in which the UTXO is created (eg, coinbase is 0, next transaction is 1, etc.)

func WatchAddrs 

func WatchAddrs(watchAddrs ...firoutil.Address) RescanOption

WatchAddrs specifies the addresses to watch/filter for. Each call to this function adds to the list of addresses being watched rather than replacing the list. Each time a transaction spends to the specified address, the outpoint is added to the WatchOutPoints list.

func WatchInputs 

func WatchInputs(watchInputs ...InputWithScript) RescanOption

WatchInputs specifies the outpoints to watch for on-chain spends. We also require the script as we'll match on the script, but then notify based on the outpoint. Each call to this function adds to the list of outpoints being watched rather than replacing the list.

type ScanProgressHandler 

type ScanProgressHandler func(lastProcessedBlock uint32)

ScanProgressHandler is used in rescanOptions to update the caller with the rescan progress.

type ServerPeer 

type ServerPeer struct {
	*peer.Peer
	// contains filtered or unexported fields
}

ServerPeer extends the peer to maintain state shared by the server and the blockmanager.

func (*ServerPeer) OnAddr 

func (sp *ServerPeer) OnAddr(_ *peer.Peer, msg *wire.MsgAddr)

OnAddr is invoked when a peer receives an addr bitcoin message and is used to notify the server about advertised addresses.

func (*ServerPeer) OnDisconnect 

func (sp *ServerPeer) OnDisconnect() <-chan struct{}

OnDisconnect returns a channel that will be closed when this peer is disconnected.

NOTE: Part of the query.Peer interface.

func (*ServerPeer) OnFeeFilter 

func (sp *ServerPeer) OnFeeFilter(_ *peer.Peer, msg *wire.MsgFeeFilter)

OnFeeFilter is invoked when a peer receives a feefilter bitcoin message and is used by remote peers to request that no transactions which have a fee rate lower than provided value are inventoried to them. The peer will be disconnected if an invalid fee filter value is provided.

func (*ServerPeer) OnHeaders 

func (sp *ServerPeer) OnHeaders(p *peer.Peer, msg *wire.MsgHeaders)

OnHeaders is invoked when a peer receives a headers bitcoin message. The message is passed down to the block manager.

func (*ServerPeer) OnInv 

func (sp *ServerPeer) OnInv(p *peer.Peer, msg *wire.MsgInv)

OnInv is invoked when a peer receives an inv bitcoin message and is used to examine the inventory being advertised by the remote peer and react accordingly. We pass the message down to blockmanager which will call QueueMessage with any appropriate responses.

func (*ServerPeer) OnRead 

func (sp *ServerPeer) OnRead(_ *peer.Peer, bytesRead int, msg wire.Message,
	err error)

OnRead is invoked when a peer receives a message and it is used to update the bytes received by the server.

func (*ServerPeer) OnReject 

func (sp *ServerPeer) OnReject(_ *peer.Peer, msg *wire.MsgReject)

OnReject is invoked when a peer receives a reject bitcoin message and is used to notify the server about a rejected transaction.

func (*ServerPeer) OnVerAck 

func (sp *ServerPeer) OnVerAck(_ *peer.Peer, msg *wire.MsgVerAck)

OnVerAck is invoked when a peer receives a verack bitcoin message and is used to kick start communication with them.

func (*ServerPeer) OnVersion 

func (sp *ServerPeer) OnVersion(_ *peer.Peer, msg *wire.MsgVersion) *wire.MsgReject

OnVersion is invoked when a peer receives a version bitcoin message and is used to negotiate the protocol version details as well as kick start the communications.

func (*ServerPeer) OnWrite 

func (sp *ServerPeer) OnWrite(_ *peer.Peer, bytesWritten int, msg wire.Message, err error)

OnWrite is invoked when a peer sends a message and it is used to update the bytes sent by the server.

func (*ServerPeer) SubscribeRecvMsg 

func (sp *ServerPeer) SubscribeRecvMsg() (<-chan wire.Message, func())

SubscribeRecvMsg adds a OnRead subscription to the peer. All bitcoin messages received from this peer will be sent on the returned channel. A closure is also returned, that should be called to cancel the subscription.

NOTE: Part of the query.Peer interface.

type SpendReport 

type SpendReport struct {
	// SpendingTx is the transaction that spent the output that a spend
	// report was requested for.
	//
	// NOTE: This field will only be populated if the target output has
	// been spent.
	SpendingTx *wire.MsgTx

	// SpendingTxIndex is the input index of the transaction above which
	// spends the target output.
	//
	// NOTE: This field will only be populated if the target output has
	// been spent.
	SpendingInputIndex uint32

	// SpendingTxHeight is the hight of the block that included the
	// transaction  above which spent the target output.
	//
	// NOTE: This field will only be populated if the target output has
	// been spent.
	SpendingTxHeight uint32

	// Output is the raw output of the target outpoint.
	//
	// NOTE: This field will only be populated if the target is still
	// unspent.
	Output *wire.TxOut

	// BlockHash is the block hash of the block that includes the unspent
	// output.
	//
	// NOTE: This field will only be populated if the target is still
	// unspent.
	BlockHash *chainhash.Hash

	// BlockHeight is the height of the block that includes the unspent output.
	//
	// NOTE: This field will only be populated if the target is still
	// unspent.
	BlockHeight uint32

	// BlockIndex is the index of the output's transaction in its block.
	//
	// NOTE: This field will only be populated if the target is still
	// unspent.
	BlockIndex uint32
}

SpendReport is a struct which describes the current spentness state of a particular output. In the case that an output is spent, then the spending transaction and related details will be populated. Otherwise, only the target unspent output in the chain will be returned.

type UpdateOption 

type UpdateOption func(uo *updateOptions)

UpdateOption is a functional option argument for the Rescan.Update method.

func AddAddrs 

func AddAddrs(addrs ...firoutil.Address) UpdateOption

AddAddrs adds addresses to the filter.

func AddInputs 

func AddInputs(inputs ...InputWithScript) UpdateOption

AddInputs adds inputs to watch to the filter.

func DisableDisconnectedNtfns 

func DisableDisconnectedNtfns(disabled bool) UpdateOption

DisableDisconnectedNtfns tells the rescan not to send `OnBlockDisconnected` and `OnFilteredBlockDisconnected` notifications when rewinding.

func Rewind 

func Rewind(height uint32) UpdateOption

Rewind rewinds the rescan to the specified height (meaning, disconnects down to the block immediately after the specified height) and restarts it from that point with the (possibly) newly expanded filter. Especially useful when called in the same Update() as one of the previous three options.

type UtxoScanner 

type UtxoScanner struct {
	// contains filtered or unexported fields
}

UtxoScanner batches calls to GetUtxo so that a single scan can search for multiple outpoints. If a scan is in progress when a new element is added, we check whether it can safely be added to the current batch, if not it will be included in the next batch.

func NewUtxoScanner 

func NewUtxoScanner(cfg *UtxoScannerConfig) *UtxoScanner

NewUtxoScanner creates a new instance of UtxoScanner using the given chain interface.

func (*UtxoScanner) Enqueue 

func (s *UtxoScanner) Enqueue(input *InputWithScript,
	birthHeight uint32,
	progressHandler ScanProgressHandler) (*GetUtxoRequest, error)

Enqueue takes a GetUtxoRequest and adds it to the next applicable batch.

func (*UtxoScanner) Start 

func (s *UtxoScanner) Start() error

Start begins running scan batches.

func (*UtxoScanner) Stop 

func (s *UtxoScanner) Stop() error

Stop any in-progress scan.

type UtxoScannerConfig 

type UtxoScannerConfig struct {
	// BestSnapshot returns the block stamp of the current chain tip.
	BestSnapshot func() (*headerfs.BlockStamp, error)

	// GetBlockHash returns the block hash at given height in main chain.
	GetBlockHash func(height int64) (*chainhash.Hash, error)

	// BlockFilterMatches checks the cfilter for the block hash for matches
	// against the rescan options.
	BlockFilterMatches func(ro *rescanOptions, blockHash *chainhash.Hash) (bool, error)

	// GetBlock fetches a block from the p2p network.
	GetBlock func(chainhash.Hash, ...QueryOption) (*firoutil.Block, error)
}

UtxoScannerConfig exposes configurable methods for interacting with the blockchain.

Source Files

View all Source files

Directories

Path Synopsis
lru

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.