archy/.claude/memory/project_bitcoin_rpc_auth.md

name, description, type

name	description	type
Bitcoin RPC rpcauth architecture	Bitcoin uses rpcauth (salted hash in config, password in secrets file), system Tor for containers, reboot survival	project

Bitcoin RPC uses rpcauth — salted HMAC-SHA256 hash in bitcoin.conf, plaintext password in /var/lib/archipelago/secrets/bitcoin-rpc-password. Credentials are STABLE across reboots, restarts, deploys.

Why: Cookie auth rotates on every Bitcoin restart, breaking all dependent containers with env-var-only credentials. The rpcauth approach keeps the password stable while never exposing plaintext in config files or CLI args.

How to apply:

• Bitcoin: reads rpcauth from bitcoin.conf (no CLI credential flags, config generated by first-boot or deploy)
• LND: bitcoind.rpcuser/rpcpass in lnd.conf (NOT rpccookie — LND v0.18.4 doesn't support it)
• All containers: read password from secrets file at creation time, passed via env vars
• Rust backend bitcoin_rpc.rs: reads from secrets file, cached with OnceCell
• bitcoin-ui: mounts /var/lib/archipelago/secrets:/secrets:ro, start.sh reads password and injects nginx auth header
• System Tor: SocksPort 0.0.0.0:9050 + SocksPolicy, containers use host.containers.internal:9050
• podman-restart.service enabled for container auto-start after reboot
• Tor hidden service hostnames copied to /var/lib/archipelago/tor-hostnames/ for readable access
• .198 ElectrumX points at .228's full Bitcoin node (pruned node can't run ElectrumX locally)
• Health monitor interval: 60 seconds — UI may briefly show "crashed" during restarts