spv

package
v0.0.0-...-d4978fa Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2019 License: Unlicense, MIT Imports: 36 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 (
	// QueryTimeout specifies how long to wait for a peer to answer a
	// query.
	QueryTimeout = time.Second * 3
	// 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
)
View Source 
var (
	// BanDuration is the duration of a ban.
	BanDuration = time.Hour * 24
	// BanThreshold is the maximum ban score before a peer is banned.
	BanThreshold = uint32(100)
	// 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 * 2
	// 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
	// DefaultFilterCacheSize is the size (in bytes) of filters neutrino will
	// keep in memory if no size is specified in the neutrino.Config.
	DefaultFilterCacheSize uint64 = 4096 * 1000
	// DisableDNSSeed disables getting initial addresses for Bitcoin nodes
	// from DNS.
	DisableDNSSeed = false
	// MaxPeers is the maximum number of connections the client maintains.
	MaxPeers = 125
	// RequiredServices describes the services that are required to be
	// supported by outbound peers.
	RequiredServices = wire.SFNodeNetwork | wire.SFNodeWitness | wire.SFNodeCF
	// Services describes the services that are supported by the server.
	Services = wire.SFNodeWitness | wire.SFNodeCF
	// TargetOutbound is the number of outbound peers to target.
	TargetOutbound = 16
	// 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.0.4-beta"
)

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 ErrRescanExit = errors.New("rescan exited")

Functions

This section is empty.

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(sp *ServerPeer)

BanPeer bans a peer that has already been connected to the server by ip.

func (*ChainService) BestBlock 

func (s *ChainService) BestBlock() (*waddrmgr.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() netparams.Params

ChainParams returns a copy of the ChainService's netparams.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) 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) (*util.Block, error)

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)

func (*ChainService) GetUtxo 

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

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) NewRescan 

func (s *ChainService) NewRescan(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 (*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) PublishTransaction 

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

PublishTransaction sends the transaction to the consensus RPC server so it can be propigated to other nodes and eventually mined.

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,
	options ...QueryOption) error

func (*ChainService) Start 

func (s *ChainService) Start()

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 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 teh chain.
	Database walletdb.DB
	// ChainParams is the chain that we're running on.
	ChainParams netparams.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
	// BlockCacheSize indicates the size (in bytes) of blocks the block
	// cache will hold in memory at most.
	BlockCacheSize uint64
}

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)

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

func (GetUtxoRequestPQ) Len 

func (pq GetUtxoRequestPQ) Len() int

We want Pop to give us the least BirthHeight.

func (GetUtxoRequestPQ) Less 

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

func (*GetUtxoRequestPQ) Peek 

func (pq *GetUtxoRequestPQ) Peek() *GetUtxoRequest

func (*GetUtxoRequestPQ) Pop 

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

func (*GetUtxoRequestPQ) Push 

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

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
}

type QueryOption 

type QueryOption func(*queryOptions)

func DoneChan 

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

func Encoding 

func Encoding(encoding wire.MessageEncoding) QueryOption

func NumRetries 

func NumRetries(numRetries uint8) QueryOption

func PeerConnectTimeout 

func PeerConnectTimeout(timeout time.Duration) QueryOption

func PersistToDisk 

func PersistToDisk() QueryOption

func Timeout 

func Timeout(timeout time.Duration) QueryOption

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 (*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

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 RescanOption 

type RescanOption func(ro *rescanOptions)

func EndBlock 

func EndBlock(endBlock *waddrmgr.BlockStamp) RescanOption

func NotificationHandlers 

func NotificationHandlers(ntfn rpcclient.NotificationHandlers) RescanOption

func QueryOptions 

func QueryOptions(options ...QueryOption) RescanOption

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

func WatchAddrs 

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

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 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) 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 send the "sendheaders" command to peers that are of a sufficienty new protocol version.

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.

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
}

type UpdateOption 

type UpdateOption func(uo *updateOptions)

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

func AddAddrs 

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

AddAddrs adds addresses to the filter.

func AddInputs 

func AddInputs(inputs ...InputWithScript) UpdateOption

func DisableDisconnectedNtfns 

func DisableDisconnectedNtfns(disabled bool) UpdateOption

func Rewind 

func Rewind(height uint32) UpdateOption

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

func (*UtxoScanner) Enqueue 

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

func (*UtxoScanner) Start 

func (s *UtxoScanner) Start() error

func (*UtxoScanner) Stop 

func (s *UtxoScanner) Stop() error

type UtxoScannerConfig 

type UtxoScannerConfig struct {
	// BestSnapshot returns the block stamp of the current chain tip.
	BestSnapshot func() (*am.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) (*util.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.