add project specification files

2025-06-17 18:18:44 +02:00 · 2025-06-17 18:18:44 +02:00 · a8e1918633
commit a8e1918633
parent 5d77957b55
6 changed files with 856 additions and 0 deletions
--- a/DCA-Common-Specification.md
+++ b/DCA-Common-Specification.md
@ -0,0 +1,90 @@
+# 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 
--- a/DCA-System-Implementation-Plan.md
+++ b/DCA-System-Implementation-Plan.md
@ -0,0 +1,197 @@
+# 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! 🚀 
--- a/Extension-Admin-Specification.md
+++ b/Extension-Admin-Specification.md
@ -0,0 +1,143 @@
+# DCA Admin 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 
--- a/Extension-Client-Specification.md
+++ b/Extension-Client-Specification.md
@ -0,0 +1,184 @@
+# 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 
--- a/ExtensionDescription.md
+++ b/ExtensionDescription.md
@ -0,0 +1,77 @@
+## 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
--- a/Lamassu-Database-Analysis.md
+++ b/Lamassu-Database-Analysis.md
@ -0,0 +1,165 @@
+# Lamassu Database Analysis - Based on Sample Data
+
+## Database Schema Analysis
+
+Based on the provided CSV sample data, here's the identified structure:
+
+### Transaction Table Structure (Estimated Column Names)
+
+| Position | Field Name (Estimated) | Sample Values | Description |
+|----------|------------------------|---------------|-------------|
+| 1 | `id` | `81b3f12e-7c75-41a9-a212-8a82dcbfda07` | Transaction ID (UUID) |
+| 2 | `device_id` | `b3f790bd3207aec95157de7c7a06d4130586e4d5b2c5b10a5b1dc9ff50498366` | ATM Device identifier |
+| 3 | `crypto_address` | `bc1qc7gqgck9tx6cgv3d7y89xmqzvn6435u035l09m` | BTC address or Lightning invoice |
+| 4 | `crypto_atoms` | `512400`, `31100`, `312100` | Amount in smallest crypto unit (satoshis) |
+| 5 | `crypto_code` | `BTC`, `LN` | Cryptocurrency type |
+| 6 | `fiat_amount` | `4000.00000`, `100.00000` | Fiat amount requested |
+| 7 | `fiat_code` | `GTQ` | Fiat currency code (Guatemalan Quetzal) |
+| 8 | `status` | `confirmed`, `notSeen` | **Transaction status (CRITICAL)** |
+| 9 | `send` | `t`, `f` | Boolean - Send transaction flag |
+| 10 | `receive` | `f` | Boolean - Receive transaction flag |
+| 11 | `flag_11` | `f` | Boolean - Unknown purpose |
+| 12 | `error_code` | `Operator cancel` | Error/cancellation reason |
+| 13 | `created` | `2025-06-09 19:12:42.040933+00` | **Transaction creation timestamp** |
+| 14 | `send_confirmed` | `2025-06-09 19:26:08.801857+00` | Send confirmation timestamp |
+| 15 | `flag_15` | | Various flags |
+| 16-18 | `flags_16_18` | `f`, `f`, `f` | Additional boolean flags |
+| 19 | `confirmations` | `40`, `20`, `8` | Number of confirmations |
+| 20 | `discount_1` | `0` | First discount field |
+| 21 | `discount_2` | `100`, `0` | **Discount percentage (CRITICAL)** |
+| 22 | `dispense_confirmed` | `100` | Dispense confirmation amount |
+| 23 | `cancel_reason` | `operatorCancel` | Cancellation reason code |
+| 24 | `machine_id` | `47ac1184-8102-11e7-9079-8f13a7117867` | **Machine UUID (consistent across all)** |
+| 25 | `batch_id` | `25`, `26`, `16` | Batch identifier |
+| 26 | `batch_time` | `2025-06-09 19:14:49.618988+00` | Batch processing time |
+| 27 | `flag_27` | `f` | Boolean flag |
+| 28-29 | `fields_28_29` | | Additional fields |
+| 30 | `commission_percentage` | `0.05500`, `0.04500` | **Commission rate** |
+| 31 | `exchange_rate` | `826091.28000`, `339104.71000` | **Exchange rate at transaction time** |
+| 32 | `dispensed` | `512400`, `31100` | **Actually dispensed amount** |
+| 33+ | `additional_fields` | Various | Additional transaction metadata |
+
+## Key Findings for DCA System
+
+### ✅ Critical Fields Identified
+
+1. **Transaction Status**: Column 8 (`status`)
+   - `confirmed` = Successful transaction ✓
+   - `notSeen` = Failed/incomplete transaction ✗
+
+2. **Transaction Amounts**:
+   - **Fiat Amount**: Column 6 (`fiat_amount`) - What layperson requested
+   - **Crypto Amount**: Column 4 (`crypto_atoms`) - Satoshis/smallest unit
+   - **Dispensed Amount**: Column 32 (`dispensed`) - Actually given amount
+
+3. **Commission Data**:
+   - **Commission Rate**: Column 30 (`commission_percentage`) - e.g., 0.05500 (5.5%)
+   - **Discount Percentage**: Column 21 (`discount_percentage`) - e.g., 100 = no commission, 10 = 10% off
+   - **Exchange Rate**: Column 31 (`exchange_rate`) - Rate at transaction time
+
+4. **Timing**:
+   - **Created**: Column 13 (`created`) - Transaction initiation
+   - **Confirmed**: Column 14 (`send_confirmed`) - When completed
+
+5. **Machine Identification**:
+   - **Machine ID**: Column 24 (`machine_id`) - Same across all: `47ac1184-8102-11e7-9079-8f13a7117867`
+
+### Transaction Types Observed
+
+1. **Successful Cash-Out (Sell)**: `status = 'confirmed'`, `send = 't'`
+   - Layperson sells BTC, receives fiat
+   - These transactions should trigger DCA distributions
+
+2. **Failed Transactions**: `status = 'notSeen'`
+   - Should be ignored by DCA system
+
+3. **Cancelled Transactions**: Contains `"Operator cancel"`
+   - Should be ignored even if status shows confirmed
+
+4. **Lightning vs On-Chain**: 
+   - `crypto_code = 'LN'` for Lightning
+   - `crypto_code = 'BTC'` for on-chain
+
+5. **Discount Analysis from Sample Data**:
+   - Most transactions show `100` in discount field = **NO COMMISSION**
+   - One transaction shows `90` = **90% discount** (only 10% of commission applies)
+   - Standard transactions appear to have 100% discount (commission-free)
+   - Special promotional transactions may have partial discounts
+
+## SQL Query for DCA System
+
+Based on this analysis, here's the query to get new successful transactions:
+
+```sql
+-- Get new successful cash-out transactions for DCA distribution
+SELECT 
+    id,
+    fiat_amount,
+    crypto_atoms,
+    commission_percentage,
+    discount_percentage,  -- Column 21: Critical for commission calculation
+    exchange_rate,
+    dispensed,
+    created,
+    send_confirmed,
+    machine_id
+FROM transactions 
+WHERE status = 'confirmed' 
+    AND send = 't' 
+    AND error_code IS NULL 
+    AND cancel_reason IS NULL
+    AND created > :last_processed_timestamp
+ORDER BY created ASC;
+```
+
+## Answers to Your Original Questions
+
+### 3. Flow Mode Distribution Logic (FINAL)
+- **Trigger Transactions**: Both `BTC` and `LN` (Lightning) successful cash-outs
+- **Target Recipients**: **Flow Mode DCA clients ONLY** (Fixed Mode clients not affected)
+- **Distribution Amount**: `fiat_amount - actual_commission` (principal only)
+- **No Minimum**: All successful transactions trigger distribution, regardless of size
+- **Commission Calculation**:
+  ```
+  base_commission = fiat_amount * commission_percentage
+  actual_commission = base_commission * (1 - discount_percentage/100)
+  flow_mode_distribution = fiat_amount - actual_commission
+  ```
+- **Bitcoin Value Reference**: Use `crypto_atoms` for rate calculations
+- **Special Cases**:
+  - If `discount_percentage = 100`: No commission, Flow Mode gets full `fiat_amount`
+  - Commission amount (if any) goes to separate distribution system
+
+### 4. Commission Distribution System (UPDATED)
+- **Base Commission Rate**: `commission_percentage` (e.g., 0.05500 = 5.5%)
+- **Discount Applied**: `discount_percentage` (e.g., 100 = no commission, 10 = 10% off)
+- **Commission Calculation**:
+  ```
+  base_commission = fiat_amount * commission_percentage
+  discount_amount = base_commission * (discount_percentage / 100)
+  actual_commission = base_commission - discount_amount
+  ```
+- **Distribution Logic**:
+  - **Principal Amount**: `fiat_amount - actual_commission` → **Flow Mode DCA clients only**
+  - **Commission Amount**: `actual_commission` → **Separate distribution system** (configurable percentages to specified wallets)
+  - **DCA clients can potentially be included** in commission distribution
+- **Example**: 1000 GTQ transaction, 5.5% commission, 10% discount:
+  - Base commission: 1000 * 0.055 = 55 GTQ
+  - Actual commission: 55 - 5.5 = 49.5 GTQ
+  - **To Flow Mode DCA**: 1000 - 49.5 = 950.5 GTQ
+  - **To Commission Distribution**: 49.5 GTQ (distributed per admin configuration)
+
+### Duplicate Prevention Strategy
+- Use the `id` field (transaction UUID) to track processed transactions
+- Store processed transaction IDs in your LNBits extension database
+- Query: `WHERE id NOT IN (processed_transaction_ids)`
+
+## Recommendations
+
+1. **Focus on Cash-Out Transactions**: Filter for `send = 't'` (layperson selling BTC)
+2. **Status Check**: Only process `status = 'confirmed'` 
+3. **Error Handling**: Exclude transactions with `error_code` or `cancel_reason`
+4. **Use Dispensed Amount**: Consider using `dispensed` field for actual transaction value
+5. **Commission Decision**: Decide whether DCA clients get commission benefit or not
+
+This sample data provides everything needed to build the DCA system! 🎯