lnbits-exts/satmachineclient
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

move to parent directory

Browse source
This commit is contained in:
padreug 2025-06-22 11:52:55 +02:00
parent 3f9e3d47ed
commit 462c93d18d
6 changed files with 0 additions and 957 deletions
Download patch file Download diff file Expand all files Collapse all files

266
CLAUDE.md
View file

@ -1,266 +0,0 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is the **Satoshi Machine Admin Extension** for LNBits - a Dollar Cost Averaging (DCA) administration system that integrates with Lamassu ATM machines to automatically distribute Bitcoin to registered clients based on their deposit balances.
## Development Commands
### Code Quality & Formatting
```bash
# Format all code
make format
# Check code quality
make check
# Individual commands
poetry run black . # Python formatting
poetry run ruff check . --fix # Python linting with auto-fix
poetry run ./node_modules/.bin/prettier --write . # JavaScript formatting
poetry run mypy . # Python type checking
poetry run ./node_modules/.bin/pyright # JavaScript type checking
```
### Testing
```bash
# Run tests
make test
# or
PYTHONUNBUFFERED=1 DEBUG=true poetry run pytest
```
### Pre-commit Hooks
```bash
# Install pre-commit hooks
make install-pre-commit-hook
# Run pre-commit on all files
make pre-commit
```
## Architecture
### Core Structure
The Satoshi Machine Admin extension follows LNBits architecture patterns:
- **Backend (Python/FastAPI)**:
- `__init__.py` - Extension initialization and router setup
- `models.py` - Pydantic data models for DCA system
- `crud.py` - Database operations for all DCA entities
- `views.py` - Admin dashboard page route
- `views_api.py` - DCA API endpoints
- `migrations.py` - Database schema (condensed single migration)
- `tasks.py` - Background polling and invoice listening
- `transaction_processor.py` - Core Lamassu integration logic
- **Frontend (Vue.js 3 Options API + Quasar)**:
- `static/js/index.js` - Admin dashboard Vue app
- `templates/myextension/index.html` - Admin interface template
### Key Conventions
1. **Template Syntax Rules**:
- Use `{{ }}` and `{% %}` ONLY in `index.html` files (Jinja2)
- In Vue components: Use `v-text='value'` instead of `{{ value }}`
- Use `:attribute='value'` for binding, `v-html='value'` for HTML content
2. **API Patterns**:
- Always include wallet key (inkey/adminkey) as third parameter in API calls
- Use `LNbits.api.request()` for all API calls
- Destructure responses: `const {data} = await LNbits.api.request(...)`
3. **Component Registration**:
- Templates must be included BEFORE scripts in HTML
- Components must be registered BEFORE app.mount()
### The Magical G Object
The global `this.g` object provides access to:
- `this.g.user` - Complete user data including wallets array
- `this.g.user.wallets[0].inkey` - Invoice key for API calls
- `this.g.user.wallets[0].adminkey` - Admin key for privileged operations
- `this.g.wallet` - Currently selected wallet
### Built-in Utilities
- Currency conversion: `/api/v1/currencies`, `/api/v1/conversion`
- QR code generation: `/api/v1/qrcode/{data}` or Quasar VueQrcode component
- WebSocket support: `wss://host/api/v1/ws/{id}` with POST to `/api/v1/ws/{id}/{data}`
## Configuration Files
- `config.json` - Extension configuration (name: "DCA Client")
- `manifest.json` - Extension manifest for installation
- `pyproject.toml` - Python dependencies and tool configuration
- `package.json` - JavaScript dependencies
## DCA System Architecture
### Core Components
#### **1. Lamassu ATM Integration**
- Secure SSH connection to remote Lamassu PostgreSQL database
- Polls `cash_out_txs` table for new confirmed transactions
- Supports both SSH password and private key authentication
- Read-only database access for security
#### **2. Commission Calculation Engine**
- Formula: `base_amount = total_amount / (1 + effective_commission)`
- Effective commission: `commission_percentage * (100 - discount) / 100`
- Supports discount percentages for promotional rates
- Separates commission earnings to configurable wallet
#### **3. DCA Distribution System**
- **Flow Mode**: Proportional distribution based on client balance ratios
- **Fixed Mode**: Daily limit-based allocation (future enhancement)
- Automatic Bitcoin transfers using LNBits internal payment system
- Real-time balance tracking and deduction
#### **4. Audit and Compliance**
- Complete transaction audit trail in `lamassu_transactions` table
- Detailed distribution records in `dca_payments` table
- Clickable transaction history with distribution breakdowns
- CSV export capabilities for accounting
### Database Schema
**Core Tables:**
- `dca_clients` - Client registration and DCA mode settings
- `dca_deposits` - Fiat deposit tracking and confirmation workflow
- `dca_payments` - Bitcoin payment records and status tracking
- `lamassu_config` - Database connection and polling configuration
- `lamassu_transactions` - Complete audit trail of processed ATM transactions
**Key Features:**
- Single migration (`m001_initial_dca_schema`) creates complete schema
- UTC timezone handling throughout
- Comprehensive indexing for performance
- Foreign key relationships maintained
### API Endpoints
#### **Client Management**
- `GET /api/v1/dca/clients` - List all DCA clients
- `GET /api/v1/dca/clients/{id}/balance` - Get client balance summary
- `POST /api/v1/dca/clients` - Create test client (development)
#### **Deposit Administration**
- `GET /api/v1/dca/deposits` - List all deposits
- `POST /api/v1/dca/deposits` - Create new deposit
- `PUT /api/v1/dca/deposits/{id}/status` - Confirm deposits
#### **Transaction Processing**
- `GET /api/v1/dca/transactions` - List processed Lamassu transactions
- `GET /api/v1/dca/transactions/{id}/distributions` - View distribution details
- `POST /api/v1/dca/manual-poll` - Trigger manual database poll
- `POST /api/v1/dca/test-transaction` - Process test transaction
#### **Configuration**
- `GET /api/v1/dca/config` - Get Lamassu database configuration
- `POST /api/v1/dca/config` - Save database and wallet settings
- `POST /api/v1/dca/test-connection` - Verify connectivity
### Frontend Architecture
#### **Vue.js Components**
- **Dashboard Overview** - System status and recent activity
- **Client Management** - DCA client table with balance tracking
- **Deposit Workflow** - Quick deposit forms and confirmation
- **Transaction History** - Lamassu transaction audit with drill-down
- **Configuration Panel** - Database and wallet setup with testing
#### **Key UX Features**
- Real-time balance updates during polling
- Loading states for all async operations
- Error handling with user-friendly notifications
- Responsive design for mobile administration
- Export functionality for audit and compliance
## Technical Implementation Details
### SSH Connection Setup
```bash
# On Lamassu server:
sudo mkdir -p /var/lib/postgresql/.ssh
sudo echo "your-public-key" >> /var/lib/postgresql/.ssh/authorized_keys
sudo chown -R postgres:postgres /var/lib/postgresql/.ssh
sudo chmod 700 /var/lib/postgresql/.ssh
sudo chmod 600 /var/lib/postgresql/.ssh/authorized_keys
```
### Commission Calculation Example
```python
# Real transaction: 2000 GTQ → 266,800 sats (3% commission, 0% discount)
crypto_atoms = 266800 # Total sats from Lamassu
commission_percentage = 0.03 # 3%
discount = 0.0 # No discount
effective_commission = 0.03 * (100 - 0) / 100 = 0.03
base_amount = 266800 / (1 + 0.03) = 258,835 sats (for DCA)
commission_amount = 266800 - 258835 = 7,965 sats (to commission wallet)
```
### Polling Strategy
- **Automatic**: Hourly background task via LNBits task system
- **Manual**: Admin-triggered polling for immediate processing
- **Smart Recovery**: Tracks last successful poll to prevent missed transactions
- **Error Handling**: Graceful failure with detailed logging
### Security Considerations
- SSH tunnel encryption for database connectivity
- Read-only database permissions
- Wallet key validation for all financial operations
- Input sanitization and type validation
- Audit logging for all administrative actions
## Development Workflow
### Adding New Features
1. **Models**: Update `models.py` with new Pydantic schemas
2. **Database**: Add migration to `migrations.py` (append only)
3. **CRUD**: Implement database operations in `crud.py`
4. **API**: Add endpoints to `views_api.py`
5. **Frontend**: Update Vue.js components in `static/js/index.js`
6. **Templates**: Modify HTML template if needed
### Testing
- Use "Test Connection" for database connectivity verification
- Use "Test Transaction" for DCA flow validation
- Manual polling for real-world transaction testing
- Monitor LNBits logs for detailed error information
### Debugging
- Enable debug logging: `DEBUG=true`
- Check SSH tunnel connectivity independently
- Verify Lamassu database query results
- Monitor wallet balance changes
- Review transaction audit trail
## Key Files Reference
- `transaction_processor.py` - Core Lamassu integration and DCA logic
- `models.py` - Complete data models for DCA system
- `crud.py` - Database operations with optimized queries
- `migrations.py` - Single condensed schema migration
- `static/js/index.js` - Admin dashboard Vue.js application
- `templates/myextension/index.html` - Admin interface template
- `config.json` - Extension metadata and configuration
- `tasks.py` - Background polling and invoice listeners
## Important Notes
- Extension uses LNBits internal payment system for Bitcoin transfers
- All timestamps stored and processed in UTC timezone
- Commission calculations handle edge cases and rounding
- SSH authentication prefers private keys over passwords
- Database polling is stateful and resumable after downtime
- UI displays human-readable usernames where available
- Export functions generate CSV files for external analysis
## Extension Status
**Current Version**: v0.0.1 (Initial Release)
**Status**: Production Ready
**Dependencies**: LNBits v1.0.0+, SSH access to Lamassu server
**License**: MIT

