Lightning Greenlight

Greenlight (Blockstream)

Greenlight is a "hosted self-custodial Lightning" service. Blockstream runs CLN nodes on its infrastructure. Users hold private keys on their device and sign via the signer protocol.

Service: https://blockstream.com/lightning/greenlight/

Architecture

[User device]                [Blockstream cloud]
  signer protocol  ──────►   CLN node
                  ◄──────    chain access, peer connections

• User device: holds master seed, runs gl-client library.
• Cloud: runs CLN with no key access; pings device for sigs.
• Network: TLS-mutual-auth between device and cloud.

When CLN needs to sign anything (commitment, HTLC), it sends a signing request via the signer protocol. The device-side signer validates the request, signs, and returns the signature.

Why hosted

Mobile users can't run a 24/7 LN node — channels drop, force-closes happen. Greenlight runs the node 24/7 while keys stay on device.

Compare:

• Self-custodial mobile (LDK Node, Phoenix): keys + node on device, but channels drop when offline.
• Custodial (Wallet of Satoshi): keys held by service; tradeoff is custody risk.
• Greenlight: keys on device, node hosted; node available 24/7.

Signer protocol

Subset of CLN's hardware-signer protocol. Operations:

• Sign commitment tx.
• Sign HTLC tx.
• Provide ECDH for onion / gossip.
• Sign mutual close / cooperative close.

Each request includes:

• Channel state context.
• Counterparty pubkey.
• Operation type.

Device verifies state hasn't been "rolled back" (replay attacks) and that the operation aligns with channel policy.

gl-client library

Available in:

• Rust — primary gl-client crate.
• Python — pygreenlight.
• Swift / Kotlin — for mobile apps.
• JS / WASM — for browser apps.

let scheduler = Scheduler::new(node_id, network).await?;
let signer = Signer::new(seed, network, tls)?;
let node = scheduler.schedule(signer.tls()).await?;

// Use node like CLN
node.list_funds().await?;
node.create_invoice("desc", amount_msat).await?;

Trust model

Greenlight trusts:

• The hosted node to be online (availability).
• The hosted node to relay your messages honestly.
• The hosted node CANNOT steal funds (it doesn't have keys).
• The hosted node CAN refuse to forward (DoS), trigger force-close, etc.

Mitigations:

• Force-close from device side anytime.
• Multi-sig or future variants where multiple cloud nodes vote.

Comparison with other models

Setup

Mobile/desktop integration via Blockstream's onboarding:

1. Install gl-client SDK.
2. Generate seed locally.
3. Register node with Greenlight cloud.
4. Pin TLS certificate.
5. Run signer in background; node accessible via cloud.

Pricing: per-channel small fee (typically ~few sats per channel operation); subject to Blockstream's evolving terms.

See also

• cln/SKILL.md
• ldk/SKILL.md
• consumer-wallets/SKILL.md