bitcoinafterlife/bal-server
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
707d5b103211ecfcb38336170ec6ba4bed74ff98
bal-server/docs/09_references_and_links.md
svatantrya 707d5b1032 feat(contrib): add ping key revocation helper 
- Add make_ping_key_revocation.py: onion revocations are signed by the
  identity key, DNS TXT revocations are self-signed by the revoked key
- Document the revocation format, endpoint, helper usage, lifetime and
  no-revocation-of-identity-key limits
- Update the security audit, references and env docs for the new flow and
  the v2/onion-only scope
2026-11-09 00:45:43 -04:00

8.5 KiB
Raw Blame History

References and Links

Quick Reference

Source Code References

Module/Component File Path Key Details
Library src/lib.rs Exports db, validation, xpub modules
Database src/db.rs SQL schema, open_db, execute_insert, WAL mode, path validation
XPub/Address Derivation src/xpub.rs new_address_from_xpub, get_bitcoincore_descriptor, calculate_fingerprint, BIP-84
SSRF Validation src/validation.rs is_valid_welist_url, blocks private/internal IPs
HTTP Server src/bin/bal-server.rs Actix-web 4.9.0, rate limiting, 7 routes, Arc<Mutex<Connection>>
Async Pusher src/bin/bal-pusher.rs ZMQ hashblock, RPC + Reqwest, Ed25519 signing, calculate_stats
Script/Config Path Purpose
Release script make_release.sh Builds release, creates tag, uploads to Gitea (token from .env)
DB download script download_bal_db.sh scp from remote
Server dev script bal-server.sh Sources bal-server.env, cargo run
Pusher dev script bal-pusher.sh Sources bal-pusher.env, cargo run
Send transaction script sendtx.sh bitcoin-cli wrapper for testing
Utility scripts lib.sh Colored echo functions
Contrib (install) contrib/download_and_install_bal.sh Nginx, Certbot, systemd setup
Contrib (install bitcoind) contrib/download_and_install_bitcoincore.sh Bitcoind download, GPG verify, systemd, config
Contrib (install Tor) contrib/install_tor.sh Tor repository, ControlPort 9051
Contrib (onion delegation) contrib/make_onion_delegation.py Issues the v3 onion ping delegation certificate from a Tor or PKCS#8 identity key
Contrib (key revocation) contrib/make_ping_key_revocation.py Issues an onion (identity-signed) or DNS (self-signed) ping key revocation
Contrib (TXT helper) contrib/make_welist_txt.sh Prints the _welist-key TXT record; generates an Ed25519 key pair when omitted
Nginx template contrib/nginx/bal-server.conf TLS termination, security headers, rate limiting
Dockerfile Dockerfile Multi-stage build from source, non-root user, tini, healthcheck
Dockerfile.release Dockerfile.release Download latest release from Gitea, SHA-256 verification
Systemd Service File Purpose
bal-server.service bal-server.service Runs as bal user, hardened
bitcoind.service bitcoind.service zmqpubhashblock setup for mainnet
tbitcoind.service tbitcoind.service Testnet bitcoind

Dependency Map (from Cargo.toml)

Core Dependencies

Dependency Version Purpose
bitcoin 0.32.5 Transaction parsing, ScriptBuf, Address, Xpub, Transaction
bitcoincore-rpc 0.19.0 RPC client (sendrawtransaction, getblockchaininfo)
bitcoincore-rpc-json 0.19.0 JSON types for Bitcoin RPC responses
sqlite 0.34.0 Direct SQLite C bindings, raw SQL queries
serde 1.0.152 Serialization (derive feature)
serde_json 1.0.116 JSON parsing for HTTP request/response
tokio 1 Async runtime (rt, net, macros, rt-multi-thread)
sha2 0.10.8 SHA-256 hashing
bs58 0.4.0 Base58 encoding for xpubs
hex 0.4.3 Hex encoding for transaction serialization
regex 1.10.4 Regular expressions
log 0.4.21 Logging facade
env_logger 0.11.5 Log level via RUST_LOG
url 2 URL parsing for SSRF validation

Server-Only Dependencies (feature: server)

Dependency Version Purpose
actix-web 4.9.0 Async HTTP server framework
actix-governor 0.6.0 Rate limiting middleware (token-bucket)
actix-rt 2.10.0 Actix async runtime
chrono 0.4.40 Date/Time handling for timestamps
hex-conservative 0.1.1 Hex parsing for Bitcoin hex strings