90
DCA-Common-Specification.md
View file

@ -1,90 +0,0 @@
# DCA System - Common Specification
## System Overview
This document describes the common elements of a Dollar Cost Averaging (DCA) system that integrates with Lamassu Bitcoin ATMs. The system consists of two LNBits extensions:
1. **Admin Extension**: Monitors Postgres database and manages DCA distributions
2. **Client Extension**: Provides user dashboard for DCA control and monitoring
## Context
A user provides a certain amount of cash to a Dollar Cost Average (DCA) service. This cash goes into a Lamassu Bitcoin ATM (it's a 2-way machine that allows both buying and selling).
For now, you can only DCA by purchasing Bitcoin, however it would be interesting to make sure that it is generalized in such a way that someone could also DCA into fiat. In the current moment we are not concerned with the latter option, we are only concerned with someone being able to DCA into Bitcoin.
The Lamassu ATM (often referred to as "the machine") runs a server which stores all transactions in a postgres database. It is important to note that not all transactions succeed, so for this service, we want to make sure that we are only accounting for successful transactions. We may want the ability to manually add a transaction in the case that a interaction is settled externally.
Note that the frame of reference with regards to a transaction will always be from the perspective of the layperson and Bitcoin. E.g., if a layperson sells. They are selling their Bitcoin to the machine and receiving fiat in return. If they buy, they are buying Bitcoin from the machine and inserting fiat in exchange.
This system will eventually involve multiple machines in different locations, however there is currently only one. All machines log to the same Postgres database and simply have a field for machine id.
## Definitions
**Dollar Cost Averaging**: When someone commits to buying an asset over time instead of in one lump sum
**layperson**: an unknown person who uses the Lamassu machine to either buy or sell bitcoin. They are not directly related to the DCA system. They are what fuel the system by their interactions with the system.
**client**: someone who is providing cash to the Lamassu ATM and receiving back Bitcoin through one of the methods defined below
**commission**: the amount that the machine charges to the layperson.
**cash-out**: when someone sells their bitcoin to the machine in return for cash.
**cash-in**: when someone buys Bitcoin from the machine with fiat.
## DCA Methods
Clients choose one of two DCA methods that they can change in their dashboard:
### Flow Mode
This works by the client choosing to receive their Bitcoin as a function of layperson transactions.
#### Example
1) A client provides 20,000 GTQ to DCA. Once the 20,000 GTQ is received it is placed into the ATM. It is now in the ATM.
2) Following its placement into the ATM, a layperson goes to cash out at the machine and decides to sell, i.e., exchange their BTC for 2,000 GTQ. They create a "sell" order and choose 2,000 GTQ. The machine calculates the exchange rate, taking into account commission, and provides the layperson a QR code to which they will send their BTC.
3) If the transaction is successful, the layperson receives their cash and it is logged in the postgres database on a separate server. The lnbits extension then detects that a new successful transaction has occurred and it distributes the transaction amongst all of the Flow Mode DCA'ers proportionally.
3a) if the transaction is unsuccessful, nothing happens
3b) leave room for a manual input in the case that a failed transaction is settled externally
### Fixed Mode
The DCA client can choose to receive up to X amount per day. They can vary the amount, but there is a limit. The extension admin will choose when the fixed DCA is distributed. Either it happens once a day at a fixed time, or it happens Y times per day.
## System Properties/Features
DCA transactions will be tagged with `aio-dca` so that the extension knows to filter for those when calculating metrics.
Clients can see things such as their:
- Average DCA rate in fiat/BTC
- Total amount of satoshis stacked
- any other useful stats
## Critical Requirements
### Duplicate Payment Prevention
We must have a check in place to know when a successful transaction has already been processed so that no duplicate payments occur.
### Transaction Processing Rules
- Only successful transactions should be processed
- Failed transactions should be ignored unless manually added
- All transactions must be properly logged and trackable
- Commission amounts should be handled separately from principal amounts
## Database Integration
The system integrates with the Lamassu ATM's Postgres database to monitor for new successful transactions. The database contains:
- Transaction records with success/failure status
- Machine ID for multi-location support
- Transaction amounts (principal + commission)
- Timestamps and other transaction metadata

