bal-server
Installation
git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server.git
cd bal-server
openssl genpkey -algorithm ED25519 -out private_key.pem
openssl pkey -in private_key.pem -pubout -out public_key.pem
cargo build --release
sudo cp target/release/bal-server target/release/bal-pusher /usr/local/bin
Docker
Build
docker build -t bal-server .
Run
docker run -d \
--name bal-server \
--network host \
--tmpfs /tmp:rw,noexec,nosuid \
-v /path/to/data:/var/bal:rw \
-v /path/to/.bitcoin/regtest/.cookie:/var/bal/.bitcoin/regtest/.cookie:ro \
-e BAL_SERVER_REGTEST_ADDRESS="your_xpub_or_address" \
-e BAL_SERVER_REGTEST_FIXED_FEE=50000 \
-e BAL_SERVER_INFO="BAL server" \
-e BAL_PUSHER_NETWORK=regtest \
-e BAL_PUSHER_REGTEST_ZMQ_HASHBLOCK=tcp://127.0.0.1:28332 \
-e BAL_PUSHER_REGTEST_COOKIE_FILE=/var/bal/.bitcoin/regtest/.cookie \
bal-server
Docker environment variables
| Variable | Description | Default |
|---|---|---|
BAL_PUSHER_NETWORK |
Network to run pusher on (bitcoin, testnet, testnet4, signet, regtest). |
bitcoin |
BAL_PUSHER_REGTEST_ZMQ_HASHBLOCK |
ZMQ endpoint for regtest blocks. | tcp://127.0.0.1:21332 |
BAL_PUSHER_REGTEST_COOKIE_FILE |
Absolute path to Bitcoin Core cookie file inside the container. | - |
Note: The container runs as a non-root
baluser (uid 1000) withtinias PID 1. The/var/balvolume stores the database. Mount Bitcoin Core's cookie file as read-only. When using--network host, ensure only127.0.0.1is used for internal services.
Configuration (bal-server)
The bal-server application can be configured using environment variables.
General
| Variable | Description | Default |
|---|---|---|
BAL_SERVER_DB_FILE |
Path to the SQLite3 database file. | bal.db |
BAL_SERVER_BIND_ADDRESS |
Address to listen on. Never bind to 0.0.0.0 in production without a reverse proxy. |
127.0.0.1 |
BAL_SERVER_BIND_PORT |
Port to listen on. | 9137 |
BAL_SERVER_INFO |
Server info string returned by the / endpoint. |
- |
BAL_SERVER_PUB_KEY_PATH |
Ed25519 public key for signature verification. | public_key.pem |
BAL_SERVER_URL |
Public URL of this server (used for stats reporting). | - |
SSL_KEY_PATH |
Ed25519 private key for signing stats reports. | private_key.pem |
RUST_LOG |
Log level (error, warn, info, debug, trace). |
info |
Per-network addresses and fees
| Variable | Description | Default |
|---|---|---|
BAL_SERVER_BITCOIN_ADDRESS |
xpub or address for mainnet. | - |
BAL_SERVER_BITCOIN_FIXED_FEE |
Fixed fee (satoshis) for mainnet. | 50000 |
BAL_SERVER_REGTEST_ADDRESS |
xpub or address for regtest. | - |
BAL_SERVER_REGTEST_FIXED_FEE |
Fixed fee (satoshis) for regtest. | 50000 |
BAL_SERVER_SIGNET_ADDRESS |
xpub or address for signet. | - |
BAL_SERVER_SIGNET_FIXED_FEE |
Fixed fee (satoshis) for signet. | 50000 |
BAL_SERVER_TESTNET_ADDRESS |
xpub or address for testnet. | - |
BAL_SERVER_TESTNET_FIXED_FEE |
Fixed fee (satoshis) for testnet. | 50000 |
BAL_SERVER_TESTNET4_ADDRESS |
xpub or address for testnet4. | - |
BAL_SERVER_TESTNET4_FIXED_FEE |
Fixed fee (satoshis) for testnet4. | 50000 |
DoS protection (Actix Web)
| Variable | Description | Default |
|---|---|---|
BAL_SERVER_ACTIX_MAX_BODY_SIZE |
Maximum request body size in bytes. | 1048576 (1 MB) |
BAL_SERVER_ACTIX_TIMEOUT_SECS |
Request timeout in seconds. | 5 |
BAL_SERVER_ACTIX_PUSHTXS_PER_SEC |
Rate limit: push txs requests per second. | 1 |
BAL_SERVER_ACTIX_PUSHTXS_BURST |
Rate limit: push txs burst size. | 3 |
BAL_SERVER_ACTIX_SEARCHTX_PER_SEC |
Rate limit: search tx requests per second. | 5 |
BAL_SERVER_ACTIX_SEARCHTX_BURST |
Rate limit: search tx burst size. | 10 |
BAL_SERVER_ACTIX_INFO_PER_SEC |
Rate limit: info requests per second. | 20 |
BAL_SERVER_ACTIX_INFO_BURST |
Rate limit: info burst size. | 30 |
BAL_SERVER_ACTIX_DEFAULT_PER_SEC |
Rate limit: default requests per second. | 50 |
BAL_SERVER_ACTIX_DEFAULT_BURST |
Rate limit: default burst size. | 100 |
BAL_SERVER_ACTIX_WORKERS |
Number of Actix worker threads. | 4 |
BAL_SERVER_ACTIX_MAX_CONNECTIONS |
Maximum concurrent connections. | 100 |
bal-pusher
bal-pusher monitors Bitcoin blocks via ZMQ and pushes time-locked transactions from the database to the Bitcoin network when their locktime exceeds the median time past (MTP).
Prerequisites
- Bitcoin Core with ZMQ support enabled. Add to
bitcoin.conf:zmqpubhashblock=tcp://127.0.0.1:28332 - Rust and Cargo: Rust Installation
- Libraries:
libssl-dev,libsodium-dev,libzmq5-dev,libsqlite3-dev
Running
bal-pusher [bitcoin|testnet|testnet4|signet|regtest]
If no network is specified, defaults to bitcoin.
Configuration (bal-pusher)
General
| Variable | Description | Default |
|---|---|---|
BAL_PUSHER_DB_FILE |
Path to the SQLite3 database file. | bal.db |
BAL_PUSHER_SEND_STATS |
Send stats to welist server. | false |
BAL_SERVER_URL |
URL of bal-server (for stats reporting). | - |
SSL_KEY_PATH |
Ed25519 private key for signing stats reports. | private_key.pem |
WELIST_SERVER_URL |
Welist server URL. | https://welist.bitcoin-after.life |
Per-network configuration
Each network (bitcoin, regtest, testnet, testnet4, signet) supports the following variables.
Replace {NETWORK} with the uppercase network name (e.g., REGTEST, BITCOIN).
| Variable | Description | Default |
|---|---|---|
BAL_PUSHER_{NETWORK}_ZMQ_HASHBLOCK |
ZMQ endpoint for block notifications. | tcp://127.0.0.1:28332 (mainnet) |
BAL_PUSHER_{NETWORK}_COOKIE_FILE |
Absolute path to Bitcoin Core cookie file. | $HOME/.bitcoin/{dir}/.cookie |
BAL_PUSHER_{NETWORK}_RPC_USER |
Bitcoin Core RPC username (alternative to cookie auth). | - |
BAL_PUSHER_{NETWORK}_RPC_PASSWORD |
Bitcoin Core RPC password. | - |
BAL_PUSHER_{NETWORK}_HOST |
Bitcoin Core RPC host. | http://127.0.0.1 |
BAL_PUSHER_{NETWORK}_PORT |
Bitcoin Core RPC port. | 8332 (mainnet) |
BAL_PUSHER_{NETWORK}_DIR_PATH |
Bitcoin Core data directory subfolder. | `` (mainnet) |
Default ZMQ ports per network:
| Network | ZMQ Port | RPC Port |
|---|---|---|
bitcoin |
28332 | 8332 |
regtest |
21332 | 18443 |
testnet |
23332 | 18332 |
testnet4 |
22332 | 48332 |
signet |
24332 | 38332 |