Archon Lightning

Archon Lightning - Lightning Network Payments for DIDs

Lightning Network integration for Archon decentralized identities. Send and receive Bitcoin over Lightning using your DID.

Related skills:

• archon-keymaster — Core DID identity management
• archon-vault — Encrypted backups

Capabilities

• Lightning Wallet Management - Create Lightning wallets for DIDs
• Invoice Generation - Create BOLT11 invoices to receive payments
• Invoice Payment - Pay BOLT11 invoices
• Payment Verification - Verify payments settled (critical security pattern)
• Lightning Address Zapping - Send to Lightning Addresses (user@domain.com)
• Payment History - Track all Lightning transactions
• Balance Checking - Query wallet balance
• DID Integration - Publish Lightning endpoint to DID document
• Invoice Decoding - Inspect BOLT11 invoice details

Prerequisites

• Node.js installed (for npx @didcid/keymaster)
• Archon identity configured (~/.archon.env with ARCHON_WALLET_PATH, ARCHON_PASSPHRASE)
• jq recommended for JSON parsing

All created by archon-keymaster setup. If you don't have Archon configured yet, see the archon-keymaster skill first.

Security Notes

This skill handles Lightning Network payments:

1. Non-custodial: You control your Lightning node and private keys
2. Payment verification is built-in: lightning-pay.sh automatically verifies payments; if using keymaster directly, you must verify manually with lightning-check (see Payment Verification Pattern below)
3. Environment access: Scripts source ~/.archon.env for wallet access
4. Network connectivity: Connects to Lightning Network via Archon gatekeeper

Quick Start

Create Lightning Wallet

./scripts/lightning/add-lightning.sh [id]

Creates a Lightning wallet for your current DID (or specified DID alias).

Examples:

./scripts/lightning/add-lightning.sh          # Current DID
./scripts/lightning/add-lightning.sh work     # Specific DID alias

Check Balance

./scripts/lightning/lightning-balance.sh [id]

Returns current balance in satoshis.

Example output:

2257 sats

Receiving Payments

Create Invoice

./scripts/lightning/lightning-invoice.sh <amount> <memo> [id]

Creates a BOLT11 invoice to receive payment.

Arguments:

• amount - Amount in satoshis (1000 = 0.00001 BTC)
• memo - Description/memo for the invoice
• id - (optional) DID alias, defaults to current identity

Example:

./scripts/lightning/lightning-invoice.sh 1000 "Coffee payment"

Output:

{
  "paymentRequest": "lnbc10u1p...",
  "paymentHash": "a3f7b8c9..."
}

Share this invoice with the payer. They can:

• Scan as QR code
• Paste into any Lightning wallet
• Pay via Lightning-enabled app

Sending Payments

Pay Invoice (Basic)

./scripts/lightning/lightning-pay.sh <bolt11> [id]

Pay a BOLT11 invoice with automatic payment verification.

Arguments:

• bolt11 - BOLT11 invoice string
• id - (optional) DID alias to pay from

Output: Success or failure message with exit code

Example:

./scripts/lightning/lightning-pay.sh lnbc10u1p...
# ✅ Payment confirmed
# (exits 0 on success, 1 on failure)

The script automatically verifies the payment settled before outputting success.

⚠️ Payment Verification Pattern (CRITICAL)

The payment hash is NOT proof of payment! Lightning payments can fail, time out, or remain pending.

Our lightning-pay.sh script handles verification automatically:

./scripts/lightning/lightning-pay.sh lnbc10u1p...
# ✅ Payment confirmed
# (or "❌ Payment failed or pending" + exit 1)

The script verifies the payment settled and outputs a clear success/failure message. No manual checking needed.

Why verification matters:

• Payment hash ≠ success (can fail after returning hash)
• Prevents false confirmation (thinking you paid when you didn't)

Verify Payment Status

./scripts/lightning/lightning-check.sh <paymentHash> [id]

Check whether a payment settled.

Arguments:

• paymentHash - Payment hash from lightning-pay
• id - (optional) DID alias

Returns:

{
  "paid": true,
  "preimage": "...",
  "amount": 1000
}

• "paid": true — Payment settled successfully
• "paid": false — Payment failed or still pending

Lightning Address Zapping

./scripts/lightning/lightning-zap.sh <recipient> <amount> [memo] [id]

Send sats to a Lightning Address, DID, or alias.

Arguments:

• recipient - Lightning Address (user@domain.com), DID, or alias
• amount - Amount in satoshis
• memo - (optional) Message/memo
• id - (optional) DID alias to send from

Examples:

# Zap to Lightning Address
./scripts/lightning/lightning-zap.sh user@getalby.com 1000 "Great post!"

# Zap to DID
./scripts/lightning/lightning-zap.sh did:cid:bagaaiera... 5000

# Zap to alias
./scripts/lightning/lightning-zap.sh alice 2000 "Coffee"

Output: Success or failure message with exit code

Example:

./scripts/lightning/lightning-zap.sh user@getalby.com 1000 "Great post!"
# ✅ Payment confirmed
# (exits 0 on success, 1 on failure)

The script automatically verifies the payment settled before outputting success.

What it does:

1. Resolves Lightning Address to LNURL endpoint
2. Requests invoice for specified amount
3. Pays invoice
4. Returns payment hash (you still need to verify!)

Payment History

List Payments

./scripts/lightning/lightning-payments.sh [id]

Show all Lightning payments (sent and received).

Example output:

2026/03/05 11:17:38  -100 sats "Payment memo"
2026/03/04 17:08:14  +20 sats "Received payment"
2026/03/03 17:16:31  +25 sats "Test invoice"

Format: YYYY/MM/DD HH:MM:SS [+/-]amount sats ["memo"]

• Negative amounts = payments sent
• Positive amounts = payments received
• Memo is optional

DID Integration

Publish Lightning Endpoint

./scripts/lightning/publish-lightning.sh [id]

Add your Lightning endpoint to your DID document.

What it does:

• Updates your DID document with Lightning service info
• Makes your Lightning endpoint publicly discoverable
• Others can look up your DID and pay you

Example:

./scripts/lightning/publish-lightning.sh

# Your DID document now includes:
# {
#   "didDocument": {
#     "id": "did:cid:bagaaiera...",
#     "service": [{
#       "id": "did:cid:bagaaiera...#lightning",
#       "type": "Lightning",
#       "serviceEndpoint": "http://...onion:4222/invoice/bagaaiera..."
#     }]
#   }
# }

Unpublish Lightning Endpoint

./scripts/lightning/unpublish-lightning.sh [id]

Remove Lightning endpoint from your DID document.

Utilities

Decode Invoice

./scripts/lightning/lightning-decode.sh <bolt11>

Inspect BOLT11 invoice details before paying.

Example output:

{
  "amount": 1000,
  "description": "Coffee payment",
  "paymentHash": "a3f7b8c9...",
  "timestamp": 1709635800,
  "expiry": 3600,
  "destination": "03..."
}

Use cases:

• Verify amount before paying
• Check invoice hasn't expired
• Confirm recipient/description
• Extract payment hash for tracking

Complete Workflow Examples

Example 1: Simple Payment

# Alice creates invoice
INVOICE=$(./scripts/lightning/lightning-invoice.sh 1000 "Coffee")
echo "Invoice: $INVOICE"

# Bob pays invoice
RESULT=$(./scripts/lightning/lightning-pay.sh "$INVOICE")
HASH=$(echo "$RESULT" | jq -r .paymentHash)

# Bob verifies payment
STATUS=$(./scripts/lightning/lightning-check.sh "$HASH" | jq -r .paid)
if [ "$STATUS" = "true" ]; then
  echo "✅ Payment confirmed!"
fi

# Alice checks balance
./scripts/lightning/lightning-balance.sh

Example 2: Lightning Address Zap

# Zap creator via Lightning Address
./scripts/lightning/lightning-zap.sh creator@getalby.com 5000 "Love your content!"
# ✅ Payment confirmed

# Payment verification is automatic - no manual checking needed

Example 3: Invoice Verification

# Receive a BOLT11 invoice from someone
INVOICE="lnbc10u1p..."

# Decode to verify amount and recipient
./scripts/lightning/lightning-decode.sh "$INVOICE"
# Check amount, description, expiry

# If looks good, pay it
RESULT=$(./scripts/lightning/lightning-pay.sh "$INVOICE")
HASH=$(echo "$RESULT" | jq -r .paymentHash)

# CRITICAL: Verify payment settled
./scripts/lightning/lightning-check.sh "$HASH"

Example 4: Multi-DID Wallet Management

# Create wallets for different personas
./scripts/lightning/add-lightning.sh personal
./scripts/lightning/add-lightning.sh work
./scripts/lightning/add-lightning.sh project

# Check balances
./scripts/lightning/lightning-balance.sh personal
./scripts/lightning/lightning-balance.sh work
./scripts/lightning/lightning-balance.sh project

# Pay from specific wallet
./scripts/lightning/lightning-pay.sh lnbc10u1p... work

Example 5: Publishing Lightning to DID

# Create Lightning wallet
./scripts/lightning/add-lightning.sh

# Publish to DID document
./scripts/lightning/publish-lightning.sh

# Others can now discover your Lightning endpoint
# They look up your DID and see your Lightning service

# Later, if you want to unpublish:
./scripts/lightning/unpublish-lightning.sh

Example 6: Sending Invoice via Dmail

# Alice creates an invoice for 5000 sats
INVOICE_JSON=$(npx @didcid/keymaster lightning-invoice 5000 "Consulting fee")
INVOICE=$(echo "$INVOICE_JSON" | jq -r .paymentRequest)

# Alice sends the invoice to Bob via dmail
npx @didcid/keymaster send-dmail \
  "did:cid:bob..." \
  "Invoice for consulting work" \
  "Please pay this invoice: $INVOICE"

# Bob receives the dmail, extracts the invoice, and pays
npx @didcid/keymaster lightning-pay "$INVOICE"
# ✅ Payment confirmed

# Alice checks her payment history
npx @didcid/keymaster lightning-payments
# Shows the received payment

Why this matters: Agents can request payment without needing email, phone numbers, or centralized messaging platforms. Just DIDs + Lightning + dmail.