197
DCA-System-Implementation-Plan.md
View file

@ -1,197 +0,0 @@
# DCA System Implementation Plan
## Current State
- **Base Extension**: SatoshiMachine (template extension)
- **Structure**: Complete LNBits extension with all necessary files
- **Status**: Ready to be overwritten with DCA functionality
## Updated System Design Based on Clarifications
### 1. Data Integration Solution - CSV Fetch Approach
**Implementation**: Admin extension will fetch CSV data using the provided bash script pattern:
- Execute SSH commands to export transaction data from Lamassu server
- Download CSV files: `cash_out_txs.csv`, `cash_in_txs.csv`, `cash_out_actions.csv`
- Process CSV data to identify new successful transactions
- Alternative: Direct Postgres connection (read-only) for real-time processing
**Benefits**:
- Secure (read-only access)
- Reliable data export from Lamassu
- Network security through SSH
### 2. Proportional Distribution Logic (CLARIFIED)
**Flow Mode Distribution**:
```python
# Example: Client A: 9,000 GTQ, Client B: 1,000 GTQ (Total: 10,000 GTQ)
# New transaction: 2,000 GTQ principal after commission
client_a_share = (9000 / 10000) * 2000 = 1800 GTQ worth of BTC
client_b_share = (1000 / 10000) * 2000 = 200 GTQ worth of BTC
# Convert to satoshis using transaction exchange rate
client_a_sats = 1800 * (crypto_atoms / fiat_amount)
client_b_sats = 200 * (crypto_atoms / fiat_amount)
```
### 3. System Architecture - Shared Database Approach
**Admin Extension** (Primary):
- Hosts all data models and business logic
- Processes transaction data (CSV/Postgres)
- Manages DCA distributions
- Provides internal API endpoints
- **Must be active** for system to function
**Client Extension** (Interface):
- User-facing dashboard
- Calls admin extension's internal APIs
- No direct database access
- Lightweight interface layer
### 4. Fixed Mode Configuration
**System-Wide Settings**:
- Admin configures Fixed Mode timing globally
- Maximum daily limit: **2000 GTQ per client**
- Insufficient funds handling: LNBits wallet "top-up" or Nostr notification
### 5. Authentication & User Mapping
**Client Identification**:
- User selects DCA wallet in client extension (standard LNBits pattern)
- Wallet cannot be changed after initiation (maintains transaction integrity)
- Admin manually adds clients using `user_id` + deposit amount
- No separate registration process required
### 6. Real-Time Updates Strategy
**Recommended Approach**: **Polling-based** for this use case
- Client dashboard polls admin APIs every 30-60 seconds
- Lower complexity than WebSocket for this scenario
- Sufficient responsiveness for DCA monitoring
- LNBits handles actual payment notifications
## Implementation Architecture
### Phase 1: Admin Extension (Core System)
1. **Database Models**:
- DCA clients and deposits
- Transaction processing tracking
- Commission distribution configuration
- Distribution history
2. **Transaction Processing**:
- CSV data fetching and parsing
- Duplicate detection using transaction IDs
- Flow Mode distribution calculations
- Commission distribution system
3. **Admin Interface**:
- Client management dashboard
- Transaction monitoring
- Commission distribution configuration
- System health monitoring
### Phase 2: Client Extension (User Interface)
1. **Dashboard Components**:
- DCA overview and metrics
- Transaction history
- Settings management
- Performance analytics
2. **API Integration**:
- Read-only access to admin extension APIs
- Real-time balance and status updates
- Settings synchronization
## Technical Specifications
### Data Flow
```
Lamassu ATM → CSV Export → Admin Extension → Process & Distribute → Client Extensions Display
```
### Security Model
- Admin extension: Full database access, transaction processing
- Client extension: Read-only API access, user-specific data only
- CSV/SSH: Secure remote data fetching with credentials management
### Commission Distribution System
- Configurable percentage allocation to specified wallets
- Can include DCA clients in commission distribution
- Separate from Flow Mode distribution
- Admin-controlled allocation rules
### Error Handling
- Insufficient Fixed Mode funds: LNBits wallet top-up + Nostr notification
- Failed transactions: Comprehensive logging and admin alerts
- Network issues: Retry mechanisms and offline mode handling
## File Structure Transformation
### From Current Template:
```
dca_admin/
├── templates/dca_admin/
│ ├── index.html
│ ├── dca_admin.html
│ └── _dca_admin.html
├── static/
├── models.py
├── crud.py
├── views.py
├── views_api.py
└── config.json
```
### To DCA System:
```
dca_admin/ # Admin Extension
├── templates/dca_admin/
│ ├── index.html
│ ├── client_management.html
│ ├── transaction_monitor.html
│ └── commission_config.html
├── static/
├── models.py # DCA clients, transactions, distributions
├── crud.py # Database operations
├── views.py # Admin interface
├── views_api.py # Internal APIs for client extension
├── transaction_processor.py # CSV processing & distribution logic
└── config.json
dca_client/ # Client Extension
├── templates/dca_client/
│ ├── index.html
│ ├── dashboard.html
│ └── analytics.html
├── static/
├── models.py # Minimal client-side models
├── views.py # Client interface
├── views_api.py # Client API endpoints
└── config.json
```
## Next Steps
1. **Create updated specifications** for both extensions
2. **Transform current template** into DCA admin extension
3. **Create new client extension** from scratch
4. **Implement CSV processing** and distribution logic
5. **Build admin interface** for system management
6. **Create client dashboard** with analytics
7. **Test integration** and distribution calculations
## Key Decisions Confirmed
✅ **Data Source**: CSV fetch with SSH (+ optional direct Postgres)
✅ **Architecture**: Shared database via admin extension APIs
✅ **Distribution**: Proportional by deposit amounts
✅ **Fixed Mode**: System-wide 2000 GTQ daily limit
✅ **Authentication**: LNBits user_id + selected wallet
✅ **Updates**: Polling-based (30-60 seconds)
✅ **Commission**: Separate configurable distribution system
The system is now fully specified and ready for implementation! 🚀