Pusher-Only Dependencies (feature: pusher)

Dependency Version Purpose
zmq 0.10.0 ZeroMQ for hashblock notifications
reqwest 0.12.24 HTTP client (json + socks features) for welist stats POST
byteorder 1.5.0 Reading block timestamp from raw block header
base64 0.22.1 Encoding/decoding for Ed25519 signatures
ed25519-dalek 2 Ed25519 signing (pem + pkcs8 features)
bytes 1.2 Byte handling

Test Files

Test File Tests Coverage
tests/sql_injection_tests.rs 3 SQL injection prevention
tests/panic_regression_tests.rs 2 Panic recovery, NULL handling
tests/ssrf_tests.rs 4+ SSRF URL validation
tests/secret_leakage_tests.rs 3 Secret protection, .gitignore
tests/input_validation_tests.rs 4 Input validation, address caching
tests/db_path_validation.rs 5 DB path validation, WAL mode
tests/test_endpoints.sh Bash Integration tests for HTTP endpoints

Mapping to Existing Documentation

Existing File Description Replaced/Managed By KB
README.md Installation, env vars, Docker, per-network config 07_deployment_and_ops.md
RPC.md API endpoint specification (HTTP methods, paths) 05_api_reference.md
AGENTS.md Security guidelines, audit rules, baseline commands 08_security_audit.md
Cargo.toml Dependency versions and features 09_references_and_links.md (Dependency Map)
bal-server.service systemd unit file 07_deployment_and_ops.md (Systemd)
bitcoind.service systemd unit for bitcoin node 07_deployment_and_ops.md (Systemd)
tbitcoind.service systemd unit for testnet node 07_deployment_and_ops.md (Systemd)
bal-server.env bal-server environment variables 07_deployment_and_ops.md (Environment Variables)
bal-pusher.env bal-pusher environment variables 07_deployment_and_ops.md (Environment Variables)
bal-server.sh Dev server startup script 07_deployment_and_ops.md (Bash Scripts)
bal-pusher.sh Dev pusher startup script 07_deployment_and_ops.md (Bash Scripts)
sendtx.sh Test transaction sender 07_deployment_and_ops.md (Bash Scripts)
make_release.sh Release script 07_deployment_and_ops.md (Bash Scripts)
download_bal_db.sh scp from remote 07_deployment_and_ops.md (Bash Scripts)
generate_keys.sh Generate public key from privkey.pem 07_deployment_and_ops.md (Bash Scripts)
public_key.pem Ed25519 public key for stats verification 05_api_reference.md (GET /.pub_key.pem endpoint)
privkey.pem Private key for stats signing 08_security_audit.md (Secret Leakage)
contrib/download_and_install_bal.sh Full deployment setup 07_deployment_and_ops.md (Nginx, SSL)
contrib/download_and_install_bitcoincore.sh Bitcoin Core install/verify 07_deployment_and_ops.md (Systemd)
contrib/install_tor.sh Tor installation script 07_deployment_and_ops.md (Tor)
contrib/make_onion_delegation.py Onion delegation certificate issuer 10_dnssec_key_publishing.md (Onion URLs)
contrib/make_ping_key_revocation.py Ping key revocation issuer (onion and DNS) 10_dnssec_key_publishing.md (Revocation and lifetime)
contrib/make_welist_txt.sh _welist-key TXT record helper 10_dnssec_key_publishing.md (sections 2–3)
contrib/nginx/bal-server.conf Nginx TLS config template 07_deployment_and_ops.md (Nginx)
Dockerfile Multi-stage Docker build 07_deployment_and_ops.md (Docker)

Build and Release Profile

[profile.release]
opt-level = "z"      # Optimize for binary size
lto = true           # Link-time optimization
codegen-units = 1    # Single codegen unit for maximum optimization
strip = true         # Strip debug symbols
panic = "abort"      # Abort on panic (smaller binary)

Feature Flags

[features]
default = ["server", "pusher"]
server = ["dep:actix-web", "dep:actix-governor", "dep:actix-rt", "dep:chrono", "dep:hex-conservative"]
pusher = ["dep:zmq", "dep:reqwest", "dep:byteorder", "dep:base64", "dep:ed25519-dalek"]

Build individual binaries:

cargo build --bin bal-server --features server
cargo build --bin bal-pusher --features pusher
Reference in New Issue View Git Blame Copy Permalink