|
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 | | -
|
19 | | -## Binding libraries |
20 | | - |
21 | | -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). |
22 | | - |
23 | | -(More binding libraries coming soon, [let me know](https://github.com/shesek/bwt/issues/69) which you'd like to see first!) |
24 | | - |
25 | | - |
26 | | -## C interface |
27 | | - |
28 | | -The interface exposes two functions, for starting and stopping the bwt servers. |
29 | | -Everything else happens through the Electrum/HTTP APIs. |
30 | | - |
31 | | -```c |
32 | | -typedef void (*bwt_init_cb)(void* shutdown_ptr); |
33 | | - |
34 | | -typedef void (*bwt_notify_cb)(const char* msg_type, float progress, |
35 | | - uint32_t detail_n, const char* detail_s); |
36 | | - |
37 | | -int32_t bwt_start(const char* json_config, |
38 | | - bwt_init_cb init_cb, |
39 | | - bwt_notify_cb notify_cb); |
40 | | - |
41 | | -int32_t bwt_shutdown(void* shutdown_ptr); |
42 | | -``` |
43 | | -
|
44 | | -Both functions return `0` on success or `-1` on failure. |
45 | | -
|
46 | | -### `bwt_start(json_config, init_cb, notify_cb)` |
47 | | -
|
48 | | -Start the configured server(s). |
49 | | -
|
50 | | -This will initialize the daemon and start the sync loop, blocking the current thread. |
51 | | -
|
52 | | -`json_config` should be provided as a JSON-encoded string. The list of options is available [below](#config-options). |
53 | | -Example minimal configuration: |
54 | | -
|
55 | | -``` |
56 | | -{ |
57 | | - "bitcoind_dir": "/home/satoshi/.bitcoin", |
58 | | - "descriptors": [ "wpkh(xpub66../0/*)" ], |
59 | | - "electrum_addr": "127.0.0.1:0" |
60 | | -} |
61 | | -``` |
62 | | -
|
63 | | -> You can configure `electrum_addr`/`http_addr` to `127.0.0.1:0` to bind on any available port. |
64 | | -> The assigned port will be reported back via the `ready:X` notifications (see below). |
65 | | -
|
66 | | -The function accepts two callbacks: `init_cb` and `notify_cb`. |
67 | | -
|
68 | | -`init_cb(shutdown_ptr)` will be called with the shutdown pointer (see `bwt_shutdown()`) |
69 | | -right before bwt is started up, after the configuration is validated. |
70 | | -
|
71 | | -The `notify_cb(msg_type, progress, detail_n, detail_s)` callback will be called with error messages, |
72 | | -progress updates and information about the running services, with the `progress` argument indicating the |
73 | | -current progress as a float from 0 to 1. |
74 | | -The meaning of the `detail_{n,s}` field varies for the different `msg_type`s, which are: |
75 | | -
|
76 | | -- `progress:sync` - Progress updates for bitcoind's initial block download. `detail_n` contains the unix |
77 | | - timestamp of the current chain tip. |
78 | | -- `progress:scan` - Progress updates for historical transactions rescanning. `detail_n` contains the estimated |
79 | | - remaining time in seconds. |
80 | | -- `ready:electrum` - The Electrum server is ready. `detail_s` contains the address the server is bound on, |
81 | | - as an `<ip>:<port>` string (useful for ephemeral binding on port 0). |
82 | | -- `ready:http` - The HTTP server is ready. `detail_s` contains the address the server is bound on. |
83 | | -- `ready` - Everything is ready. |
84 | | -- `error` - An error occurred during the initial start-up. `detail_s` contains the error message. |
85 | | -
|
86 | | -> The `detail_s` argument will be deallocated after calling the callback. If you need to keep it around, make a copy of it. |
87 | | -> |
88 | | -> Note that `progress:X` notifications will be sent from a different thread. |
89 | | -
|
90 | | -This function does not return until the daemon is stopped. |
91 | | -
|
92 | | -### `bwt_shutdown(shutdown_ptr)` |
93 | | -
|
94 | | -Shutdown the bwt daemon. |
95 | | -
|
96 | | -Should be called with the shutdown pointer passed to `init_cb()`. |
97 | | -
|
98 | | -If this is called while bitcoind is importing/rescanning addresses, |
99 | | -the daemon will not stop immediatly but will be marked for later termination. |
100 | | -
|
101 | | -## Config Options |
102 | | -
|
103 | | -All options are optional, except for `descriptors`/`xpubs`/`addresses` (of which there must be at least one). |
104 | | -
|
105 | | -To start the API servers, set `electrum_addr`/`http_addr`. |
106 | | -
|
107 | | -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. |
108 | | -
|
109 | | -#### Network and Bitcoin Core RPC |
110 | | -- `network` - one of `bitcoin`, `testnet` or `regtest` (defaults to `bitcoin`) |
111 | | -- `bitcoind_url` - bitcoind url (defaults to `http://localhost:<network-rpc-port>/`) |
112 | | -- `bitcoind_auth` - authentication in `<user>:<pass>` format (defaults to reading from the cookie file) |
113 | | -- `bitcoind_dir` - bitcoind data directory (defaults to `/.bitcoin` on Linux, `~/Library/Application Support/Bitcoin` on Mac, or `%APPDATA%\Bitcoin` on Windows) |
114 | | -- `bitcoind_cookie` - path to cookie file (defaults to `.cookie` in the datadir) |
115 | | -- `bitcoind_wallet` - bitcoind wallet to use (for use with multi-wallet) |
116 | | -
|
117 | | -#### Address tracking |
118 | | -- `descriptors` - an array of descriptors to track |
119 | | -- `xpubs` - an array of xpubs to track (SLIP32 ypubs/zpubs are supported too) |
120 | | -- `addresses` - an array of addresses to track |
121 | | -- `addresses_file` - path to file with addresses (one per line) |
122 | | -- `rescan_since` - the unix timestamp to begin rescanning from, or 'now' to track new transactions only (scans from genesis by default) |
123 | | -- `gap_limit` - the [gap limit](https://github.com/shesek/bwt#gap-limit) for address import (defaults to 20) |
124 | | -- `initial_import_size` - the chunk size to use during the initial import (defaults to 350) |
125 | | -- `force_rescan` - force rescanning for historical transactions, even if the addresses were already previously imported (defaults to false) |
126 | | -
|
127 | | -#### General settings |
128 | | -- `poll_interval` - interval for polling new blocks/transactions from bitcoind in seconds (defaults to 5) |
129 | | -- `tx_broadcast_cmd` - [custom command](https://github.com/shesek/bwt#scriptable-transaction-broadcast) for broadcasting transactions |
130 | | -- `verbose` - verbosity level for stderr log messages (0-4, defaults to 0) |
131 | | -- `require_addresses` - when disabled, the daemon will start even without any configured wallet addresses (defaults to true) |
132 | | -- `setup_logger` - enable stderr logging (defaults to true) |
133 | | -
|
134 | | -#### Electrum |
135 | | -- `electrum_addr` - bind address for electrum server (off by default) |
136 | | -- `electrum_skip_merkle` - skip generating merkle proofs (off by default) |
137 | | -
|
138 | | -#### HTTP |
139 | | -- `http_addr` - bind address for http server (off by default) |
140 | | -- `http_cors` - allowed cross-origins for http server (none by default) |
141 | | -
|
142 | | -#### Web Hooks |
143 | | -- `webhooks_urls` - array of urls to notify with index updates |
144 | | -
|
145 | | -#### UNIX only |
146 | | -- `unix_listener_path` - path to bind the [sync notification](https://github.com/shesek/bwt#real-time-indexing) unix socket (off by default) |
| 1 | +Moved to https://github.com/bwt-dev/libbwt |
0 commit comments