143
Extension-Admin-Specification.md
View file

@ -1,143 +0,0 @@
# DCA Client Extension - Technical Specification
## Goal
Create an admin extension where the deposits of DCA clients are recorded and managed. This extension monitors the Lamassu ATM's Postgres database and automatically distributes Bitcoin to DCA clients based on successful layperson transactions.
## Core Functionality
### Database Monitoring
The admin extension monitors a Postgres database for new successful transactions. Every time a new (unprocessed) successful transaction is posted to the postgres database, the admin extension distributes the principal amount among the DCA clients.
### Key Responsibilities
1. **Transaction Monitoring**: Continuously monitor the Lamassu Postgres database for new successful transactions
2. **Payment Distribution**: Automatically distribute Bitcoin to Flow Mode DCA clients proportionally when new transactions occur
3. **Client Management**: Record and manage DCA client deposits and balances
4. **Fixed Mode Processing**: Handle scheduled distributions for Fixed Mode DCA clients
5. **Manual Transaction Entry**: Provide interface for manually adding transactions settled externally
6. **Duplicate Prevention**: Ensure no transaction is processed twice
## Technical Requirements
### Database Integration
- Connect to external Lamassu Postgres database
- Monitor for new successful transactions
- Track processed transactions to prevent duplicates
- Handle multiple machine IDs for future multi-location support
### Payment Processing
- **Flow Mode Distribution**:
- Triggered by both BTC and Lightning successful cash-out transactions
- Distribute principal amount (`fiat_amount - actual_commission`) proportionally among Flow Mode clients only
- No minimum transaction size - all transactions trigger distribution
- **Commission Distribution**:
- Separate distribution system for commission amounts
- Configurable percentage allocation to specified wallets
- DCA clients can optionally be included in commission distribution
- **Fixed Mode Processing**:
- Process scheduled distributions based on admin-configured timing (daily or multiple times per day)
- Independent of layperson transactions
- Tag all DCA transactions with `aio-dca` for tracking and metrics
### Admin Interface Features
1. **Client Management Dashboard**
- Add new DCA clients
- Record initial deposits
- Set DCA mode (Flow/Fixed)
- View client balances and transaction history
2. **Transaction Monitoring**
- View all Lamassu transactions (successful/failed)
- Mark transactions as processed
- Manual transaction entry interface
- Transaction processing logs
3. **Fixed Mode Configuration**
- Set distribution schedule (once daily or multiple times)
- Configure maximum daily amounts per client
- Manual trigger for fixed distributions
4. **Commission Distribution Management**
- Configure commission distribution percentages
- Set target wallets for commission allocation
- Include/exclude DCA clients from commission distribution
- Monitor commission distribution history
5. **System Administration**
- Database connection settings
- Transaction filtering configuration (BTC/LN)
- System health monitoring
- Processing status and logs
### Security & Data Integrity
- Secure connection to external Postgres database
- Transaction processing locks to prevent race conditions
- Comprehensive logging of all operations
- Backup and recovery procedures for client data
## Data Models
### DCA Client
- Client ID
- Initial deposit amount
- Current balance
- DCA mode (Flow/Fixed)
- Fixed mode daily limit (if applicable)
- Creation date
- Status (active/inactive)
### Processed Transaction
- Lamassu transaction ID
- Processing timestamp
- Amount distributed
- Number of clients affected
- Processing status
### Distribution Record
- Client ID
- Transaction ID
- Amount received (satoshis)
- Exchange rate at time of distribution
- Timestamp
- Distribution type (flow/fixed/manual/commission)
### Commission Distribution Config
- Wallet ID
- Allocation percentage
- Wallet type (DCA client/external wallet)
- Status (active/inactive)
## Integration Points
### External Systems
- Lamassu Postgres database (read-only access)
- LNBits wallet system for Bitcoin distributions
### Internal Systems
- Client extension (for user dashboards)
- LNBits core wallet functionality
- LNBits payment processing
## Monitoring & Alerting
- Database connection health
- Transaction processing failures
- Duplicate transaction attempts
- Distribution calculation errors
- Wallet balance monitoring
## Future Considerations
- Multi-location machine support
- Fiat DCA capability (mentioned as future feature)
- Advanced reporting and analytics
- API endpoints for external integrations

