Architecture

Architecture

Component Map

┌─────────────────────────────────────────────────────────┐
│                      sz CLI                             │
│   (agent calls commands, parses JSON from stdout)       │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│                   Wallet Core                           │
│                                                         │
│  node.py        — LDK Node lifecycle (start/stop)       │
│  channels.py    — open, close, list, monitor            │
│  payments.py    — send, receive, invoice generation     │
│  peers.py       — peer connect/disconnect/list          │
│  l402.py        — HTTP 402 intercept, pay, retry        │
│  liquidity.py   — inbound/outbound monitoring           │
│  keystore.py    — BIP39 seed, encrypted at rest         │
│  lqwd.py        — LQWD node directory + LSP client      │
│  output.py      — JSON formatting, TTY detection        │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│                    LDK Node                             │
│  - Full Lightning protocol implementation               │
│  - Neutrino chain sync (no full Bitcoin node)           │
│  - BIP39 key management                                 │
│  - Peer connections and channel state machine           │
└──────────────┬────────────────────────┬─────────────────┘
               │                        │
┌──────────────▼──────────┐  ┌──────────▼──────────────────┐
│   LQWD Global Nodes     │  │   Any Lightning Node        │
│   (default — 18 nodes,  │  │   (agent can peer with      │
│   18 countries, deep    │  │   any public node on the    │
│   liquidity, LSPS)      │  │   Lightning Network)        │
└─────────────────────────┘  └─────────────────────────────┘

Key Design Decisions

• Neutrino chain sync — No external Bitcoin node needed. Under 50MB storage.
• LQWD as default LSP — 18 global nodes embedded. Auto-peer on sz init.
• Peer-agnostic — Open channels to any Lightning node after init.
• JSON-first — All commands output structured JSON to stdout. Errors to stderr.
• Non-interactive — No prompts, no confirmations. Built for agent runtimes.

Technology Stack

Component	Library	Notes
Language	Python 3.12	Type hints throughout
Lightning node	ldk-node	Neutrino built-in
CLI framework	typer	Auto-generated help
HTTP client	httpx	Async, L402 interceptor
Invoice parsing	bolt11	BOLT11 parse and create
Key encryption	cryptography	Fernet encryption for seed
Package manager	uv	Fast, modern Python tooling
Testing	pytest	Unit and integration tests