Home

Awesome

Bitcoin Wallet Tracker - C FFI

Build Status Latest release Downloads MIT license Pull Requests Welcome

C FFI for Bitcoin Wallet Tracker, a lightweight personal indexer for bitcoin wallets.

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

Support development: ⛓️ on-chain or ⚡ lightning via BTCPay

Also see: bwt, libbwt-jni and libbwt-nodejs.

C interface

The interface exposes two functions, for starting and stopping the bwt daemon. Everything else is done through the Electrum/HTTP APIs.

typedef void (*bwt_init_cb)(void* shutdown_ptr);

typedef void (*bwt_notify_cb)(const char* msg_type, float progress,
                                uint32_t detail_n, const char* detail_s);

int32_t bwt_start(const char* json_config,
                  bwt_init_cb init_cb,
                  bwt_notify_cb notify_cb);

int32_t bwt_shutdown(void* shutdown_ptr);

Both functions return 0 on success or -1 on failure.

bwt_start(json_config, init_cb, notify_cb)

Start the configured server(s).

This will initialize the daemon and start the sync loop, blocking the current thread.

json_config should be provided as a JSON-encoded string. The list of options is available below. Example minimal configuration:

{
  "bitcoind_dir": "/home/satoshi/.bitcoin",
  "descriptors": [ "wpkh(xpub66../0/*)" ],
  "electrum_addr": "127.0.0.1:0"
}

You can configure electrum_addr/http_addr to 127.0.0.1:0 to bind on any available port. The assigned port will be reported back via the ready:X notifications (see below).

The function accepts two callbacks: init_cb and notify_cb.

init_cb(shutdown_ptr) will be called with the shutdown pointer (see bwt_shutdown()) right before bwt is started up, after the configuration is validated.

The notify_cb(msg_type, progress, detail_n, detail_s) callback will be called with error messages, information about the running services and progress updates, with the progress argument indicating the current progress as a float from 0 to 1. The meaning of the detail_{n,s} field varies for the different msg_types, which are:

The detail_s argument will be deallocated after calling the callback. If you need to keep it around, make a copy of it.

Note that progress:X notifications will be sent from a different thread.

This function does not return until the daemon is stopped.

bwt_shutdown(shutdown_ptr)

Shutdown the bwt daemon.

Should be called with the shutdown pointer passed to init_cb().

If this is called while bitcoind is importing/rescanning addresses, the daemon will not stop immediately but will be marked for later termination.

Installation

Pre-built signed & deterministic libbwt library files are available for download from the releases page for Linux, Mac, Windows and ARMv7/8.

⚠️ The pre-built libraries are meant to make it easier to get started. If you're integrating bwt into real-world software, building from source is highly recommended.

Electrum-only variant

The pre-built libraries are also available for download as an electrum_only variant, which doesn't include the HTTP API server. It 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 (bottom of slide).

# Download (change x86_64-linux to your platform)
$ wget https://github.com/bwt-dev/libbwt/releases/download/v0.2.4/libbwt-0.2.4-x86_64-linux.tar.gz

# Fetch public key
$ gpg --keyserver keyserver.ubuntu.com --recv-keys FCF19B67866562F08A43AAD681F6104CD0F150FC

# Verify signature
$ wget -qO - https://github.com/bwt-dev/libbwt/releases/download/v0.2.4/SHA256SUMS.asc \
  | gpg --decrypt - | grep x86_64-linux.tar.gz | sha256sum -c -

The signature verification should show Good signature from "Nadav Ivgi <nadav@shesek.info>" ... Primary key fingerprint: FCF1 9B67 ... and libbwt-0.2.4-x86_64-linux.tar.gz: OK.

Config Options

All options are optional, except for descriptors/xpubs/addresses (of which there must be at least one).

To start the API servers, set electrum_addr/http_addr.

Network and Bitcoin Core RPC

If bitcoind is running locally on the default port, at the default datadir location and with cookie auth enabled (the default), connecting to it should Just Work™, no configuration needed.

Address tracking

Authentication

The API servers are unauthenticated by default. To enable authentication, set one of the following options:

See auth.md for more information about authentication.

General settings

Electrum

HTTP

Web Hooks

UNIX only

Building from source

Manually build the C FFI library for a single platform (requires Rust):

$ git clone https://github.com/bwt-dev/libbwt && cd libbwt
$ git checkout <tag>
$ git verify-commit HEAD
$ git submodule update --init

$ cargo build --release --target <platform>

The library file will be available in target/<platform>/release, named libbwt.so for Linux/Android/ARM, libbwt.dylib for OSX, or bwt.dll for Windows.

To build the electrum_only variant, set --no-default-features --features electrum.

Reproducible builds

The library files for all supported platforms can be reproduced in a Docker container environment as follows:

$ git clone https://github.com/bwt-dev/libbwt && cd libbwt
$ git checkout <tag>
$ git verify-commit HEAD
$ git submodule update --init

# Linux, Windows, ARMv7 and ARMv8
$ docker build -t bwt-builder - < bwt/scripts/builder.Dockerfile
$ docker run -it --rm -u `id -u` -v `pwd`:/usr/src/libbwt -w /usr/src/libbwt \
  --entrypoint scripts/build.sh bwt-builder

# 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`:/usr/src/libbwt -w /usr/src/libbwt \
  --entrypoint scripts/build.sh bwt-builder-osx

$ sha256sum dist/*.tar.gz

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