184
Extension-Client-Specification.md
View file

@ -1,184 +0,0 @@
# DCA Client Extension - Technical Specification
## Goal
Create a client extension that provides users with a dashboard to control and monitor their Dollar Cost Averaging (DCA) activities. This extension gives DCA clients visibility into their Bitcoin accumulation and allows them to manage their DCA preferences.
## Core Functionality
### User Dashboard
The client extension provides a comprehensive dashboard where DCA clients can:
1. **Monitor DCA Progress**: View their Bitcoin accumulation over time
2. **Control DCA Settings**: Switch between Flow Mode and Fixed Mode
3. **Track Performance**: Analyze their DCA strategy effectiveness
4. **View Transaction History**: See all their DCA-related transactions
### Key Features
1. **DCA Mode Management**
- Switch between Flow Mode and Fixed Mode
- Configure Fixed Mode daily limits
- View current mode status and settings
2. **Portfolio Tracking**
- Current total satoshis accumulated
- Average DCA rate in fiat/BTC
- Total fiat amount invested
- Portfolio value and performance metrics
3. **Transaction History**
- Detailed history of all DCA transactions
- Transaction amounts, rates, and timestamps
- Filter by date range, transaction type
- Export functionality for record keeping
4. **Analytics Dashboard**
- Charts showing DCA progress over time
- Average purchase price trends
- Comparison with market price
- Performance metrics and statistics
## Technical Requirements
### User Interface Components
1. **Overview Dashboard**
- Current balance display (satoshis and fiat value)
- Total invested amount
- Average DCA rate
- Recent transaction summary
2. **DCA Settings Panel**
- Mode selection (Flow/Fixed)
- Fixed mode daily limit configuration
- DCA activation/deactivation controls
- Settings history and changes log
3. **Analytics & Charts**
- Interactive charts for DCA progress
- Performance comparison charts
- Statistical summaries
- Export functionality for data
4. **Transaction Management**
- Paginated transaction history
- Search and filter capabilities
- Transaction details modal
- CSV/PDF export options
### Data Integration
- Read-only access to client's DCA data from admin extension
- Real-time updates of transaction status
- Integration with LNBits wallet for balance display
- Exchange rate integration for fiat value calculations
### User Experience Features
1. **Responsive Design**
- Mobile-friendly interface
- Adaptive layouts for different screen sizes
- Touch-friendly controls
2. **Real-time Updates**
- Live balance updates
- Notification of new DCA transactions
- Status indicators for system health
3. **Customization Options**
- Preferred fiat currency display
- Chart time ranges and preferences
- Dashboard layout customization
## Data Models
### Client Profile
- Client ID (linked to LNBits user)
- DCA preferences and settings
- Notification preferences
- Dashboard customization settings
### DCA Transaction View
- Transaction ID
- Amount in satoshis
- Fiat amount and currency
- Exchange rate at transaction time
- Transaction timestamp
- Transaction type (flow/fixed/manual)
- Status and confirmations
### Performance Metrics
- Total invested (fiat)
- Total accumulated (satoshis)
- Average DCA rate
- Best/worst purchase rates
- Time-weighted performance
- Comparison with market benchmarks
## Security & Privacy
### Access Control
- User can only access their own DCA data
- Secure authentication via LNBits user system
- Read-only access to prevent data manipulation
### Data Protection
- Encrypted data transmission
- Secure storage of user preferences
- Privacy-compliant data handling
- Optional data anonymization for analytics
## Integration Points
### LNBits Core
- User authentication and wallet integration
- Payment processing for DCA transactions
- Balance and transaction history access
### Admin Extension
- Read access to client's DCA data
- Real-time updates from distribution processing
- Settings synchronization
### External Services
- Exchange rate APIs for fiat conversions
- Chart libraries for data visualization
- Export services for data portability
## User Workflow
### Initial Setup
1. User accesses client extension dashboard
2. System displays current DCA status (if any)
3. User can configure DCA preferences
4. Dashboard shows initial balance and settings
### Daily Usage
1. User checks dashboard for latest DCA activity
2. Views new transactions and updated metrics
3. Optionally adjusts DCA settings
4. Reviews performance analytics
### Advanced Features
1. Export transaction history
2. Analyze DCA performance vs market
3. Configure notifications and alerts
4. Compare with DCA benchmarks
## Responsive Design Requirements
- Mobile-first approach for accessibility
- Tablet optimization for detailed analytics
- Desktop experience for comprehensive management
- Cross-browser compatibility
- Fast loading and smooth interactions
## Future Enhancements
- Social features (anonymous performance comparisons)
- Advanced analytics and AI insights
- Integration with external portfolio trackers
- Mobile app development
- Advanced notification systems

