libbwt
v0.2.4
Published
A library for programmatically controlling the Bitcoin Wallet Tracker daemons
Downloads
11
Maintainers
Readme
Bitcoin Wallet Tracker - JavaScript bindings
JavaScript bindings for Bitcoin Wallet Tracker, a lightweight personal indexer for bitcoin wallets.
libbwt-nodejs
allows to programmatically manage bwt's Electrum RPC and HTTP API servers.
It can be used as a compatibility layer for easily upgrading Electrum-backed wallets to support a
Bitcoin Core full node backend (by running the Electrum server in the wallet),
or for shipping software that integrates bwt's HTTP API
as an all-in-one package.
It is based on the libbwt
C FFI.
Support development: ⛓️ on-chain or ⚡ lightning via BTCPay
Also see: bwt, libbwt and libbwt-jni.
Usage
Below is a minimally viable setup. If bitcoind is running locally on the default port, at the default datadir location and with cookie auth enabled (the default), this should Just Work™ \o/
import { BwtDaemon } from 'libbwt'
const bwtd = await BwtDaemon({
xpubs: [ 'xpub66...' ],
electrum: true,
}).start()
console.log('bwt electrum server ready on', bwtd.electrum_addr)
With some more advanced options:
const bwtd = await BwtDaemon({
// Network and Bitcoin Core RPC settings
network: 'regtest',
bitcoind_dir: '/home/satoshi/.bitcoin',
bitcoind_url: 'http://127.0.0.1:9008/',
bitcoind_wallet: 'bwt',
// Descriptors and xpubs to track
descriptors: [ 'wpkh(tpub61.../0/*)' ],
xpubs: [ 'tpub66...' ],
// Rescan since timestamp. Accepts unix timestamps, date strings, Date objects, or 'now' to look for new transactions only
rescan_since: '2020-01-01',
// Enable HTTP and Electrum servers (use port 0 to bind on any available port)
electrum_addr: '127.0.0.1:0',
http_addr: '127.0.0.1:0',
// Set the gap limit of watched unused addresses
gap_limit: 100,
// Progress notifications for initial block download and wallet rescanning
sync_progress: (progress, tip_time) =>
console.log(`Initial block download in progress... (${progress*100}% done, synced up to ${tip_time})`),
scan_progress: (progress, eta) =>
console.log(`Wallet rescanning in progress... (${progress*100}% done, ETA ${eta} seconds)`),
}).start()
// Get the assigned address/port for the Electrum/HTTP servers
console.log('bwt electrum server ready on', bwtd.electrum_addr)
console.log('bwt http server ready on', bwtd.http_url)
// Shutdown
bwtd.shutdown()
See example.js
for a more complete example, including connecting to the HTTP API.
The API servers are unauthenticated by default, but authentication can be enabled.
The list of options is available in the libbwt C FFI documentation. The nodejs wrapper also provides the following additional options:
sync_progress
- callback for IBD progress notifications, invoked with(progress, tip_time)
scan_progress
- callback for wallet rescan progress notifications, invoked with(progress, eta)
electrum
- setting totrue
is an alias forelectrum_addr=127.0.0.1:0
http
- setting totrue
is an alias forhttp_addr=127.0.0.1:0
Note that if you call shutdown()
while bitcoind is importing/rescanning addresses, the daemon will
not stop immediately but will be marked for later termination.
Installation
Install from the npm registry:
$ npm install libbwt
(Instructions for installing the signed package are available below.)
The will download the libbwt
library for your platform as a postinstall step.
The currently supported platforms are Linux, Mac, Windows and ARMv7/8.
The hash of the downloaded library is verified against the
SHA256SUMS
file that ships with the npm package.
Note:
libbwt-nodejs
usesffi-napi
, which requires a recent nodejs version. If you're running into errors during installation or segmentation faults, try updating to a newer version, and make sure to install and run libbwt using the same version.
Electrum-only variant
To install libbwt with Electrum support only (without the HTTP API), run BWT_VARIANT=electrum_only npm install libbwt
.
The electrum_only
variant is roughly 33% smaller and comes with less dependencies.
Verifying the signature
The releases are signed by Nadav Ivgi (@shesek). The public key can be verified on the PGP WoT, github, twitter, keybase, hacker news and this video presentation.
# Download
$ wget https://github.com/bwt-dev/libbwt-nodejs/releases/download/v0.2.4/libbwt-nodejs-0.2.4.tgz
# Fetch public key
$ gpg --keyserver keyserver.ubuntu.com --recv-keys FCF19B67866562F08A43AAD681F6104CD0F150FC
# Verify signature
$ wget -qO - https://github.com/bwt-dev/libbwt-nodejs/releases/download/v0.2.4/SHA256SUMS.asc \
| gpg --decrypt - | sha256sum -c -
# Install
$ npm install libbwt-nodejs-0.2.4.tgz
The signature verification should show Good signature from "Nadav Ivgi <[email protected]>" ... Primary key fingerprint: FCF1 9B67 ...
and libbwt-nodejs-0.2.4.tgz: OK
.
Building from source
Build the FFI library for your platform(s) as described here and
copy the libbwt.so
/libbwt.dylib
/bwt.dll
file into the root directory of libbwt-nodejs
.
Reproducible builds
The nodejs package (including the LIBBWT-SHA256SUMS
file with the libbwt
hashes for all platforms)
can be reproduced in a Docker container environment as follows:
$ git clone https://github.com/bwt-dev/libbwt-nodejs && cd libbwt-nodejs
$ git checkout <tag>
$ git verify-commit HEAD
$ git submodule update --init --recursive
# Build libbwt FFI library files for Linux, Windows, ARMv7 and ARMv8
$ docker build -t bwt-builder - < bwt/scripts/builder.Dockerfile
$ docker run -it --rm -u `id -u` -v `pwd`/libbwt:/usr/src/libbwt -w /usr/src/libbwt \
--entrypoint scripts/build.sh bwt-builder
# Build libbwt FFI library files for Mac OSX (cross-compiled via osxcross)
$ docker build -t bwt-builder-osx - < bwt/scripts/builder-osx.Dockerfile
$ docker run -it --rm -u `id -u` -v `pwd`/libbwt:/usr/src/libbwt -w /usr/src/libbwt \
--entrypoint scripts/build.sh bwt-builder-osx
# Build libbwt-nodejs npm package
$ docker run -it --rm -u `id -u` -v `pwd`:/usr/src/libbwt-nodejs -w /usr/src/libbwt-nodejs \
-e LIBBWT_DIST=/usr/src/libbwt-nodejs/libbwt/dist \
--entrypoint scripts/build.sh node:14
$ sha256sum dist/*.tgz
You may set -e TARGETS=...
to a comma separated list of the platforms to build.
The available platforms are: x86_64-linux
, x86_64-osx
, x86_64-windows
, arm32v7-linux
and arm64v8-linux
.
Both variants will be built by default. To build the electrum_only
variant only, set -e ELECTRUM_ONLY_ONLY=1
.
The builds are reproduced on Travis CI using the code from GitHub. The SHA256 checksums are available under the "Reproducible builds" stage.
License
MIT