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

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

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

Examples:

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

Check Balance

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

Returns current balance in satoshis.

Example output:

2257 sats

Receiving Payments

Create Invoice

bash
./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:

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

Output:

json
{
  "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)

bash
./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:

bash
./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:

bash
./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

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

Check whether a payment settled.

Arguments:

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

Returns:

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

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

Lightning Address Zapping

bash
./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:

bash
# 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:

bash
./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

bash
./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

bash
./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:

bash
./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

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

Remove Lightning endpoint from your DID document.

Utilities

Decode Invoice

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

Inspect BOLT11 invoice details before paying.

Example output:

json
{
  "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

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
# 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.

Environment Setup

All scripts require:

bash
source ~/.archon.env   # Load wallet path and passphrase

This is automatically sourced by the wrapper scripts. npx is used to run keymaster, so no nvm sourcing is needed.

Environment variables (~/.archon.env):

• ARCHON_WALLET_PATH - Path to your wallet file
• ARCHON_PASSPHRASE - Wallet encryption passphrase
• ARCHON_GATEKEEPER_URL - (optional) Gatekeeper endpoint

Advanced Usage

Lightning Node Details

Archon Lightning wallets are:

• Non-custodial - You control the keys
• Self-hosted - Runs via Archon gatekeeper
• DID-integrated - Same identity across protocols

The wallet is managed by @didcid/keymaster which interfaces with Lightning infrastructure.

Payment Amounts

Lightning amounts are in satoshis:

• 1 satoshi = 0.00000001 BTC
• 1000 sats = 0.00001 BTC (~$0.01 at $100k BTC)
• 100,000 sats = 0.001 BTC (~$1 at $100k BTC)

Minimum payment typically 1 sat, maximum depends on channel capacity.

Invoice Expiry

BOLT11 invoices typically expire after 1 hour. Check expiry with:

bash
./scripts/lightning/lightning-decode.sh lnbc10u1p... | jq .expiry

Lightning Address Resolution

Lightning Addresses resolve via LNURL:

user@domain.com
→ Query: https://domain.com/.well-known/lnurlp/user
→ Get invoice endpoint
→ Request invoice for amount
→ Pay invoice

The lightning-zap.sh script handles this automatically.

Error Handling

Common Issues

"No route found":

• Lightning Network couldn't find path to recipient
• Try smaller amount or wait for better routing

"Insufficient balance":

• Check balance: ./scripts/lightning/lightning-balance.sh
• Add funds to your wallet

"Invoice expired":

• Request new invoice from recipient
• Check expiry: ./scripts/lightning/lightning-decode.sh

"Payment failed":

• Always verify with lightning-check
• Payment hash ≠ success
• May need to retry with new invoice

Verification Workflow

bash
# 1. Attempt payment
RESULT=$(./scripts/lightning/lightning-pay.sh "$INVOICE" 2>&1)

# 2. Check for errors
if ! echo "$RESULT" | jq -e .paymentHash > /dev/null 2>&1; then
  echo "Payment failed: $RESULT"
  exit 1
fi

# 3. Extract payment hash
HASH=$(echo "$RESULT" | jq -r .paymentHash)

# 4. Verify payment settled
for i in {1..5}; do
  STATUS=$(./scripts/lightning/lightning-check.sh "$HASH" | jq -r .paid)
  if [ "$STATUS" = "true" ]; then
    echo "✅ Payment confirmed"
    exit 0
  fi
  sleep 2
done

echo "⏳ Payment still pending or failed"
exit 1

Security Best Practices

Payment Verification

Always verify payments settled:

bash
# ❌ WRONG
./scripts/lightning/lightning-pay.sh lnbc10u1p...
echo "Paid!" # NO!

# ✅ CORRECT
HASH=$(./scripts/lightning/lightning-pay.sh lnbc10u1p... | jq -r .paymentHash)
./scripts/lightning/lightning-check.sh "$HASH" | jq -r .paid

Invoice Validation

Before paying, verify:

• Amount is correct
• Recipient is expected
• Invoice hasn't expired
• Description matches expectation

bash
./scripts/lightning/lightning-decode.sh lnbc10u1p...
# Check output before paying

Key Security

• Lightning private keys derived from DID seed
• Keep ARCHON_PASSPHRASE secure
• Backup your 12-word mnemonic (see archon-vault skill)
• Use separate DIDs for different risk profiles

Amount Limits

• Start with small amounts for testing
• Lightning is for micropayments (< $100 typical)
• Large amounts should use on-chain Bitcoin
• Check balance before sending

Troubleshooting

"Command not found: npx"

Ensure Node.js is installed and in your PATH:

bash
node --version  # Should show v16 or newer
npx --version   # Should show npm version

If not installed, install Node.js via your package manager or from https://nodejs.org

"Cannot read wallet"

bash
source ~/.archon.env
ls -la "$ARCHON_WALLET_PATH"
# Ensure wallet file exists and is readable

"Payment hash not found"

Payment may still be pending or failed. Wait 5-10 seconds and try lightning-check again.

"Lightning wallet not found"

bash
./scripts/lightning/add-lightning.sh
# Creates wallet for current DID

Network Issues

If Archon gatekeeper is unreachable:

bash
echo $ARCHON_GATEKEEPER_URL
# Verify URL is correct

# Try default gatekeeper
unset ARCHON_GATEKEEPER_URL
./scripts/lightning/lightning-balance.sh

Data Storage

Lightning payment data is stored:

• Locally: Wallet state in ~/.archon.wallet.json
• Network: Channel state on Lightning Network
• DID document: Public endpoint (if published)

No payment history or balances are exposed publicly unless you explicitly publish them.

Use Cases

Agent-to-Agent Payments:

• Pay for API access
• Skill marketplace transactions
• Service subscriptions
• Bounty payments

Content Monetization:

• Paywalled articles
• Per-use API access
• Streaming sats for media
• Microtips for social posts

Real-Time Payments:

• Pay-per-compute
• Storage payments
• Data feed subscriptions
• Time-based access

Value-4-Value:

• Podcast boosts
• Creator support
• Open source tips
• P2P payments

References

• Archon documentation: https://github.com/archetech/archon
• Keymaster reference: https://github.com/archetech/archon/tree/main/keymaster
• Lightning Network: https://lightning.network
• BOLT specifications: https://github.com/lightning/bolts
• Lightning Address: https://lightningaddress.com

Related Skills

• archon-keymaster — Core DID management and credentials
• archon-vault — Encrypted backups and disaster recovery
• archon-cashu — Ecash tokens with DID locking

⚡ Powered by Lightning. Secured by Archon. Built for agents.