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
• INLINECODE1 — 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)
• INLINECODE7 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. 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

CODEBLOCK0

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

Examples:
CODEBLOCK1

Check Balance

CODEBLOCK2

Returns current balance in satoshis.

Example output:
CODEBLOCK3

Receiving Payments

Create Invoice

CODEBLOCK4

Creates a BOLT11 invoice to receive payment.

Arguments:

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

Example:
CODEBLOCK5

Output:
CODEBLOCK6

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)

CODEBLOCK7

Pay a BOLT11 invoice with automatic payment verification.

Arguments:

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

Output: Success or failure message with exit code

Example:
CODEBLOCK8

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:

CODEBLOCK9

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

CODEBLOCK10

Check whether a payment settled.

Arguments:

• - paymentHash - Payment hash from INLINECODE20
• INLINECODE21 - (optional) DID alias

Returns:
CODEBLOCK11

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

Lightning Address Zapping

CODEBLOCK12

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

Arguments:

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

Examples:
CODEBLOCK13

Output: Success or failure message with exit code

Example:
CODEBLOCK14

The script automatically verifies the payment settled before outputting success.

What it does:

1. 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

CODEBLOCK15

Show all Lightning payments (sent and received).

Example output:
CODEBLOCK16

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

CODEBLOCK17

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:
CODEBLOCK18

Unpublish Lightning Endpoint

CODEBLOCK19

Remove Lightning endpoint from your DID document.

Utilities

Decode Invoice

CODEBLOCK20

Inspect BOLT11 invoice details before paying.

Example output:
CODEBLOCK21

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

CODEBLOCK22

Example 2: Lightning Address Zap

CODEBLOCK23

Example 3: Invoice Verification

CODEBLOCK24

Example 4: Multi-DID Wallet Management

CODEBLOCK25

Example 5: Publishing Lightning to DID

CODEBLOCK26

Example 6: Sending Invoice via Dmail

CODEBLOCK27

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:

CODEBLOCK28

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
• INLINECODE33 - Wallet encryption passphrase
• INLINECODE34 - (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:

CODEBLOCK29

Lightning Address Resolution

Lightning Addresses resolve via LNURL:

CODEBLOCK30

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: INLINECODE37
• Add funds to your wallet

"Invoice expired":

• - Request new invoice from recipient
• Check expiry: INLINECODE38

"Payment failed":

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

Verification Workflow

CODEBLOCK31

Security Best Practices

Payment Verification

Always verify payments settled:
CODEBLOCK32

Invoice Validation

Before paying, verify:

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

CODEBLOCK33

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:

CODEBLOCK34

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

"Cannot read wallet"

CODEBLOCK35

"Payment hash not found"

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

"Lightning wallet not found"

CODEBLOCK36

Network Issues

If Archon gatekeeper is unreachable:
CODEBLOCK37

Data Storage

Lightning payment data is stored:

• - Locally: Wallet state in INLINECODE43
• 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