padreug
fc761844b7
- Introduced LNBits as a Lightning Network wallet provider for Lamassu ATMs. - Added configuration options for LNBits in the environment variables. - Implemented core functionalities including invoice creation, payment processing, balance monitoring, and payment status tracking. - Created unit tests for the LNBits plugin to ensure functionality and error handling. - Updated development environment setup to include LNBits configuration.
144 lines
No EOL
4.2 KiB
Markdown
144 lines
No EOL
4.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](https://docs.lnbits.com)
|
|
- [LNBits GitHub](https://github.com/lnbits/lnbits)
|
|
|
|
For Lamassu integration issues, contact Lamassu support. |