Files

docker: add release Dockerfile, fix build deps and feature-split builds

- Add Dockerfile.release: downloads latest release from Gitea, verifies SHA-256
- Fix Dockerfile: remove unused libsodium/cmake, add libsqlite3-dev
- Split build per binary with --no-default-features --features server/pusher
- Remove Cargo.lock from .dockerignore for reproducible builds
- Update README and knowledge base with Dockerfile.release docs

2026-07-20 17:36:58 -04:00

3.4 KiB

Raw Blame History

Project Overview

Quick Reference

What this file contains: vision, scope, system components, and mapping to existing documentation.
See also: 02_glossary_and_bitcoin_domain.md, 03_architecture_and_data_flow.md

Vision and Scope

bal_server is a Rust-based Bitcoin transaction executor server (v0.3.2, edition 2024). It receives raw Bitcoin transactions via HTTP, validates them, persists them in a local SQLite database, and coordinates their broadcast on-chain after a locktime condition expires. The system supports multiple Bitcoin networks (mainnet, testnet, regtest, testnet4, signet) and tracks extended public keys (xpub) for fee collection.

Key Goals

Receive and validate raw Bitcoin transactions with locktime.
Store transactions, inputs, and outputs in a structured database.
Monitor new blocks via ZMQ and push transactions to the Bitcoin network when the locktime is satisfied.
Track derived addresses and extended public keys for fee accounting.
Collect and report statistics about the service.

System Components

The project consists of two binaries and one shared library:

bal-server: Async HTTP server (actix-web 4.9.0 + actix-rt) that exposes the API for receiving transactions and serving statistics. Includes rate limiting via actix-governor.
bal-pusher: Async daemon (tokio) that listens for hashblock ZMQ messages and pushes pending transactions to a Bitcoin node via RPC.
lib.rs: Exports the shared modules db, xpub, and validation.

Library Modules

db.rs: All database operations, schema creation, path validation, and WAL mode for SQLite 0.34.0.
xpub.rs: Address derivation from xpub/zpub/ypub using BIP-84 and the bitcoin crate.
validation.rs: SSRF protection for the welist URL, blocking private/internal IP ranges.

Feature Flags

The project uses Cargo feature flags to build each binary independently:

Feature	Dependencies	Binary
`server` (default)	`actix-web`, `actix-governor`, `actix-rt`, `chrono`, `hex-conservative`	`bal-server`
`pusher` (default)	`zmq`, `reqwest`, `byteorder`, `base64`, `ed25519-dalek`	`bal-pusher`

Docker Support

Two Dockerfiles are provided:

Dockerfile.release (recommended for production): Downloads the latest pre-built release from the Gitea server. No Rust toolchain needed. Verifies SHA-256 checksum. Supports pinning a specific version via BAL_VERSION build arg.
Dockerfile (for development/custom builds): Multi-stage build using rust:1.95-bookworm as the builder and debian:bookworm-slim as the runtime. Each binary is compiled with only its required features (--no-default-features --features server / --features pusher).

Both run as a non-root bal user (uid 1000) with tini as PID 1 and include a healthcheck endpoint.

Mapping to Existing Documentation

Existing File	Subject	Covered in this KB
`README.md`	Installation, environment variables, ZMQ dependency, Docker	`07_deployment_and_ops.md`
`RPC.md`	API endpoint specification	`05_api_reference.md`
`AGENTS.md`	Security guidelines for agents	`08_security_audit.md`

3.4 KiB Raw Blame History