diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index a553bd1..2c60692 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -29,13 +29,28 @@ priority: critical --- +## Target Market Context + +> [!important] Cash-Out Dominant Market +> Market research shows **95%+ of activity is cash-out** (users selling Bitcoin for cash). This is typical for: +> - Remittance corridors (receiving Bitcoin from abroad) +> - Bitcoin-paid workers converting to local currency +> - Merchants liquidating Bitcoin revenue +> +> **Implications:** +> - Bill dispenser is **essential** for testing, not optional +> - Cash-out flow is the **critical path** +> - Cash-in still important (equal weight in code) but secondary for go-live + +--- + ## Guiding Principles > [!important] Build Philosophy -> 1. **Vertical slices** - Each phase delivers working functionality -> 2. **Test on real hardware early** - Don't wait until "everything is ready" -> 3. **Mock what you must** - But prefer real components when possible -> 4. **Ship incrementally** - Working ATM with 1 bill validator > perfect ATM with 10 +> 1. **Cash-out first** - Primary use case, test with real dispenser early +> 2. **Vertical slices** - Each phase delivers working functionality +> 3. **Test on real hardware early** - Dispenser essential, not optional +> 4. **Ship incrementally** - Working cash-out ATM > feature-complete vaporware --- @@ -1436,7 +1451,13 @@ console.log(`Dispensed ${dispensed} bills`) ## Phase 4: Payment Flows > [!goal] Deliverable -> Complete cash-in and cash-out flows working end-to-end. +> Complete cash-out (primary) and cash-in flows working end-to-end. + +> [!important] Cash-Out First +> Given 95%+ cash-out activity in target market: +> 1. **4.2 Cash-Out** - Implement and test first +> 2. **4.3 Cash-In** - Implement second +> 3. Both flows share Lightning.Pub integration ### 4.1 Lightning.Pub Integration @@ -1589,14 +1610,23 @@ export class ATMCashuWallet { ### 4.5 Milestone Checklist +**Priority 1: Cash-Out (95% of volume)** - [ ] Lightning.Pub client connects -- [ ] Can create invoices -- [ ] Can receive payments -- [ ] Cash-in flow works end-to-end (mock hardware) -- [ ] Cash-out flow works end-to-end (mock hardware) +- [ ] Can create invoices (for user to pay) +- [ ] Invoice payment detection working +- [ ] Dispenser integration (real hardware!) +- [ ] Cash-out flow works end-to-end with real dispenser +- [ ] NFC BOLT card tap-to-withdraw working + +**Priority 2: Cash-In** +- [ ] Can receive payments (CLINK debit) - [ ] CLINK offer request/response working +- [ ] Cash-in flow works end-to-end (mock validator OK) - [ ] NIP-17 receipts delivered + +**Priority 3: Advanced** - [ ] Cashu offline mode works +- [ ] Real bill validator integration --- @@ -1725,28 +1755,31 @@ export function useFleet() { ## Development Hardware -### Recommended Dev Kit (One-Way: Cash-In Only) +> [!warning] Cash-Out is Primary Use Case +> With 95%+ activity being cash-out, **bill dispenser is required** for meaningful testing - not optional. + +### Minimum Dev Kit (Cash-Out Priority) | Component | Model | Purpose | Est. Cost | |-----------|-------|---------|-----------| | SBC | Raspberry Pi 5 (8GB) | Development machine | $80 | -| Display | Waveshare 7" touch | UI development | $70 | -| Bill Validator | ITL NV200 (used) | Real hardware testing | $300-500 | +| Display | Waveshare 10.1" touch | UI development | $90 | +| **Bill Dispenser** | Puloon LCDM-1000 (used) | **Cash-out testing (critical)** | $400-600 | +| NFC Reader | ACR122U | BOLT card tap-to-withdraw | $35 | | Printer | Generic ESC/POS | Receipt testing | $50 | -| NFC Reader | ACR122U | BOLT card testing | $35 | -| **Total** | | | **~$535-735** | +| **Total** | | | **~$655-855** | -### Full Dev Kit (Two-Way: Cash-In + Cash-Out) +### Full Dev Kit (Two-Way) | Component | Model | Purpose | Est. Cost | |-----------|-------|---------|-----------| | SBC | Raspberry Pi 5 (8GB) | Development machine | $80 | | Display | Waveshare 10.1" touch | Larger UI for two-way | $90 | -| Bill Validator | ITL NV200 (used) | Cash-in acceptance | $300-500 | -| **Bill Dispenser** | Puloon LCDM-1000 (used) | Cash-out dispensing | $400-800 | -| Printer | Generic ESC/POS | Receipt testing | $50 | +| **Bill Dispenser** | Puloon LCDM-1000 (used) | Cash-out (primary) | $400-600 | +| Bill Validator | ITL NV200 (used) | Cash-in (secondary) | $300-500 | | NFC Reader | ACR122U | BOLT card testing | $35 | -| **Total** | | | **~$955-1,555** | +| Printer | Generic ESC/POS | Receipt testing | $50 | +| **Total** | | | **~$955-1,355** | ### Bill Dispenser Options @@ -1757,7 +1790,15 @@ export function useFleet() { | Fujitsu F53 | 4 | 2,500 notes | USB/RS-232 | $800-1,200 | > [!tip] Start with Puloon LCDM-1000 -> Single cassette is sufficient for development. Simple RS-232 protocol with existing lamassu-machine drivers to reference. +> Single cassette handles the primary use case. Multi-cassette (for multiple denominations) can come later. + +### Bill Validator Options (Secondary Priority) + +| Model | Protocol | Notes | Est. Used Price | +|-------|----------|-------|-----------------| +| **ITL NV200** | eSSP | Industry standard, good docs | $300-500 | +| MEI Cashflow | ccTalk/MDB | Common in NA market | $250-400 | +| JCM iVizion | ID-003 | Existing lamassu driver | $200-350 | ### Sourcing Used Equipment @@ -1765,10 +1806,11 @@ export function useFleet() { - **Alibaba** - New units, but longer shipping - **ATM parts suppliers** - atmpartsnow.com, atmequipment.com - **Bitcoin ATM operators** - Sometimes sell retired units +- **ATM route liquidations** - Best prices, bulk deals ### Mock-First Development -For most development, mocks are sufficient: +For initial UI/flow development, mocks work - but **test with real dispenser early**: ```typescript // Start with mocks