77
ExtensionDescription.md
View file

@ -1,77 +0,0 @@
## Goal
Create two extensions (here we will focus on the admin extension)
1. Have an admin extension where the deposits of the "client" are recorded. This will be the value that the client sees as their initial balance.
1. Give users dashboard from which to control their DCA (we don't focus on this one here)
## Context
A user provides a certain amount of cash to a Dollar Cost Average (DCA) service. This cash goes into a Lamassu Bitcoin ATM (it's a 2-way machine that allows ).
For now, you can only DCA by purchasing Bitcoin, however it would be interesting to make sure that it is generalized in such a way that someone could also DCA into fiat. In the current moment we are not concerned with the latter option, we are only concerned with someone being able to DCA into Bitcoin
The Lamassu ATM (often referred to as "the machine") runs a server which stores all transactions in a postgres database. It is important to note that not all transactions succeed, so for this service, we want to make sure that we are only accounting for successful transactions. We may want the ability to manually add a transaction in the case that a interactions is settled externally.
Note that the frame of reference with regards to a transaction will always be from the perspective of the layperson and Bitcoin. E.g., if a layperson sells. They are selling their Bitcoin to the machine and receiving fiat in return. If they buy, they are buying Bitcoin from the machine and inserting fiat in exchange.
This system will eventually involve multiple machines in different locations, however there is currently only one. All machines log to the same Postgres database and simply have a field for machine id
For the admin extension, which is this one, we want to monitor a postgres database. Every time a new (unprocessed) successful transaction is posted to the postgres database, we want the admin extension to distribute the principal amount among the DCA clients.
The amount that corresponds to the commission
## Definitions
Dollar Cost Averaging: When someone commits to buying an asset over time instead of in one lump sum
layperson: an unknown person who uses the Lamassu machine to either buy or sell bitcoin. They are not directly related to the DCA system. They are what fuel the system by their interactions with the system.
client: someone who is providing cash to the Lamassu ATM and receiving back Bitcoin through one of the methods defined below
commission: the amount that the machine charges to the layperson.
cash-out: when someone sells their bitcoin to the machine in return for cash.
cash-in: when someone buys Bitcoin from the machine with fiat.
They choose one of two DCA methods that they can choose in their dashboard. They can change this
### Flow Mode
This works by the client choosing to receive their Bitcoin as a function of layperson transactions.
#### Example
1) A client provides 20,000 GTQ to DCA. Once the 20,000 GTQ is received it is placed into the ATM. It is now in the ATM.
2) Following its placement into the ATM, a layperson goes to cash out at the machine and decides to sell, i.e., exchange their BTC for 2,000 GTQ. They create a "sell" order and choose 2,000 GTQ. The machine calculates the exchange rate, taking into account commission, and provides the layperson a QR code to which they will send their BTC.
3) If the transaction is successful, the layperson receives their cash and it is logged in the postgres database on a separate server. The lnbits extension then detects that a new successful transaction has occurred and it distributes the transaction amongst all of the Flow Mode DCA'ers proportionally.
3a) if the transaction is unsuccessful, nothing happens
3b) leave room for a manual input in the case that a failed transaction is settled externally
### Fixed Mode
The DCA client can choose to receive up to X amount per day. They can vary the amount, but there is a limit. The extension admin will choose when the fixed DCA is distributed. Either it happens once a day at a fixed time, or it happens Y times per day.
## Properties/Features of the extension
DCA transactions will be tagged with `aio-dca` so that the extension knows to filter for those when calculating metrics.
Clients can see things such as their:
- Average DCA rate in fiat/BTC
- Total amount of satoshis stacked
- any other useful stats
## Important
We must have a check in place to know when a successful transaction has already been processed so that no duplicate payments occur
## Notes to AI
If you have any questions about particular design features, please ask and we can amend this