Files

svatantrya df8effcc60 refactor: remove bal-pusher-enhanced and update docs/env

- Remove src/bin/bal-pusher-enhanced.rs (synchronous pusher variant)
- Remove bal-pusher.env and bal-pusher.sh from git tracking (now in .gitignore)
- Update all documentation to remove references to bal-pusher-enhanced:
  * 01_project_overview.md
  * 02_glossary_and_bitcoin_domain.md
  * 03_architecture_and_data_flow.md
  * 04_modules_detail.md
  * 05_api_reference.md (remove rawblock ZMQ section, update references)
  * 08_security_audit.md (remove references to bal-pusher-enhanced in DoS and ZMQ sections)
  * 09_references_and_links.md
- Build verified: cargo check passes for bal-pusher and bal-server binaries

2026-07-16 14:32:59 -04:00

2.2 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. 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 three primary binaries and two shared libraries:

bal-server: Async HTTP server (hyper + tokio) that exposes the API for receiving transactions and serving statistics.
bal-pusher: Async daemon that listens for hashblock ZMQ messages and pushes pending transactions to a Bitcoin node via RPC.
lib.rs: Exports the shared modules db and xpub.
db.rs: All database operations and schema creation for SQLite 0.34.0.
xpub.rs: Address derivation from xpub/zpub using BIP-84 and the bitcoin crate.

Mapping to Existing Documentation

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

2.2 KiB Raw Blame History