claude-dev-suite Consumer Lightning Wallets
Most users access Lightning via mobile/desktop wallets. This skill catalogues major options and integration patterns.
Wallet matrix (late 2025)
| Wallet | Architecture | Custody | LSP |
|---|---|---|---|
| Phoenix | Eclair core, mobile | Self-custodial via ACINQ trampoline | ACINQ exclusive |
| Breez SDK | LDK or Greenlight under hood | Self-custodial | Multi (Breez choice) |
| Mutiny | LDK web/mobile | Self-custodial | Multi (user choice) |
| Zeus | LND/CLN/Embedded LND | Self-custodial; supports remote nodes | Configurable |
| BlueWallet (LN) | LndHub backend | Custodial typically | LndHub provider |
| Aqua | LDK + Liquid | Self-custodial multi-asset | Multi |
| Wallet of Satoshi | Backend custodial | Custodial | n/a |
| Cash App | LDK backend | Custodial | n/a |
| Strike | Backend custodial | Custodial | n/a |
| Bitkit | LDK | Self-custodial | Synonym (their LSP) |
| Alby | Hybrid (NWC + custodial backend) | Custodial default; can connect own | n/a |
Self-custodial mobile patterns
Phoenix
- ACINQ runs an Eclair node as the user's "trampoline".
- User wallet talks to ACINQ via custom protocol.
- ACINQ never holds user keys; can refuse to forward but can't steal.
- Channels open dynamically as needed (splice-on-demand).
- Backups: 12-word seed + automatic encrypted state to ACINQ cloud.
Breez SDK
- Open-source SDK (Apache 2.0).
- Can use Greenlight (CLN) or LDK as backend.
- Multi-language bindings: Swift, Kotlin, Rust, Dart, JS, Python.
- Useful for app integrators wanting plug-and-play LN.
Mutiny Wallet
- Web wallet (browser tab) + mobile app.
- Pure LDK in WebAssembly for browser version.
- Multi-LSP: rotate, choose, fallback.
- Encrypted state to user-supplied cloud (VSS).
Zeus
- "Power user" wallet — connects to user's own LND/CLN/Embedded LND node.
- For Embedded mode: ships LND-mobile, runs locally.
- For Remote: connect via macaroon + Tor / clearnet.
- Most flexible; not as plug-and-play.
Mobile UX challenges
Always-online problem
LN nodes need to be online to:
- Watch for HTLCs.
- Respond to channel updates.
- Detect cheating.
Mobile devices: NOT always online.
Solutions:
- Watchtowers: outsource monitoring.
- Hosted node (Greenlight, custodial): always-online server with signing on device.
- Trampoline + LSP (Phoenix model): node-like service with user keys.
- Background sync: app wakes periodically (iOS/Android limits).
- Push notifications: peer notifies on important events (some LSPs offer this).
Push notification flow
LSP has user's mobile push token. When channel event needs response:
- LSP sends silent push.
- Mobile wakes, opens connection to LSP.
- Handles event.
Requires careful coordination (Apple/Google background limits).
Integration patterns
Build a custodial backend
- Run LND/CLN backend.
- Create user accounts; track balances.
- Generate invoices on demand.
- Forward HTLC payments via your node.
Build a self-custodial mobile app
- Best: Breez SDK or LDK Node (hides complexity).
- More control: directly use LDK Rust crates.
- Provide LSP integration for inbound liquidity.
Build a Lightning Address resolver
- HTTP server with
/.well-known/lnurlp/<user>endpoint. - Backend talks to your LN node (LND/CLN/phoenixd/LDK).
- See lightning-address/SKILL.md.
Wallet SDK comparison
| SDK | Backends | Bindings | Self-custody |
|---|---|---|---|
| Breez SDK | LDK + Greenlight | many | yes |
| LDK Node | LDK | Rust + bindings | yes |
| Lightning Toolkit / Bitkit SDK | LDK | native | yes |
| LndHub | LND | REST | no (custodial) |
| Greenlight Client | CLN cloud | many | yes |
For new mobile app integrations as of 2025, Breez SDK or LDK Node are the top choices.
Common bugs
- Treating LSP as fully trusted → didn't run watchtower → potentially vulnerable.
- Bg-sync misconfigured → channels close due to inactivity.
- iOS background restrictions ignored → app killed before processing channel events.
- Custodial backend with no insolvency monitoring → outage = users funds locked.