# DCA Admin Extension for LNBits

A Dollar Cost Averaging (DCA) administration extension for LNBits that integrates with Lamassu ATM machines to automatically distribute Bitcoin to registered clients based on their deposit balances.

## Overview

This extension enables automated Bitcoin distribution from Lamassu ATM transactions to DCA clients. When customers use a Lamassu ATM to purchase Bitcoin, the system automatically distributes the purchased amount (minus commission) proportionally to clients who have active DCA balances.

## Features

### 🏦 DCA Client Management
- View all registered DCA clients from the client extension
- Monitor client balances and deposit history
- Support for both "flow" and "fixed" DCA modes
- Real-time balance tracking with remaining amounts

### 💰 Deposit Management
- Quick deposit creation for existing clients
- Individual deposit confirmation workflow
- Status tracking (pending/confirmed)
- Notes and documentation for each deposit

### 🔄 Lamassu ATM Integration
- Real-time polling of Lamassu database transactions
- Secure SSH tunnel support for database access
- Automatic commission calculation and handling
- Proportional distribution to active DCA clients

### 📊 Transaction Audit Trail
- Complete record of all processed Lamassu transactions
- Clickable transaction details showing exact distribution breakdown
- Commission tracking with discount support
- Export capabilities for all data

### ⚙️ Configuration Management
- Secure database connection configuration
- Source wallet selection for Bitcoin distributions
- Commission wallet configuration for earnings
- SSH tunnel setup for secure remote access

## Installation

1. Copy this extension to your LNBits extensions directory
2. Enable the extension in LNBits admin panel
3. Install the companion DCA client extension for end-users

## Configuration

### Database Setup

1. **Configure Lamassu Database Connection**
   - Navigate to the DCA Admin extension
   - Click "Configure Database" in the sidebar
   - Enter your Lamassu PostgreSQL connection details:
     - Host and port
     - Database name (usually "lamassu")
     - Username and password
   - Select source wallet for Bitcoin distributions
   - Optionally select commission wallet for earnings

2. **SSH Tunnel (Recommended)**
   - Enable SSH tunnel for secure database access
   - Provide SSH server details and authentication
   - Supports both password and private key authentication

3. **Test Connection**
   - Use the "Test Connection" button to verify setup
   - Check SSH tunnel and database connectivity

### Wallet Configuration

- **Source Wallet**: Must contain sufficient Bitcoin for distributions
- **Commission Wallet**: Optional separate wallet for commission earnings
- Wallets are automatically credited with Lamassu transaction amounts

## Usage

### For Administrators

1. **Client Registration**
   - Clients register using the DCA client extension
   - Admins can view all registered clients in the admin panel

2. **Deposit Management**
   - Add deposits for clients when they provide fiat currency
   - Confirm deposits once money is physically placed in ATM
   - Track deposit status and client balances

3. **Transaction Processing**
   - System automatically polls Lamassu database hourly
   - Manual polling available for immediate processing
   - Test transaction feature for system validation

4. **Monitoring**
   - View all processed transactions with full audit trail
   - Click transactions to see distribution details
   - Export data for accounting and compliance

### For End Users (DCA Client Extension)

1. **Registration**
   - Install DCA client extension
   - Choose DCA mode (flow or fixed)
   - Make initial deposit with administrator

2. **DCA Modes**
   - **Flow Mode**: Receives proportional share of all transactions
   - **Fixed Mode**: Receives up to daily limit from transactions

## Technical Details

### Architecture

- **Backend**: FastAPI with PostgreSQL database
- **Frontend**: Vue.js 3 with Quasar UI components
- **Database**: Extends LNBits database with dedicated tables
- **Integration**: Direct PostgreSQL connection to Lamassu database

### Database Schema

The extension creates several tables:
- `dca_clients`: Registered DCA users
- `dca_deposits`: Client deposit tracking
- `dca_payments`: Individual Bitcoin distributions
- `lamassu_config`: Database connection settings
- `lamassu_transactions`: Processed ATM transaction audit trail

### Security

- SSH tunnel support for secure database access
- Encrypted storage of database credentials
- Read-only access to Lamassu database
- Internal LNBits payment system for Bitcoin distributions

### Commission Handling

- Configurable commission percentage from Lamassu
- Discount support for promotional rates
- Automatic commission calculation: `base_amount = total / (1 + commission_rate)`
- Separate wallet option for commission earnings

## API Endpoints

### DCA Clients
- `GET /api/v1/dca/clients` - List all clients
- `GET /api/v1/dca/clients/{id}/balance` - Get client balance
- `POST /api/v1/dca/clients` - Create test client (dev only)

### Deposits
- `GET /api/v1/dca/deposits` - List all deposits
- `POST /api/v1/dca/deposits` - Create new deposit
- `PUT /api/v1/dca/deposits/{id}/status` - Update deposit status

### Transactions
- `GET /api/v1/dca/transactions` - List processed transactions
- `GET /api/v1/dca/transactions/{id}/distributions` - Get distribution details

### Configuration
- `GET /api/v1/dca/config` - Get database configuration
- `POST /api/v1/dca/config` - Create/update configuration
- `POST /api/v1/dca/test-connection` - Test database connection

### Operations
- `POST /api/v1/dca/manual-poll` - Trigger manual polling
- `POST /api/v1/dca/test-transaction` - Process test transaction

## Development

### Setup Development Environment

1. Clone LNBits and this extension
2. Install dependencies: `poetry install`
3. Set up test Lamassu database or use test mode
4. Configure SSH tunnel for development access

### Code Structure

```
├── README.md                 # This file
├── __init__.py              # Extension initialization
├── models.py                # Pydantic data models
├── crud.py                  # Database operations
├── views.py                 # Frontend page routes
├── views_api.py             # API endpoints
├── migrations.py            # Database migrations
├── transaction_processor.py # Lamassu integration
├── helpers.py               # Utility functions
├── config.json              # Extension configuration
├── manifest.json            # Extension manifest
├── templates/
│   └── satmachineclient/
│       └── index.html       # Main UI template
└── static/
    └── js/
        └── index.js         # Frontend JavaScript
```

### Testing

- Use "Test Connection" to verify Lamassu database access
- Use "Test Transaction" to simulate ATM transaction processing
- Monitor logs for debugging transaction processing
- Test SSH tunnel connectivity independently

## Troubleshooting

### Common Issues

1. **SSH Connection Failed**
   - Verify SSH credentials and host accessibility
   - Check SSH key permissions (600 for private keys)
   - Ensure SSH server allows database user connections

2. **Database Connection Failed**
   - Verify PostgreSQL connection details
   - Check database user permissions (SELECT access required)
   - Confirm database name and schema

3. **No Transactions Found**
   - Check Lamassu database for recent transactions
   - Verify transaction polling timestamps
   - Review database query filters

4. **Distribution Errors**
   - Ensure source wallet has sufficient balance
   - Check client deposit confirmations
   - Verify wallet configuration

### Debugging

- Enable debug logging: `DEBUG=true`
- Check LNBits logs for transaction processing
- Use manual polling to test individual transactions
- Verify database queries with SSH tunnel

## Security Considerations

- Use SSH tunnels for production database access
- Regularly rotate database credentials
- Monitor transaction processing logs
- Implement proper backup procedures
- Use read-only database access where possible

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Review LNBits extension documentation
3. Check connection test results for specific errors
4. Monitor system logs for detailed error messages

## License

This extension follows the same license as LNBits.

---

**Note**: This extension requires the companion DCA client extension for end-users to register and participate in the DCA program.