aiolabs/satmachineclient
8
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
satmachineclient/README.md
Padreug ade4e67541 feat(v2): satmachineclient maintenance pass — v2 admin schema (P7) 
Updates the LP-facing client extension to work against the v2 admin schema
(per-machine dca_clients, leg_type-discriminated dca_payments, settlement
audit trail) and strips the dead v1 code paths.

Maintenance-mode framing: the richer LP UI is migrating to ~/dev/webapp.
This extension now provides a minimal stable read-mostly surface so
existing LP installs don't break against the v2 admin schema.

models.py — rewrite:
  + PerMachinePosition: LP's position at a single machine
  ~ ClientDashboardSummary: now aggregates across all the LP's machines
    and exposes per-machine breakdown in `positions` field
  ~ ClientTransaction: gains machine_id + machine_npub + settlement_id;
    drops transaction_type / lamassu_transaction_id (v1 fields)
  ~ leg_type discriminator on ClientTransaction so the LP can tell DCA,
    operator-initiated balance-settle, and auto-forward legs apart
  + UpdateClientAutoforward: LPs control their own autoforward setting
  - ClientDashboardSummaryAPI, ClientTransactionAPI: deleted (GTQ-only
    parallel "API" models that duplicated the internal ones)
  - ClientPreferences, ClientRegistrationData, UpdateClientSettings:
    deleted (registration + settings are operator-controlled in v2)

crud.py — rewrite:
  + _fetch_user_clients: all dca_clients rows for the LP, joined with
    dca_machines for display metadata
  + _position_for_client: per-machine aggregation helper
  + get_client_dashboard_summary: aggregates positions + sums sats/fiat
    + computes cost basis on fiat-spent (not gross deposits)
  + get_client_transactions: filters to LP-visible leg_types
    (dca / settlement / autoforward); optional machine_id filter
  + update_lp_autoforward: LP self-manages autoforward across all their
    machine positions
  - get_client_analytics (300+ lines of date-parsing pretzels): deleted;
    webapp will own analytics
  - register_dca_client: deleted (admin owns registration in v2)
  - update_client_dca_settings: deleted (admin owns DCA mode/limits)
  - Lamassu-era status='confirmed' (now 'completed'), transaction_type
    column refs, lamassu_transaction_id column refs: all gone

views_api.py — rewrite to 3 endpoints:
  GET /api/v1/dca-client/positions       (aggregated dashboard)
  GET /api/v1/dca-client/transactions    (filterable history)
  PUT /api/v1/dca-client/autoforward     (LP self-manages forwarding)

All require_admin_key on the LP's wallet. Old registration / settings
/ analytics endpoints removed.

Files deleted:
  tasks.py — empty stub ("No background tasks needed")
  transaction_processor.py — empty stub ("No transaction processing")

README.md gains a status banner pointing LP audience at webapp.

.gitignore gains `data/` + sqlite db files + __pycache__ to prevent
LNbits runtime artifacts (auth keys, dev DBs) from being committed.

4 routes registered. Zero ruff errors across the extension.

Refs: aiolabs/satmachineadmin#9 — completes P7

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-14 17:53:13 +02:00

262 lines
No EOL
8.8 KiB
Markdown
Raw Permalink Blame History

# DCA Client Extension for LNBits
> **Status: maintenance-mode (v2).** This extension provides a minimal LP-facing
> read view over the v2 satmachineadmin schema. The richer LP UI is migrating to
> `~/dev/webapp`. Keep this surface stable; new LP features should land in webapp.
A Dollar Cost Averaging (DCA) administration extension for LNBits that integrates with bitSpire ATMs (formerly Lamassu) to automatically distribute Bitcoin to registered liquidity providers (LPs) 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 Client 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.
Reference in a new issue View git blame Copy permalink