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

docs/02_glossary_and_bitcoin_domain.md

@@ -0,0 +1,51 @@
+# Glossary and Bitcoin Domain Knowledge
+
+## Quick Reference
+- **What this file contains:** Bitcoin-specific concepts, protocols, and standards needed to understand this codebase.
+- **See also:** [01_project_overview.md](01_project_overview.md), [04_modules_detail.md](04_modules_detail.md)
+
+## BIP-84: Derivation Path for P2WPKH
+
+BIP-84 defines the derivation path for native SegWit (Bech32) addresses (P2WPKH). The standard path is `m/84'/<coin_type>'/<account>'/0/<address_index>`. In this project, `xpub.rs` derives P2WPKH addresses from an xpub or zpub using the path `m/84'/coin_type'/account'/0/index`. The `bitcoin` crate's `Xpub::derive_pub` and `Secp256k1` are used in `src/xpub.rs`.
+
+## XPub, ZPub, and Extended Public Keys
+
+An **XPub** (Extended Public Key) is a master key that allows derivation of child public keys without revealing private keys. A **ZPub** is the Bech32-encoded equivalent for native SegWit. The codebase uses `xpub.rs` to derive addresses from these and verify their checksums. See `src/xpub.rs` for the Base58 decoding and checksum logic.
+
+## Locktime and nLockTime
+
+A Bitcoin transaction can include a `nLockTime` field. If it is non-zero and below `500_000_000`, it is interpreted as a **block height** before which the transaction cannot be mined. If above, it is a **Unix timestamp**. The system evaluates whether the locktime has been met by comparing it against the blockchain's median time. See `src/bin/bal-pusher.rs` and `src/bin/bal-pusher-enhanced.rs` for the evaluation logic.
+
+## P2WPKH (Pay to Witness Public Key Hash)
+
+P2WPKH is a native SegWit output format that reduces transaction size and lowers transaction fees. The addresses are Bech32 encoded (e.g., `bc1q...`). The project assumes fee collection outputs are P2WPKH and uses `bitcoin::Address::p2wpkh` for derivation in `src/xpub.rs`.
+
+## Bitcoin Block Header (80 bytes)
+
+A Bitcoin block header is a fixed 80-byte structure containing `version` (4 bytes), `previous block hash` (32 bytes), `merkle root` (32 bytes), `timestamp` (4 bytes), `bits` (4 bytes), and `nonce` (4 bytes). The `bal-pusher-enhanced` binary reads the raw 80-byte block from the `rawblock` ZMQ topic and extracts the timestamp from byte offset 68-72. This avoids the need for an RPC call to `getblockchaininfo`. See `src/bin/bal-pusher-enhanced.rs`.
+
+## ZMQ Publisher
+
+Bitcoin Core can publish notifications over ZeroMQ. The project listens to two topics:
+- **`hashblock`**: Sends the 32-byte block hash when a new block is found. The `bal-pusher` uses this to trigger an update cycle.
+- **`rawblock`**: Sends the full raw block (including the 80-byte header). The `bal-pusher-enhanced` uses this to derive the timestamp without RPC.
+
+The ZMQ endpoint is per-network:
+- Bitcoin: `tcp://127.0.0.1:28332`
+- Regtest: `tcp://127.0.0.1:21332`
+- Testnet: `tcp://127.0.0.1:23332`
+- Testnet4: `tcp://127.0.0.1:24332`
+- Signet: `tcp://127.0.0.1:22332`
+
+## Bitcoin Core RPC
+
+The project communicates with a local Bitcoin Core node via the JSON-RPC interface. Key methods used are:
+- `sendrawtransaction`: To broadcast a pending transaction.
+- `getblockchaininfo`: To retrieve the current block height and `mediantime` (used to evaluate locktime). `Note:` `bal-pusher-enhanced` does not use this method to avoid RPC round-trips for median time.
+- `getblock`: To retrieve block data in `bal-pusher` (for median time calculation).
+
+Authentication is done via `bitcoincore-rpc` using either `UserPass` or `CookieFile` (the `cookie` file is stored in `~/.bitcoin/.cookie`). See `src/bin/bal-pusher.rs`.
+
+## Mempool and P2P
+
+Transactions are validated against mempool rules before submission. The server checks that the fee output is paid to a specific address owned by the operator. It also ensures the transaction can be deserialized using the `bitcoin::Transaction` parser from the `bitcoin` crate. See `src/bin/bal-server.rs` (`pushtxs` endpoint).