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