1 files changed, 511 insertions, 0 deletions

diff --git a/docs/MULTI_MINT_DESIGN.md b/docs/MULTI_MINT_DESIGN.md
new file mode 100644
index 0000000..f4db06b
--- /dev/null
+++ b/docs/MULTI_MINT_DESIGN.md
@@ -0,0 +1,511 @@
+# Multi-Mint Support — Design Document
+
+**Branch**: `feature/multi-mint-support`
+**Date**: 2026-05-18
+**Status**: Implementation Phase
+
+---
+
+## 1. Overview
+
+Extend the ESP32 TollGate firmware to accept Cashu ecash payments from **multiple mints** instead of a single hardcoded mint URL. The system must:
+
+- Accept tokens from any of 4 configured mints
+- Track mint reachability via periodic health probes
+- Only accept payments from mints that are currently reachable (successful swap)
+- Expose all reachable mints in the discovery endpoint and captive portal
+- Manage per-mint wallets with independent keysets and proof storage
+
+### Supported Mints
+
+| Mint | URL |
+|------|-----|
+| Minibits | `https://mint.minibits.cash/Bitcoin` |
+| CoinOS | `https://mint.coinos.io` |
+| 21mint | `https://21mint.me` |
+| LNVoltz | `https://mint.lnvoltz.com` |
+
+All verified reachable via `GET /v1/info` (HTTP 200).
+
+---
+
+## 2. Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    config.json                       │
+│  "accepted_mints": ["url1", "url2", "url3", "url4"] │
+└──────────────────────┬──────────────────────────────┘
+                       │
+          ┌────────────┼────────────────┐
+          ▼            ▼                ▼
+   ┌──────────┐  ┌──────────┐   ┌───────────────┐
+   │  Config   │  │  Health  │   │  Multi-Wallet │
+   │  Layer    │  │  Tracker │   │  (Nucula)     │
+   │           │  │          │   │               │
+   │ accepted_ │  │ probe    │   │ Wallet[0] →   │
+   │ mints[]   │  │ every    │   │  mint A       │
+   │           │  │ 5min     │   │ Wallet[1] →   │
+   │           │  │          │   │  mint B       │
+   │           │  │ recovery │   │ ...           │
+   │           │  │ thresh=3 │   │               │
+   └─────┬─────┘  └────┬─────┘   └───────┬───────┘
+         │              │                  │
+         ▼              ▼                  ▼
+   ┌─────────────────────────────────────────────────┐
+   │              cashu_is_mint_accepted()            │
+   │  in config AND reachable → accept               │
+   └────────────────────┬────────────────────────────┘
+                        │
+          ┌─────────────┼──────────────┐
+          ▼             ▼              ▼
+   ┌──────────┐  ┌───────────┐  ┌───────────┐
+   │Discovery │  │  Captive  │  │  Payment  │
+   │ Endpoint │  │  Portal   │  │  Handler  │
+   │          │  │           │  │           │
+   │ 1 tag    │  │ mint list │  │ find right│
+   │ per      │  │ with      │  │ wallet,   │
+   │ reachable│  │ indicators│  │ receive() │
+   │ mint     │  │           │  │           │
+   └──────────┘  └───────────┘  └───────────┘
+```
+
+---
+
+## 3. Phase Details
+
+### Phase 1: Config Layer — Multi-Mint Array
+
+**Files**: `main/config.h`, `main/config.c`
+
+**Changes**:
+
+- Increase `TOLLGATE_MAX_MINT_URLS` from `3` to `8`
+- Add to `tollgate_config_t`:
+  ```c
+  char accepted_mints[TOLLGATE_MAX_MINT_URLS][256];
+  int accepted_mint_count;
+  ```
+- Keep existing `mint_url[256]` for backward compatibility
+- Parse new `"accepted_mints"` JSON array from config.json
+- If `"accepted_mints"` absent, populate from `"mint_url"` (backward compat)
+- Update default config.json generation to include `"accepted_mints"`
+
+**Config.json format** (new):
+```json
+{
+  "nsec": "...",
+  "accepted_mints": [
+    "https://mint.minibits.cash/Bitcoin",
+    "https://mint.coinos.io",
+    "https://21mint.me",
+    "https://mint.lnvoltz.com"
+  ],
+  "mint_url": "https://mint.minibits.cash/Bitcoin"
+}
+```
+
+The `"mint_url"` field is kept as fallback / primary mint identifier.
+
+---
+
+### Phase 2: Mint Acceptance — Multi-Mint Check
+
+**Files**: `main/cashu.c`, `main/cashu.h`
+
+Replace single-mint check in `cashu_is_mint_accepted()`:
+
+```c
+bool cashu_is_mint_accepted(const char *mint_url) {
+    if (!mint_url || mint_url[0] == '\0') return false;
+    const tollgate_config_t *cfg = tollgate_config_get();
+    for (int i = 0; i < cfg->accepted_mint_count; i++) {
+        if (strstr(mint_url, cfg->accepted_mints[i]) != NULL)
+            return true;
+    }
+    return false;
+}
+```
+
+This is the config-only check. Phase 4 adds health gating.
+
+---
+
+### Phase 3: Mint Health Tracker
+
+**New files**: `main/mint_health.h`, `main/mint_health.c`
+
+**Data structures**:
+
+```c
+#define MINT_HEALTH_MAX 8
+#define MINT_HEALTH_PROBE_INTERVAL_S  300
+#define MINT_HEALTH_PROBE_TIMEOUT_MS  15000
+#define MINT_HEALTH_RECOVERY_THRESHOLD 3
+
+typedef struct {
+    char url[256];
+    bool reachable;
+    uint8_t consecutive_successes;
+    int64_t last_probe_ms;
+    int last_http_status;
+} mint_status_t;
+
+typedef void (*mint_health_changed_cb)(void);
+```
+
+**Public API**:
+
+```c
+esp_err_t mint_health_init(const char urls[][256], int count);
+void mint_health_start(void);
+void mint_health_stop(void);
+const mint_status_t *mint_health_get_all(int *out_count);
+bool mint_health_is_reachable(const char *url);
+void mint_health_mark_unreachable(const char *url);
+void mint_health_register_callback(mint_health_changed_cb cb);
+```
+
+**Probing logic** (FreeRTOS task):
+
+| Parameter | Value | Rationale |
+|-----------|-------|-----------|
+| Endpoint | `GET {url}/v1/info` | Lightweight, no auth required |
+| Timeout | 15 seconds | ESP32 resource-constrained, 30s too long |
+| Interval | 5 minutes (`vTaskDelay`) | Matches Go reference |
+| Failure | Immediate | Single failed probe → unreachable |
+| Recovery | 3 consecutive successes | 15 min sustained health (matches Go) |
+| Initial | Success → reachable immediately | Set `consecutive_successes = threshold` |
+
+**Thread safety**: Single FreeRTOS mutex protecting the status array. Callbacks dispatched after releasing the mutex.
+
+**Reference**: Modeled after Go `MintHealthTracker` in `tollgate-module-basic-go/src/merchant/mint_health_tracker.go`.
+
+---
+
+### Phase 4: Health-Aware Acceptance
+
+**Files**: `main/cashu.c`
+
+Update `cashu_is_mint_accepted()` to gate on health:
+
+```c
+bool cashu_is_mint_accepted(const char *mint_url) {
+    if (!mint_url || mint_url[0] == '\0') return false;
+    const tollgate_config_t *cfg = tollgate_config_get();
+    for (int i = 0; i < cfg->accepted_mint_count; i++) {
+        if (strstr(mint_url, cfg->accepted_mints[i]) != NULL)
+            return mint_health_is_reachable(mint_url);
+    }
+    return false;
+}
+```
+
+On cold start with no internet: no mints reachable → no tokens accepted (matches Go degraded behavior). Once first probe succeeds, that mint becomes reachable and tokens are accepted.
+
+---
+
+### Phase 5: Multi-Mint Discovery Endpoint
+
+**File**: `main/tollgate_api.c`
+
+Replace single `price_per_step` tag in `api_get_discovery()` with one per reachable mint:
+
+```c
+int count;
+const mint_status_t *mints = mint_health_get_all(&count);
+for (int i = 0; i < count; i++) {
+    if (!mints[i].reachable) continue;
+    cJSON *price_tag = cJSON_CreateArray();
+    cJSON_AddItemToArray(price_tag, cJSON_CreateString("price_per_step"));
+    cJSON_AddItemToArray(price_tag, cJSON_CreateString("cashu"));
+    cJSON_AddItemToArray(price_tag, cJSON_CreateString(price_str));
+    cJSON_AddItemToArray(price_tag, cJSON_CreateString("sat"));
+    cJSON_AddItemToArray(price_tag, cJSON_CreateString(mints[i].url));
+    cJSON_AddItemToArray(price_tag, cJSON_CreateString("1"));
+    cJSON_AddItemToArray(tags, price_tag);
+}
+```
+
+If no mints are reachable, include a single tag with the primary `mint_url` as fallback (degraded mode signal).
+
+---
+
+### Phase 6: Multi-Mint Captive Portal UI
+
+**File**: `main/captive_portal.c`
+
+**Changes**:
+
+1. Replace `__MINT_URL__` template placeholder with `__MINT_LIST__`
+2. Generate HTML list of reachable mints with green dot indicators
+3. Unreachable mints shown greyed out (informative but not selectable)
+4. New API endpoint `GET /api/mints` → JSON array of mint status
+
+**Portal mint list HTML**:
+```html
+<div class="mints">
+  <div class="mints-title">SUPPORTED MINTS</div>
+  <div class="mint-item reachable">
+    <span class="mint-dot green"></span>
+    <span class="mint-url">mint.minibits.cash/Bitcoin</span>
+  </div>
+  <div class="mint-item unreachable">
+    <span class="mint-dot grey"></span>
+    <span class="mint-url">mint.coinos.io</span>
+  </div>
+</div>
+```
+
+**Auto-refresh**: JS polls `GET /api/mints` every 30s to update indicators.
+
+---
+
+### Phase 7: Multi-Mint Wallet (Nucula)
+
+**Files**: `components/nucula_lib/nucula_wallet.h`, `components/nucula_lib/nucula_wallet.cpp`
+
+**Approach**: Multi-wallet — one `cashu::Wallet` instance per mint.
+
+**Why multi-wallet vs refactoring Wallet class**:
+- Each mint has its own keysets, proofs, NVS slot — natural isolation
+- No risk of cross-mint proof confusion
+- `cashu::Wallet` class unchanged — zero regression risk
+- NVS slot allocation already supported: `Wallet(url, ctx, nvs_slot)`
+- `MAX_MINTS = 3` constant already defined in `wallet.hpp`
+
+**Internal structure**:
+```cpp
+static const int MAX_WALLETS = 4;
+static cashu::Wallet *s_wallets[MAX_WALLETS];
+static int s_wallet_count = 0;
+```
+
+**API changes**:
+
+| Old | New | Behavior |
+|-----|-----|----------|
+| `nucula_wallet_init(url)` | `nucula_wallet_init_multi(urls, count)` | Create wallet per mint |
+| `nucula_wallet_init(url)` | Keep as compat wrapper | Creates single-wallet array |
+| `nucula_wallet_receive(token)` | Same | Decode mint from token, route to correct wallet |
+| `nucula_wallet_balance()` | Same | Sum across all wallets |
+| `nucula_wallet_send(amount, ...)` | Same | Select wallet with sufficient balance |
+| `nucula_wallet_swap_all()` | Same | Swap all wallets |
+| `nucula_wallet_proof_count()` | Same | Sum across all wallets |
+
+**Token routing in `receive()`**:
+1. Decode token to extract `mint_url` from the token JSON
+2. Find matching wallet by URL
+3. Call `wallet->receive(token, proofs_out)` on that wallet
+4. If no matching wallet found, try first wallet as fallback
+
+**NVS slot mapping**:
+
+| Mint index | NVS slot | NVS keys |
+|-----------|----------|----------|
+| 0 | 0 | `url_0`, `proofs_0`, `kn_0`, `k_0_0`..`k_0_9` |
+| 1 | 1 | `url_1`, `proofs_1`, `kn_1`, `k_1_0`..`k_1_9` |
+| 2 | 2 | `url_2`, `proofs_2`, `kn_2`, `k_2_0`..`k_2_9` |
+| 3 | 3 | `url_3`, `proofs_3`, `kn_3`, `k_3_0`..`k_3_9` |
+
+---
+
+### Phase 8: Service Startup Integration
+
+**File**: `main/tollgate_main.c`
+
+**Changes to `start_services()`**:
+
+```
+1. firewall_init()
+2. session_manager_init()
+3. mint_health_init(cfg->accepted_mints, cfg->accepted_mint_count)
+4. mint_health_start()  ← async probing begins
+5. nucula_wallet_init_multi(cfg->accepted_mints, cfg->accepted_mint_count)
+6. lightning_payout_init()
+7. dns_server_start()
+8. captive_portal_start()
+9. tollgate_api_start()
+10. wifistr_publish()
+11. cvm_server_start()
+```
+
+**Health callback**: When reachable set changes, trigger wifistr re-publish to update Nostr kind 38787 event with current mint list.
+
+---
+
+## 4. Data Flow
+
+### Payment Flow (Multi-Mint)
+
+```
+Client POST cashuA token
+  │
+  ▼
+api_post_payment()
+  ├── cashu_decode_token() → extract mint_url from token
+  ├── cashu_is_mint_accepted(mint_url)
+  │     ├── Check in cfg->accepted_mints[] → config match
+  │     └── Check mint_health_is_reachable(mint_url) → health gate
+  ├── cashu_check_proof_states(mint_url, token) → POST {mint_url}/v1/checkstate
+  ├── session_create(client_ip, allotment)
+  └── nucula_wallet_receive(token_str)
+        ├── Decode token → extract mint_url
+        ├── Find wallet for that mint_url
+        └── wallet->receive(token, proofs_out)
+```
+
+### Health Probe Flow
+
+```
+mint_health_task (FreeRTOS, 5min interval)
+  │
+  for each mint in accepted_mints[]:
+  │
+  ├── GET {url}/v1/info (15s timeout)
+  │
+  ├── Success?
+  │     ├── YES → consecutive_successes++
+  │     │         if >= RECOVERY_THRESHOLD → mark reachable
+  │     └── NO  → mark unreachable, reset consecutive_successes = 0
+  │
+  └── Reachable set changed? → fire callback
+```
+
+---
+
+## 5. Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| No internet at boot | No mints reachable, no tokens accepted until probe succeeds |
+| All mints unreachable | Discovery shows primary mint (degraded), portal shows "Checking mints..." |
+| Mint goes down mid-operation | `cashu_check_proof_states` fails → 502 Bad Gateway to client |
+| Wallet init fails for one mint | Skip that mint, log error, continue with others |
+| NVS full for multi-wallet | Fallback to single wallet, log warning |
+| Probe timeout | Treat as unreachable (same as connection refused) |
+
+---
+
+## 6. Memory Budget
+
+| Component | Estimated RAM | Notes |
+|-----------|--------------|-------|
+| `mint_status_t[8]` | ~2 KB | 256-byte URLs + metadata |
+| Health probe task stack | 8 KB | HTTP client needs stack |
+| `cashu::Wallet` per mint | ~4 KB each | Keysets + proofs in NVS, not RAM |
+| 4 wallets total | ~16 KB | Within ESP32-S3 512KB SRAM budget |
+| Health task TLS | ~40 KB | esp_http_client TLS buffer |
+| **Total new overhead** | **~66 KB** | Acceptable with 512KB SRAM + 8MB PSRAM |
+
+---
+
+## 7. Testing Strategy
+
+### Unit Tests (host, `tests/unit/`)
+
+| Test File | Covers |
+|-----------|--------|
+| `test_cashu.c` | Multi-mint acceptance (config-only) |
+| `test_mint_health.c` | Health state machine, recovery, callbacks |
+| `test_config.c` | Config parsing of `accepted_mints` array |
+
+### Integration Tests (device)
+
+1. Flash to Board A, verify discovery shows multiple mints
+2. Send token from each mint, verify accepted
+3. Block one mint at firewall level, verify becomes unreachable
+4. Verify recovery after unblocking
+
+### E2E Tests (Playwright)
+
+1. Captive portal shows mint list with indicators
+2. Pay with token from mint A → success
+3. Pay with token from unreachable mint → error shown in portal
+
+---
+
+## 8. Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| TLS memory pressure with 4 wallets | Medium | High | Each wallet shares single TLS context; only probe makes concurrent HTTP |
+| NVS key namespace collision | Low | High | Use distinct `nvs_slot` per wallet (0-3) |
+| Keyset loading OOM on multiple mints | Medium | Medium | Cap keysets per wallet at `MAX_KEYSETS=10` |
+| Health probe blocks other tasks | Low | Medium | Dedicated FreeRTOS task, low priority |
+| Backward compatibility break | Low | High | `mint_url` field still works as fallback |
+
+---
+
+## 9. Backward Compatibility
+
+- Existing `config.json` with only `"mint_url"` → works (populates `accepted_mints[0]` from it)
+- Existing SPIFFS images → no change needed
+- NVS data → compatible (single wallet stays at slot 0)
+- API endpoints → same paths, discovery just has more tags
+- Captive portal → same UI flow, more mints shown
+
+---
+
+## 10. Git Worktree Strategy
+
+Multiple LLM sessions work on this repo simultaneously. To avoid conflicts:
+
+### Setup
+
+```
+# Main worktree stays on master for other sessions
+git -C /home/c03rad0r/esp32-tollgate checkout master
+
+# Dedicated worktree for this feature
+git -C /home/c03rad0r/esp32-tollgate worktree add /home/c03rad0r/esp32-tollgate-multi-mint feature/multi-mint-support
+```
+
+### Worktree Locations
+
+| Path | Branch | Purpose |
+|------|--------|---------|
+| `/home/c03rad0r/esp32-tollgate` | `master` | Main worktree, shared with other sessions |
+| `/home/c03rad0r/esp32-tollgate-multi-mint` | `feature/multi-mint-support` | This feature's isolated workspace |
+
+### Conflict Avoidance Rules
+
+| Rule | Why |
+|------|-----|
+| All edits happen in `/home/c03rad0r/esp32-tollgate-multi-mint` | Other sessions keep their own checkout untouched |
+| Push after every green test | Other sessions can `git pull` to see progress |
+| Never modify `master` directly | Merge only when feature is complete and tested |
+| `git pull --rebase` before push | Avoid merge commits if others pushed to same branch |
+
+### Cleanup (after merge)
+
+```
+git -C /home/c03rad0r/esp32-tollgate worktree remove /home/c03rad0r/esp32-tollgate-multi-mint
+```
+
+---
+
+## 11. Implementation Checklist
+
+- [x] Create feature branch `feature/multi-mint-support`
+- [x] Write design document `docs/MULTI_MINT_DESIGN.md`
+- [x] Set up git worktree at `/home/c03rad0r/esp32-tollgate-multi-mint`
+- [x] Phase 1: Config layer (`config.h`, `config.c`) — multi-mint array
+- [x] Phase 2: Multi-mint acceptance (`cashu.c`) — iterate accepted_mints
+- [x] Phase 3: Mint health tracker (`mint_health.h`, `mint_health.c`) — FreeRTOS probing task
+- [x] Phase 4: Health-aware acceptance integration — gate on reachability
+- [x] Phase 5: Multi-mint discovery endpoint (`tollgate_api.c`) — one tag per reachable mint
+- [x] Phase 6: Multi-mint captive portal UI (`captive_portal.c`) — mint list with indicators
+- [x] Phase 7: Multi-mint wallet (`nucula_wallet.h`, `nucula_wallet.cpp`) — multi-wallet approach
+- [x] Phase 8: Service startup integration (`tollgate_main.c`) — init health + multi-wallet
+- [x] Unit tests: update `test_cashu.c` for multi-mint acceptance (14/14 pass)
+- [x] Unit tests: all 256 existing tests pass
+- [x] Build verification (ESP-IDF compiles cleanly, no errors)
+- [ ] Unit tests: `test_mint_health.c` — health state machine, recovery, callbacks
+- [ ] Flash Board A and verify multi-mint discovery
+- [ ] Flash Board B and verify multi-mint discovery
+- [ ] Payment test with token from each supported mint
+- [ ] Health probe test (verify reachable/unreachable transitions)
+- [ ] Captive portal multi-mint display verification
+- [ ] Push after every passing test (blocked: Nostr relay down)
+- [ ] Merge to master