lamassu-server/packages/server/lib/plugins/wallet/lnbits/README.md

LNBits Wallet Plugin

This plugin integrates LNBits as a Lightning Network wallet provider for Lamassu Bitcoin ATMs.

Features

• Lightning Invoice Creation: Generate BOLT11 invoices for incoming payments
• Payment Processing: Send Lightning payments to any BOLT11 invoice
• Balance Monitoring: Check wallet balance in real-time
• Payment Status Tracking: Monitor invoice payment status
• Route Probing: Test payment feasibility before attempting
• Network Detection: Automatic mainnet/testnet/regtest detection

Configuration

Required Environment Variables

LNBITS_ENDPOINT=https://your-lnbits-server.com
LNBITS_ADMIN_KEY=your_admin_key_here

Important: The admin key is wallet-specific in LNBits. No separate walletId is needed.

Database Configuration

The plugin configuration is stored in the database and can be managed through the Lamassu admin interface.

API Functions

Core Functions

newAddress(account, info, tx)

Creates a new Lightning invoice for receiving payments.

Parameters:

• account: Object containing endpoint and adminKey
• info: Transaction info object
• tx: Transaction object with cryptoAtoms and cryptoCode

Returns: BOLT11 Lightning invoice string

getStatus(account, tx)

Checks the payment status of a Lightning invoice.

Parameters:

• account: Configuration object
• tx: Transaction object with toAddress (Lightning invoice)

Returns: Object with status field: 'confirmed', 'pending', or 'notSeen'

sendCoins(account, tx)

Sends a Lightning payment to a BOLT11 invoice.

Parameters:

• account: Configuration object
• tx: Transaction object with toAddress and optional cryptoAtoms

Returns: Object with txid and fee

balance(account, cryptoCode)

Gets the current wallet balance.

Parameters:

• account: Configuration object
• cryptoCode: Must be 'LN'

Returns: BigNumber balance in satoshis

Utility Functions

isLnInvoice(address)

Checks if a string is a valid Lightning invoice.

isLnurl(address)

Checks if a string is a valid LNURL.

probeLN(account, cryptoCode, invoice)

Tests payment route feasibility for different amounts.

cryptoNetwork(account, cryptoCode)

Detects network type from endpoint URL.

Error Handling

The plugin provides detailed error messages for common issues:

• Configuration errors: Missing endpoint or admin key
• Network errors: Connection timeouts or unreachable server
• API errors: Invalid requests or authentication failures
• Invoice errors: Invalid BOLT11 format or expired invoices

Testing

Run unit tests:

npm test -- tests/unit/test_lnbits_plugin.js

Migration from Galoy

This plugin replaces the Galoy (Blink) integration with the following improvements:

1. Simpler Configuration: Only requires endpoint and admin key
2. RESTful API: Easier to debug than GraphQL
3. Self-Hosted Option: Can run your own LNBits instance
4. Better Error Messages: More descriptive error handling
5. Native Webhook Support: Real-time payment notifications (future enhancement)

Security Considerations

• Store the admin key securely (marked as secret: true in database)
• Use HTTPS endpoints in production
• Validate all Lightning invoices before processing
• Implement rate limiting for API calls (handled by LNBits)
• Monitor wallet balance and set alerts for low balance

Troubleshooting

Common Issues

1. "LNBits configuration missing"

   • Ensure both endpoint and adminKey are set
   • Check environment variables or database configuration

2. "Invalid Lightning invoice"

   • Verify the invoice starts with 'lnbc', 'lntb', or 'lnbcrt'
   • Check if the invoice has expired

3. "LNBits API Error: 404"

   • Payment hash not found (invoice may not exist)
   • Check if using correct endpoint URL

4. "LNBits API Error: 401"

   • Invalid admin key
   • Verify the admin key is correct and has proper permissions

Support

For LNBits-specific issues, refer to:

• LNBits Documentation
• LNBits GitHub

For Lamassu integration issues, contact Lamassu support.