|
| 1 | +# `libbwt` |
| 2 | + |
| 3 | +C FFI library for programmatically managing the Bitcoin Wallet Tracker Electrum RPC and HTTP API servers. |
| 4 | + |
| 5 | +`libbwt` has two primary use-cases: |
| 6 | + |
| 7 | +1. Using the bwt Electrum server as a compatibility layer for Electrum-backed wallets |
| 8 | + that wish to support using a self-hosted Bitcoin Core full node as their backend, |
| 9 | + by running the server *in* the wallet. |
| 10 | + |
| 11 | +2. Shipping software that leverages the [bwt HTTP API](https://github.com/shesek/bwt#http-api) |
| 12 | + as an all-in-one package, without requiring the user to separately install bwt. |
| 13 | + |
| 14 | +Pre-built signed & deterministic `libbwt` library files (`so`/`dylib`/`dll`) are available for download from the |
| 15 | +[releases page](https://github.com/shesek/bwt/releases) for Linux, Mac, Windows and ARMv7/8, including an `electrum_only` variant. |
| 16 | + |
| 17 | +> ⚠️ WARNING: This is an alpha preview, released to gather developers' feedback. It is not ready for general use. |
| 18 | +> *Do not use with real bitcoins.* |
| 19 | +
|
| 20 | +## Binding libraries |
| 21 | + |
| 22 | +A nodejs package wrapping the native library with a more convenient higher-level API is [available here](https://github.com/shesek/bwt/tree/master/contrib/nodejs-bwt-daemon). |
| 23 | + |
| 24 | +(More binding libraries coming soon, [let me know](https://github.com/shesek/bwt/issues/69) which you'd like to see first!) |
| 25 | + |
| 26 | + |
| 27 | +## C interface |
| 28 | + |
| 29 | +The interface exposes two functions, for starting and stopping the bwt servers. |
| 30 | +Everything else happens through the Electrum/HTTP APIs. |
| 31 | + |
| 32 | +```c |
| 33 | +typedef void (*bwt_callback)(const char* msg_type, float progress, |
| 34 | + uint32_t detail_n, const char* detail_s); |
| 35 | + |
| 36 | +int32_t bwt_start(const char* json_config, |
| 37 | + bwt_callback callback, |
| 38 | + void** shutdown_out); |
| 39 | + |
| 40 | +int32_t bwt_shutdown(void* shutdown_ptr); |
| 41 | +``` |
| 42 | +
|
| 43 | +Both functions return `0` on success or `-1` on failure. |
| 44 | +
|
| 45 | +### `bwt_start(json_config, callback, shutdown_out)` |
| 46 | +
|
| 47 | +Start the configured server(s). |
| 48 | +
|
| 49 | +This will block the current thread until the initial indexing is completed and the API servers |
| 50 | +are ready, which may take awhile on the first run (depending on the `rescan_since` configuration). |
| 51 | +If you'd like this to happen in the background, call this function in a new thread. |
| 52 | +
|
| 53 | +`json_config` should be provided as a JSON-encoded string. The list of options is available [below](#config-options). |
| 54 | +Example minimal configuration: |
| 55 | +
|
| 56 | +``` |
| 57 | +{ |
| 58 | + "bitcoind_dir": "/home/satoshi/.bitcoin", |
| 59 | + "descriptors": [ "wpkh(xpub66../0/*)" ], |
| 60 | + "electrum_addr": "127.0.0.1:0", |
| 61 | + "http_addr": "127.0.0.1:0" |
| 62 | +} |
| 63 | +``` |
| 64 | +
|
| 65 | +> You can configure `electrum_addr`/`http_addr` to `127.0.0.1:0` to bind on any available port. |
| 66 | +> The assigned port will be reported back via the `ready:X` notifications (see below). |
| 67 | +
|
| 68 | +The `callback(msg_type, progress, detail_n, detail_s)` function will be called with progress updates and information |
| 69 | +about the running services, with the `progress` argument indicating the current progress as a float from 0 to 1. |
| 70 | +The meaning of the `detail_{n,s}` field varies for the different `msg_type`s, which are: |
| 71 | +
|
| 72 | +- `booting` - Sent after the configuration is validated, right before booting up. `detail_{n,s}` are both empty. |
| 73 | +- `progress:sync` - Progress updates for bitcoind's initial block download. `detail_n` contains the unix timestamp |
| 74 | + that the chain is currently synced up to. |
| 75 | +- `progress:scan` - Progress updates for historical transactions rescanning. `detail_n` contains the estimated |
| 76 | + remaining time in seconds. |
| 77 | +- `ready:electrum` - The Electrum server is ready. `detail_s` contains the address the server is bound on, |
| 78 | + as an `<ip>:<port>` string (useful for ephemeral binding on port 0). |
| 79 | +- `ready:http` - The HTTP server is ready. `detail_s` contains the address the server is bound on. |
| 80 | +- `ready` - Everything is ready. |
| 81 | +- `error` - An error occurred during the initial indexing. `detail_s` contains the error message. |
| 82 | +
|
| 83 | +> The `detail_s` argument will be deallocated after the callback is called. If you need to keep it around, make a copy of it. |
| 84 | +> |
| 85 | +> Note that `progress:X` notifications will be sent from a different thread. |
| 86 | +
|
| 87 | +After the initial indexing is completed, a new thread will be spawned to sync new blocks/transactions in the background. |
| 88 | +
|
| 89 | +A shutdown handler for stopping bwt will be written to `shutdown_out`. |
| 90 | +
|
| 91 | +### `bwt_shutdown(shutdown_ptr)` |
| 92 | +
|
| 93 | +Shutdown bwt's API server(s) and the background syncing thread. |
| 94 | +
|
| 95 | +Should be called with the shutdown handler written to `shutdown_out`. |
| 96 | +
|
| 97 | +## Config Options |
| 98 | +
|
| 99 | +All options are optional, except for `descriptors`/`xpubs`/`bare_xpubs` (of which there must be at least one). |
| 100 | +
|
| 101 | +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. |
| 102 | +
|
| 103 | +#### Network and Bitcoin Core RPC |
| 104 | +- `network` - one of `bitcoin`, `testnet` or `regtest` (defaults to `bitcoin`) |
| 105 | +- `bitcoind_url` - bitcoind url (defaults to `http://localhost:<network-rpc-port>/`) |
| 106 | +- `bitcoind_auth` - authentication in `<user>:<pass>` format (defaults to reading from the cookie file) |
| 107 | +- `bitcoind_dir` - bitcoind data directory (defaults to `/.bitcoin` on Linux, `~/Library/Application Support/Bitcoin` on Mac, or `%APPDATA%\Bitcoin` on Windows) |
| 108 | +- `bitcoind_cookie` - path to cookie file (defaults to `.cookie` in the datadir) |
| 109 | +- `bitcoind_wallet` - bitcoind wallet to use (for use with multi-wallet) |
| 110 | +
|
| 111 | +#### Address tracking |
| 112 | +- `descriptors` - an array of descriptors to track |
| 113 | +- `xpubs` - an array of xpubs to track (SLIP32 ypubs/zpubs are supported too) |
| 114 | +- `bare_xpubs` - an array of bare xpubs to track (no separate internal/external chain) |
| 115 | +- `rescan_since` - the unix timestamp to begin rescanning from, or 'now' to track new transactions only (scans from genesis by default) |
| 116 | +- `gap_limit` - the [gap limit](https://github.com/shesek/bwt#gap-limit) for address import (defaults to 20) |
| 117 | +- `initial_import_size` - the chunk size to use during the initial import (defaults to 350) |
| 118 | +
|
| 119 | +#### General settings |
| 120 | +- `poll_interval` - interval for polling new blocks/transactions from bitcoind in seconds (defaults to 5) |
| 121 | +- `tx_broadcast_cmd` - [custom command](https://github.com/shesek/bwt#scriptable-transaction-broadcast) for broadcasting transactions |
| 122 | +- `verbose` - verbosity level for stderr log messages (0-4, defaults to 0) |
| 123 | +
|
| 124 | +#### Electrum |
| 125 | +- `electrum_addr` - bind address for electrum server (off by default) |
| 126 | +- `electrum_skip_merkle` - skip generating merkle proofs (off by default) |
| 127 | +
|
| 128 | +#### HTTP |
| 129 | +- `http_addr` - bind address for http server (off by default) |
| 130 | +- `http_cors` - allowed cross-origins for http server (none by default) |
| 131 | +
|
| 132 | +#### Web Hooks |
| 133 | +- `webhooks_urls` - array of urls to notify with index updates |
| 134 | +
|
| 135 | +#### UNIX only |
| 136 | +- `unix_listener_path` - path to bind the [sync notification](https://github.com/shesek/bwt#real-time-indexing) unix socket (off by default) |
0 commit comments