Privacy-Preserving Bitcoin Light Client
Switch branches/tags
Nothing to show
Clone or download
Latest commit 8018ab7 Oct 18, 2018
Failed to load latest commit information.
cache cache: use SerializeSize() to avoid allocations when inserting blocks Aug 22, 2018
filterdb filterdb: update tests to remove ext filter Jul 14, 2018
headerfs headerfs/index: clarify that headers are sorted by hash in the db Oct 18, 2018
headerlist headerlist: add new Chain interface and BoundedMemoryChain implementa… Aug 8, 2018
testdata query_test: add blocks 1-256 testdate, and loadBlocks method Aug 22, 2018
.gitignore multi: update neutrino to use cfcheckpoint based sync, add anti-bambo… Jul 13, 2018
.travis.yml multi: update neutrino to use cfcheckpoint based sync, add anti-bambo… Jul 13, 2018
LICENSE Initial commit May 16, 2017 multi: switch over all import paths to point to btcsuite May 23, 2018
bamboozle_unit_test.go test: extend the cf header mismatch cases to include an OP_RETURN script Aug 10, 2018
batch_spend_reporter.go batch_spend_reporter: filter using outpoint in input w/ script Jul 18, 2018
blockmanager.go blockmanager: log more information about header mismatch Oct 18, 2018
blockmanager_test.go blockmanager_test: add TestBlockManagerInitialInverval Oct 18, 2018
blocksubscriptions.go subscriptions+rescan: fix bug in rescans that could cause missed bloc… Jul 27, 2018 multi: update neutrino to use cfcheckpoint based sync, add anti-bambo… Jul 13, 2018
errors.go errors: add ErrGetUtxoCancelled error Aug 21, 2018
glide.lock build: update to latest btcwallet Sep 4, 2018
glide.yaml build: update to latest btcwallet Sep 4, 2018 build: enable Travis CI Oct 26, 2017
headerlogger.go neutrino: rename blockProgressLogger to headerProgressLogger Jul 26, 2018
log.go log: add newLogClosure function Aug 8, 2018
mock_store.go headerfs+neutrino: move mock_store.go into main neutrino package Aug 22, 2018
neutrino.go neutriono+query: rename queryBatch->queryChainServiceBatch, making fu… Oct 18, 2018
notifications.go multi: switch over all import paths to point to btcsuite May 23, 2018
query.go neutriono+query: rename queryBatch->queryChainServiceBatch, making fu… Oct 18, 2018
query_test.go neutrino: update API usage due to package move Aug 23, 2018
rescan.go Revert "rescan: remove filter header check on connected block" Oct 19, 2018
sync_test.go sync_test: use BestBlock Oct 3, 2018
utxoscanner.go utxoscanner: cancel pending reqs + result Aug 23, 2018
utxoscanner_test.go utxoscanner_test: add tests for cancelling GetUtxo Aug 23, 2018

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.


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.


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