{"id":19219374,"url":"https://github.com/bwt-dev/libbwt","last_synced_at":"2026-03-11T10:32:15.794Z","repository":{"id":117492570,"uuid":"325466892","full_name":"bwt-dev/libbwt","owner":"bwt-dev","description":"C FFI for Bitcoin Wallet Tracker, a lightweight personal indexer for bitcoin wallets","archived":false,"fork":false,"pushed_at":"2021-10-06T14:31:23.000Z","size":151,"stargazers_count":5,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-13T00:43:55.847Z","etag":null,"topics":["bitcoin","bitcoin-wallet-tracker","bwt","ffi"],"latest_commit_sha":null,"homepage":"https://bwt.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bwt-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-30T05:50:57.000Z","updated_at":"2024-05-17T16:51:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"6746ed78-4938-4f65-a912-ac869d5b231e","html_url":"https://github.com/bwt-dev/libbwt","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/bwt-dev/libbwt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwt-dev%2Flibbwt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwt-dev%2Flibbwt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwt-dev%2Flibbwt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwt-dev%2Flibbwt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bwt-dev","download_url":"https://codeload.github.com/bwt-dev/libbwt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwt-dev%2Flibbwt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30378084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","bitcoin-wallet-tracker","bwt","ffi"],"created_at":"2024-11-09T14:30:58.563Z","updated_at":"2026-03-11T10:32:15.777Z","avatar_url":"https://github.com/bwt-dev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bitcoin Wallet Tracker - C FFI\n\n[![Build Status](https://travis-ci.org/bwt-dev/libbwt.svg?branch=master)](https://travis-ci.org/bwt-dev/libbwt)\n[![Latest release](https://img.shields.io/github/v/release/bwt-dev/libbwt?color=orange)](https://github.com/bwt-dev/libbwt/releases/tag/v0.2.4)\n[![Downloads](https://img.shields.io/github/downloads/bwt-dev/libbwt/total.svg?color=blueviolet)](https://github.com/bwt-dev/libbwt/releases)\n[![MIT license](https://img.shields.io/github/license/bwt-dev/libbwt.svg?color=yellow)](https://github.com/bwt-dev/libbwt/blob/master/LICENSE)\n[![Pull Requests Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/bwt-dev/bwt#developing)\n\nC FFI for [Bitcoin Wallet Tracker](https://github.com/bwt-dev/bwt), a lightweight personal indexer for bitcoin wallets.\n\n`libbwt` allows to programmatically manage bwt's Electrum RPC and HTTP API servers.\nIt can be used as a compatibility layer for easily upgrading Electrum-backed wallets to support a\nBitcoin Core full node backend (by running the Electrum server *in* the wallet),\nor for shipping software that integrates bwt's [HTTP API](https://github.com/bwt-dev/bwt#http-api)\nas an all-in-one package.\n\nSupport development: [⛓️ on-chain or ⚡ lightning via BTCPay](https://btcpay.shesek.info/)\n\n- [C interface](#c-interface)\n- [Installation](#installation)\n  - [Electrum only](#electrum-only-variant)\n  - [Verifying the signature](#verifying-the-signature)\n- [Config options](#config-options)\n- [Building from source](#building-from-source)\n- [Reproducible builds](#reproducible-builds)\n- [License](#license)\n\n\u003e Also see: [bwt](https://github.com/bwt-dev/bwt), [libbwt-jni](https://github.com/bwt-dev/libbwt-jni) and [libbwt-nodejs](https://github.com/bwt-dev/libbwt-nodejs).\n\n\n## C interface\n\nThe interface exposes two functions, for starting and stopping the bwt daemon.\nEverything else is done through the Electrum/HTTP APIs.\n\n```c\ntypedef void (*bwt_init_cb)(void* shutdown_ptr);\n\ntypedef void (*bwt_notify_cb)(const char* msg_type, float progress,\n                                uint32_t detail_n, const char* detail_s);\n\nint32_t bwt_start(const char* json_config,\n                  bwt_init_cb init_cb,\n                  bwt_notify_cb notify_cb);\n\nint32_t bwt_shutdown(void* shutdown_ptr);\n```\n\nBoth functions return `0` on success or `-1` on failure.\n\n#### `bwt_start(json_config, init_cb, notify_cb)`\n\nStart the configured server(s).\n\nThis will initialize the daemon and start the sync loop, blocking the current thread.\n\n`json_config` should be provided as a JSON-encoded string. The list of options is available [below](#config-options).\nExample minimal configuration:\n\n```\n{\n  \"bitcoind_dir\": \"/home/satoshi/.bitcoin\",\n  \"descriptors\": [ \"wpkh(xpub66../0/*)\" ],\n  \"electrum_addr\": \"127.0.0.1:0\"\n}\n```\n\n\u003e You can configure `electrum_addr`/`http_addr` to `127.0.0.1:0` to bind on any available port.\n\u003e The assigned port will be reported back via the `ready:X` notifications (see below).\n\nThe function accepts two callbacks: `init_cb` and `notify_cb`.\n\n`init_cb(shutdown_ptr)` will be called with the shutdown pointer (see `bwt_shutdown()`)\nright before bwt is started up, after the configuration is validated.\n\nThe `notify_cb(msg_type, progress, detail_n, detail_s)` callback will be called with error messages,\ninformation about the running services and progress updates, with the `progress` argument indicating the\ncurrent progress as a float from 0 to 1.\nThe meaning of the `detail_{n,s}` field varies for the different `msg_type`s, which are:\n\n- `progress:sync` - Progress updates for bitcoind's initial block download. `detail_n` contains the unix\n  timestamp of the current chain tip.\n- `progress:scan` - Progress updates for historical transactions rescanning. `detail_n` contains the estimated\n  remaining time in seconds.\n- `access_token` - When `auth_ephemeral` is enabled (see below), `detail_s` contains the randomly generated access token.\n- `ready:electrum` - The Electrum server is ready. `detail_s` contains the address the server is bound on,\n  as an `\u003cip\u003e:\u003cport\u003e` string (useful for ephemeral binding on port 0).\n- `ready:http` - The HTTP server is ready. `detail_s` contains the address the server is bound on.\n- `ready` - Everything is ready.\n- `error` - An error occurred during the initial start-up. `detail_s` contains the error message.\n\n\u003e The `detail_s` argument will be deallocated after calling the callback. If you need to keep it around, make a copy of it.\n\u003e\n\u003e Note that `progress:X` notifications will be sent from a different thread.\n\nThis function does not return until the daemon is stopped.\n\n#### `bwt_shutdown(shutdown_ptr)`\n\nShutdown the bwt daemon.\n\nShould be called with the shutdown pointer passed to `init_cb()`.\n\nIf this is called while bitcoind is importing/rescanning addresses,\nthe daemon will not stop immediately but will be marked for later termination.\n\n## Installation\n\nPre-built [signed](#verifying-the-signature) \u0026 [deterministic](#reproducible-builds) `libbwt` library\nfiles are available for download from the [releases page](https://github.com/bwt-dev/libbwt/releases)\nfor Linux, Mac, Windows and ARMv7/8.\n\n\u003e ⚠️ The pre-built libraries are meant to make it easier to get started. If you're integrating bwt\n\u003e into real-world software, [building from source](#building-from-source) is *highly* recommended.\n\n\n#### Electrum-only variant\n\nThe pre-built libraries are also available for download as an `electrum_only` variant,\nwhich doesn't include the HTTP API server. It is roughly 33% smaller and comes with less dependencies.\n\n#### Verifying the signature\n\nThe releases are signed by Nadav Ivgi (@shesek).\nThe public key can be verified on\nthe [PGP WoT](http://keys.gnupg.net/pks/lookup?op=vindex\u0026fingerprint=on\u0026search=0x81F6104CD0F150FC),\n[github](https://api.github.com/users/shesek/gpg_keys),\n[twitter](https://twitter.com/shesek),\n[keybase](https://keybase.io/nadav),\n[hacker news](https://news.ycombinator.com/user?id=nadaviv)\nand [this video presentation](https://youtu.be/SXJaN2T3M10?t=4) (bottom of slide).\n\n```bash\n# Download (change x86_64-linux to your platform)\n$ wget https://github.com/bwt-dev/libbwt/releases/download/v0.2.4/libbwt-0.2.4-x86_64-linux.tar.gz\n\n# Fetch public key\n$ gpg --keyserver keyserver.ubuntu.com --recv-keys FCF19B67866562F08A43AAD681F6104CD0F150FC\n\n# Verify signature\n$ wget -qO - https://github.com/bwt-dev/libbwt/releases/download/v0.2.4/SHA256SUMS.asc \\\n  | gpg --decrypt - | grep x86_64-linux.tar.gz | sha256sum -c -\n```\n\nThe signature verification should show `Good signature from \"Nadav Ivgi \u003cnadav@shesek.info\u003e\" ... Primary key fingerprint: FCF1 9B67 ...` and `libbwt-0.2.4-x86_64-linux.tar.gz: OK`.\n\n\n## Config Options\n\nAll options are optional, except for `descriptors`/`xpubs`/`addresses` (of which there must be at least one).\n\nTo start the API servers, set `electrum_addr`/`http_addr`.\n\n#### Network and Bitcoin Core RPC\n- `network` - one of `bitcoin`, `testnet`, `signet` or `regtest` (defaults to `bitcoin`)\n- `bitcoind_url` - bitcoind url (defaults to `http://localhost:\u003cnetwork-rpc-port\u003e/`)\n- `bitcoind_auth` - authentication in `\u003cuser\u003e:\u003cpass\u003e` format (defaults to reading from the cookie file)\n- `bitcoind_dir` - bitcoind data directory (defaults to `~/.bitcoin` on Linux, `~/Library/Application Support/Bitcoin` on Mac, or `%APPDATA%\\Bitcoin` on Windows)\n- `bitcoind_cookie` - path to cookie file (defaults to `.cookie` in the datadir)\n- `bitcoind_wallet` - bitcoind wallet to use (for use with multi-wallet)\n- `create_wallet_if_missing` - create the bitcoind wallet if it's missing (defaults to false)\n\n\u003e If bitcoind is running locally on the default port, at the default datadir location and with cookie auth enabled (the default),\n\u003e connecting to it should Just Work™, no configuration needed.\n\n#### Address tracking\n- `descriptors` - an array of descriptors to track\n- `xpubs` - an array of xpubs to track (SLIP32 ypubs/zpubs are supported too)\n- `addresses` - an array of addresses to track\n- `addresses_file` - path to file with addresses (one per line)\n- `rescan_since` - the unix timestamp to begin rescanning from, or 'now' to track new transactions only (the default)\n- `gap_limit` - the [gap limit](https://github.com/bwt-dev/bwt#gap-limit) for address import (defaults to 20)\n- `initial_import_size` - the chunk size to use during the initial import (defaults to 350)\n- `force_rescan` - force rescanning for historical transactions, even if the addresses were already previously imported (defaults to false)\n- `no_wait_sync` - don't wait for bitcoind to finish syncing up before importing addresses (useful with pruning for scanning during IBD, off by default)\n\n### Authentication\n\nThe API servers are unauthenticated by default. To enable authentication, set one of the following options:\n\n- `auth_cookie` - set to a file path to enable cookie file based authentication\n- `auth_token` - enable authentication with a specified access token\n- `auth_ephemeral`  - set to `true` to generate a random ephemeral token and report it back via the `token` notification\n\nSee [`auth.md`](https://github.com/bwt-dev/bwt/blob/master/doc/auth.md) for more information about authentication.\n\n#### General settings\n- `poll_interval` - interval for polling new blocks/transactions from bitcoind in seconds (defaults to 5)\n- `tx_broadcast_cmd` - [custom command](https://github.com/bwt-dev/bwt#scriptable-transaction-broadcast) for broadcasting transactions\n- `verbose` - verbosity level for stderr log messages (0-4, defaults to 0)\n- `require_addresses` - when disabled, the daemon will start even without any configured wallet addresses (defaults to true)\n- `setup_logger` - enable stderr logging (defaults to true)\n- `prune_until` - prune blocks before the given height or unix timestamp (off by default, requires bitcoind to be configured with `prune=1`)\n\n#### Electrum\n- `electrum_addr` - bind address for electrum server (off by default)\n- `electrum_skip_merkle` - skip generating merkle proofs (off by default)\n\n#### HTTP\n- `http_addr` - bind address for http server (off by default)\n- `http_cors` - allowed cross-origins for http server (none by default)\n\n#### Web Hooks\n- `webhooks_urls` - array of urls to notify with index updates\n\n#### UNIX only\n- `unix_listener_path` - path to bind the [sync notification](https://github.com/bwt-dev/bwt#real-time-indexing) unix socket (off by default)\n\n\n\n## Building from source\n\nManually build the C FFI library for a single platform (requires Rust):\n\n```bash\n$ git clone https://github.com/bwt-dev/libbwt \u0026\u0026 cd libbwt\n$ git checkout \u003ctag\u003e\n$ git verify-commit HEAD\n$ git submodule update --init\n\n$ cargo build --release --target \u003cplatform\u003e\n```\n\nThe library file will be available in `target/\u003cplatform\u003e/release`, named\n`libbwt.so` for Linux/Android/ARM, `libbwt.dylib` for OSX, or `bwt.dll` for Windows.\n\nTo build the `electrum_only` variant, set `--no-default-features --features electrum`.\n\n## Reproducible builds\n\nThe library files for all supported platforms can be reproduced\nin a Docker container environment as follows:\n\n```bash\n$ git clone https://github.com/bwt-dev/libbwt \u0026\u0026 cd libbwt\n$ git checkout \u003ctag\u003e\n$ git verify-commit HEAD\n$ git submodule update --init\n\n# Linux, Windows, ARMv7 and ARMv8\n$ docker build -t bwt-builder - \u003c bwt/scripts/builder.Dockerfile\n$ docker run -it --rm -u `id -u` -v `pwd`:/usr/src/libbwt -w /usr/src/libbwt \\\n  --entrypoint scripts/build.sh bwt-builder\n\n# Mac OSX (cross-compiled via osxcross)\n$ docker build -t bwt-builder-osx - \u003c bwt/scripts/builder-osx.Dockerfile\n$ docker run -it --rm -u `id -u` -v `pwd`:/usr/src/libbwt -w /usr/src/libbwt \\\n  --entrypoint scripts/build.sh bwt-builder-osx\n\n$ sha256sum dist/*.tar.gz\n```\n\nYou may set `-e TARGETS=...` to a comma separated list of the platforms to build. \nThe available platforms are: `x86_64-linux`, `x86_64-osx`, `x86_64-windows`, `arm32v7-linux` and `arm64v8-linux`.\n\nBoth variants will be built by default. To build the `electrum_only` variant only, set `-e ELECTRUM_ONLY_ONLY=1`.\n\nThe builds are [reproduced on Travis CI](https://travis-ci.org/github/bwt-dev/libbwt/branches) using the code from GitHub.\nThe SHA256 checksums are available under the \"Reproducible builds\" stage.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwt-dev%2Flibbwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbwt-dev%2Flibbwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwt-dev%2Flibbwt/lists"}