Update README.md to provide comprehensive documentation for DCA Admin Extension: include detailed overview, features, installation instructions, configuration management, usage guidelines for administrators and end users, technical details, and troubleshooting tips. Enhance clarity and usability for developers integrating with Lamassu ATM transactions.
fix
This commit is contained in:
parent
1af15b6e26
commit
edca91579c
1 changed files with 251 additions and 14 deletions
265
README.md
265
README.md
|
|
@ -1,21 +1,258 @@
|
|||
`The README.md typically serves as a guide for using the extension.`
|
||||
# DCA Admin Extension for LNBits
|
||||
|
||||
# MyExtension - An [LNbits](https://github.com/lnbits/lnbits) Extension
|
||||
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.
|
||||
|
||||
## A Starter Template for Your Own Extension
|
||||
## Overview
|
||||
|
||||
Ready to start hacking? Once you've forked this extension, you can incorporate functions from other extensions as needed.
|
||||
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.
|
||||
|
||||
### How to Use This Template
|
||||
## Features
|
||||
|
||||
> This guide assumes you're using this extension as a base for a new one, and have installed LNbits using https://github.com/lnbits/lnbits/blob/main/docs/guide/installation.md#option-1-recommended-poetry.
|
||||
### 🏦 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
|
||||
|
||||
1. Install and enable the extension either through the official LNbits manifest or by adding https://raw.githubusercontent.com/lnbits/myextension/main/manifest.json to `"Server"/"Server"/"Extension Sources"`.  
|
||||
### 💰 Deposit Management
|
||||
- Quick deposit creation for existing clients
|
||||
- Individual deposit confirmation workflow
|
||||
- Status tracking (pending/confirmed)
|
||||
- Notes and documentation for each deposit
|
||||
|
||||
2. `Ctrl c` shut down your LNbits installation.
|
||||
3. Download the extension files from https://github.com/lnbits/myextension to a folder outside of `/lnbits`, and initialize the folder with `git`. Alternatively, create a repo, copy the myextension extension files into it, then `git clone` the extension to a location outside of `/lnbits`.
|
||||
4. Remove the installed extension from `lnbits/lnbits/extensions`.
|
||||
5. Create a symbolic link using `ln -s /home/ben/Projects/<name of your extension> /home/ben/Projects/lnbits/lnbits/extensions`.
|
||||
6. Restart your LNbits installation. You can now modify your extension and `git push` changes to a repo.
|
||||
7. When you're ready to share your manifest so others can install it, edit `/lnbits/myextension/manifest.json` to include the git credentials of your extension.
|
||||
8. IMPORTANT: If you want your extension to be added to the official LNbits manifest, please follow the guidelines here: https://github.com/lnbits/lnbits-extensions#important
|
||||
### 🔄 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/
|
||||
│ └── myextension/
|
||||
│ └── 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue