SaturnZap copilot-instructions.md

SaturnZap — Copilot Instructions

CLI-first, non-custodial Lightning Network wallet for AI agents. Python 3.12, LDK Node, mainnet default.

Build & Test

uv sync                              # Install deps (never pip)
uv run ruff check src/ tests/        # Lint
uv run pytest tests/ -v              # Unit tests (-m "not live" to skip droplet tests)
uv build                             # Build wheel

After code changes, run uv sync to reinstall the package before testing.

Architecture

All source lives in src/saturnzap/. Key modules:

Module	Role
cli.py	Typer CLI entry point (sz). Each command → JSON output
node.py	LDK Node lifecycle. _require_node() lazy-starts; _use_ipc() auto-detects daemon
output.py	ok(**fields) → stdout JSON, error(code, msg) → stderr JSON + exit
config.py	TOML config + Esplora fallback resolver (3s probe timeout)
keystore.py	BIP39 seed + Fernet encryption (PBKDF2, 600K iterations, 16-byte salt)
ipc.py	Unix Domain Socket daemon. Newline-delimited JSON, 23 methods, threading.Lock
payments.py	BOLT11 invoices, keysend, spending caps, history
l402.py	HTTP 402 interceptor, token cache (SHA256-hashed URL)
liquidity.py	Channel health scoring (0–100), recommendations
lqwd.py	LQWD peer directory — 18 regions + agent-focused AI-Grid (LSPS1/LSPS2 JIT), default on mainnet
mcp_server.py	FastMCP stdio server, 25 tools
service.py	Systemd service generator

See docs/architecture.md for diagrams and IPC protocol details.

Conventions

• Output is always JSON: {"status": "ok", ...} or {"status": "error", "code": "...", "message": "..."}. Never print plain text. Use output.ok() / output.error().
• IPC routing: CLI commands check _use_ipc() first. If daemon is running, route through UDS; otherwise start ephemeral node.
• Network-namespaced paths: ~/.local/share/saturnzap/<network>/ — each network (signet, bitcoin) has separate seed, socket, config.
• Passphrase: SZ_PASSPHRASE env var or interactive prompt. No caching.
• Module-level singletons: _node, _ipc_mode, _active_network, _pretty — use global with # noqa: PLW0603.
• Mainnet safety: _confirm_mainnet(yes) gate on any command touching bitcoin network.
• LDK Node v0.7.0: Vendored wheel at vendor/. API: builder.set_entropy_bip39_mnemonic(mnemonic, None), generate_entropy_mnemonic(None).
• Commit messages: Plain English, no conventional-commit prefixes (feat:, fix:, chore:). Lead with the outcome. Avoid alarm words (fix, bug, warning, error, vulnerability). Examples: Add smart health alerts for payments and balances, Security hardening — payment proofs, graceful shutdown, and integrity checks. Bodies may include technical detail.