---
name: Bitcoin RPC rpcauth architecture
description: Bitcoin uses rpcauth (salted hash in config, password in secrets file), system Tor for containers, reboot survival
type: 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