Files

svatantrya 69d877a360 docs: add comprehensive knowledge base and security audit

- Add docs/INDEX.md with navigable index and quick reference guides
- Add 9 knowledge base files covering project overview, Bitcoin domain,
  architecture, modules, API reference, database schema, deployment/security
- Update AGENTS.md with knowledge base reference and update policy
- Add tests/sql_injection_tests.rs with regression tests for SQL injection
- Fix SQL injection vulnerabilities in bal-pusher.rs:
  * Replace string-formatted UPDATE IN with loop + parameterized queries
  * Replace string-formatted UPDATE push_err with parameterized query
  * Add chain name validation in calculate_stats to prevent env var tampering
- Update .gitignore to exclude bal-pusher.env and bal-pusher.sh

2026-07-16 14:11:18 -04:00

2.3 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.
bal-pusher-enhanced: Synchronous variant of the pusher that listens for rawblock ZMQ messages and computes the block median time from the raw header without RPC calls.
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.3 KiB Raw Blame History