libbwt

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

• Usage
• Installation
  • Electrum only
  • Verifying the signature
• Building from source
• Reproducible builds
• License

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 to true is an alias for electrum_addr=127.0.0.1:0
• http - setting to true is an alias for http_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 uses ffi-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 <[e-mail]>" ... 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