miscellaneous files

misc-aio/LNBITS_CONFIG_CLARIFICATION.md

@@ -0,0 +1,95 @@
+# LNBits Configuration Clarification
+
+## Key Finding: walletId is NOT Required
+
+After reviewing the LNBits codebase, we can confirm that **walletId is not necessary** for the Lamassu-LNBits integration because **the adminKey is already wallet-specific**.
+
+## Evidence from LNBits Source Code
+
+### 1. Wallet Model Structure
+```python
+# packages/lnbits/lnbits/core/models/wallets.py
+class Wallet(BaseModel):
+    id: str
+    user: str  
+    name: str
+    adminkey: str  # Each wallet has unique adminkey
+    inkey: str     # Each wallet has unique inkey
+```
+
+### 2. Key-to-Wallet Lookup
+```sql
+-- packages/lnbits/lnbits/core/crud/wallets.py:194
+SELECT *, COALESCE((
+    SELECT balance FROM balances WHERE wallet_id = wallets.id
+), 0)
+AS balance_msat FROM wallets
+WHERE (adminkey = :key OR inkey = :key) AND deleted = false
+```
+
+**Key Point**: LNBits looks up wallets directly by the adminkey/inkey - no walletId parameter needed.
+
+### 3. Authentication Flow
+```python
+# packages/lnbits/lnbits/decorators.py:94
+wallet = await get_wallet_for_key(key_value)
+```
+
+The authentication system uses only the key to identify and authorize access to the specific wallet.
+
+### 4. Unique Key Generation
+```python  
+# packages/lnbits/lnbits/core/crud/wallets.py:24-25
+adminkey=uuid4().hex,  # Unique UUID for each wallet
+inkey=uuid4().hex,     # Unique UUID for each wallet
+```
+
+Each wallet gets unique keys generated as UUIDs, ensuring 1:1 key-to-wallet relationship.
+
+## Impact on Lamassu Integration
+
+### Simplified Configuration
+
+**Before (Incorrect Assumption)**:
+```javascript
+const config = {
+  endpoint: 'https://lnbits.example.com',
+  adminKey: 'abc123...',
+  walletId: 'wallet_xyz'  // ❌ Not needed!
+}
+```
+
+**After (Correct Implementation)**:
+```javascript  
+const config = {
+  endpoint: 'https://lnbits.example.com', 
+  adminKey: 'abc123...'  // ✅ Admin key identifies wallet
+}
+```
+
+### API Calls Simplified
+
+All LNBits API calls use the adminKey in the `X-API-KEY` header, which automatically identifies the target wallet:
+
+```javascript
+// Create invoice - no walletId needed
+POST /api/v1/payments
+Headers: { 'X-API-KEY': 'abc123...' }
+Body: { "out": false, "amount": 1000, "memo": "Purchase" }
+
+// Check balance - no walletId needed  
+GET /api/v1/wallet
+Headers: { 'X-API-KEY': 'abc123...' }
+```
+
+## Updated Migration Benefits
+
+1. **Fewer Configuration Parameters** - Reduces setup complexity
+2. **Eliminates Mismatch Errors** - No risk of wrong walletId/adminKey pairs
+3. **Consistent with LNBits Design** - Follows intended architecture
+4. **Simpler Admin UI** - Fewer fields in configuration forms
+5. **Reduced Validation Logic** - Less error-prone configuration
+
+## Conclusion
+
+The walletId parameter should be **removed from the LNBits integration plan**. The adminKey serves as both authentication credential and wallet identifier, following LNBits' design principle of wallet-specific API keys.