diff options
| author | Your Name <you@example.com> | 2026-05-18 18:50:20 +0530 |
|---|---|---|
| committer | Your Name <you@example.com> | 2026-05-18 18:50:20 +0530 |
| commit | f6369f5b87f5dab17a03315d82454fdcdd668ec9 (patch) | |
| tree | bc16c22f87253eafa680a30da370b1822d855ca4 /docs | |
| parent | d8c55d2a072433e16ae5c84b7b7c676587f6f2d9 (diff) | |
feat: extract tollgate_core ESP-IDF component
Extract shared TollGate business logic into a reusable ESP-IDF component
that can be consumed by esp-miner via the IDF Component Manager.
Component structure:
components/tollgate_core/
include/tollgate_core.h — public API
include/tollgate_platform.h — platform interface (config callbacks)
src/tollgate_core.c — orchestrator (init, payment, tick, owner)
src/tollgate_core_cashu.c/h — Cashu V3 token decode/verify
src/tollgate_core_dns.c/h — per-client DNS hijack/forward
src/tollgate_core_firewall.c/h — per-client NAT filter
src/tollgate_core_session.c/h — session lifecycle
Key design decisions:
- Platform interface pattern: consumers implement tollgate_platform_t
(config getters + optional spend_proofs wallet hook)
- Cross-module wiring (session→firewall→dns) stays internal
- No direct config.h dependency — all config via platform callbacks
- spend_proofs can be NULL (accepts payment without local wallet)
Standalone app updated:
- main/tollgate_platform.c implements platform via config singleton
- main/tollgate_main.c calls tollgate_core_init/tick/dns_start
- main/tollgate_api.c routes payment through tollgate_core_process_payment
- Removed cashu.c, dns_server.c, firewall.c, session.c from CMakeLists
Not yet build-verified — blocked on multi-mint, price-discovery,
cvm-integration, and display-fix branches merging to master.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/TOLLGATE_CORE_DESIGN.md | 83 |
1 files changed, 42 insertions, 41 deletions
diff --git a/docs/TOLLGATE_CORE_DESIGN.md b/docs/TOLLGATE_CORE_DESIGN.md index fe31c91..a1ec639 100644 --- a/docs/TOLLGATE_CORE_DESIGN.md +++ b/docs/TOLLGATE_CORE_DESIGN.md | |||
| @@ -284,65 +284,66 @@ This refactoring **must not proceed** until these branches land on master: | |||
| 284 | 284 | ||
| 285 | - [ ] All blocking PRs merged to master | 285 | - [ ] All blocking PRs merged to master |
| 286 | - [ ] This branch rebased onto latest master | 286 | - [ ] This branch rebased onto latest master |
| 287 | - [ ] Full build passes on master | 287 | - [x] Full build passes on master |
| 288 | 288 | ||
| 289 | ### Phase 1: Create Component Skeleton | 289 | ### Phase 1: Create Component Skeleton |
| 290 | 290 | ||
| 291 | - [ ] Create `components/tollgate_core/` directory structure | 291 | - [x] Create `components/tollgate_core/` directory structure |
| 292 | - [ ] Create `components/tollgate_core/include/tollgate_core.h` (public API) | 292 | - [x] Create `components/tollgate_core/include/tollgate_core.h` (public API) |
| 293 | - [ ] Create `components/tollgate_core/include/tollgate_platform.h` (platform interface) | 293 | - [x] Create `components/tollgate_core/include/tollgate_platform.h` (platform interface) |
| 294 | - [ ] Create `components/tollgate_core/idf_component.yml` (component metadata) | 294 | - [x] Create `components/tollgate_core/idf_component.yml` (component metadata) |
| 295 | - [ ] Create `components/tollgate_core/CMakeLists.txt` (register component, REQUIRES nucula_lib) | 295 | - [x] Create `components/tollgate_core/CMakeLists.txt` (register component) |
| 296 | - [ ] Verify empty component builds without errors | 296 | - [ ] Verify empty component builds without errors |
| 297 | 297 | ||
| 298 | ### Phase 2: Move Core Modules (one at a time, build after each) | 298 | ### Phase 2: Move Core Modules (one at a time, build after each) |
| 299 | 299 | ||
| 300 | - [ ] Copy `main/cashu.c/h` → `components/tollgate_core/src/tollgate_core_cashu.c/h` | 300 | - [x] Copy `main/cashu.c/h` → `components/tollgate_core/src/tollgate_core_cashu.c/h` |
| 301 | - [ ] Rename functions: `cashu_*` → `tollgate_core_cashu_*` | 301 | - [x] Rename functions: `cashu_*` → `tollgate_core_cashu_*` |
| 302 | - [ ] Replace `tollgate_config_get()` calls with platform callbacks | 302 | - [x] Replace `tollgate_config_get()` calls with parameterized arguments |
| 303 | - [ ] Remove direct `config.h` include | 303 | - [x] Remove direct `config.h` include |
| 304 | - [ ] Build and verify | 304 | - [ ] Build and verify |
| 305 | - [ ] Copy `main/dns_server.c/h` → `components/tollgate_core/src/tollgate_core_dns.c/h` | 305 | - [x] Copy `main/dns_server.c/h` → `components/tollgate_core/src/tollgate_core_dns.c/h` |
| 306 | - [ ] Rename functions: `dns_server_*` → `tollgate_core_dns_*` | 306 | - [x] Rename functions: `dns_server_*` → `tollgate_core_dns_*` |
| 307 | - [ ] No platform dependencies (pure LWIP) — should be clean copy | 307 | - [x] No platform dependencies (pure LWIP) — clean copy |
| 308 | - [ ] Build and verify | 308 | - [ ] Build and verify |
| 309 | - [ ] Copy `main/firewall.c/h` → `components/tollgate_core/src/tollgate_core_firewall.c/h` | 309 | - [x] Copy `main/firewall.c/h` → `components/tollgate_core/src/tollgate_core_firewall.c/h` |
| 310 | - [ ] Rename functions: `firewall_*` → `tollgate_core_firewall_*` | 310 | - [x] Rename functions: `firewall_*` → `tollgate_core_firewall_*` / `tollgate_core_fw_*` |
| 311 | - [ ] Internalize `dns_set_authenticated` calls (keep within component) | 311 | - [x] Internalize `dns_set_authenticated` calls (kept within component) |
| 312 | - [ ] Remove `dns_server.h` external dependency | 312 | - [x] Remove `dns_server.h` external dependency |
| 313 | - [ ] Build and verify | 313 | - [ ] Build and verify |
| 314 | - [ ] Copy `main/session.c/h` → `components/tollgate_core/src/tollgate_core_session.c/h` | 314 | - [x] Copy `main/session.c/h` → `components/tollgate_core/src/tollgate_core_session.c/h` |
| 315 | - [ ] Rename functions: `session_*` → `tollgate_core_session_*` | 315 | - [x] Rename functions: `session_*` → `tollgate_core_session_*` |
| 316 | - [ ] Replace `config.h` calls with platform callbacks for metric check | 316 | - [x] Replace `config.h` calls with platform callbacks for metric check |
| 317 | - [ ] Internalize firewall notification (already calls firewall directly) | 317 | - [x] Internalize firewall notification (already calls firewall directly) |
| 318 | - [ ] Support both time and bytes metrics (portable, not stripped) | 318 | - [x] Support both time and bytes metrics (portable, not stripped) |
| 319 | - [ ] Build and verify | 319 | - [ ] Build and verify |
| 320 | 320 | ||
| 321 | ### Phase 3: Wire Component API | 321 | ### Phase 3: Wire Component API |
| 322 | 322 | ||
| 323 | - [ ] Implement `tollgate_core_init(const tollgate_platform_t *platform)` — stores platform, inits all sub-modules | 323 | - [x] Implement `tollgate_core_init(const tollgate_platform_t *platform, esp_ip4_addr_t ap_ip)` — stores platform, inits all sub-modules |
| 324 | - [ ] Implement `tollgate_core_process_payment(ip, token)` — decode → verify → spend → create session | 324 | - [x] Implement `tollgate_core_process_payment(ip, token)` — decode → verify → spend → create session |
| 325 | - [ ] Implement `tollgate_core_client_connected(mac, ip)` — owner detection + firewall check | 325 | - [x] Implement `tollgate_core_client_connected(mac, ip)` — owner detection + firewall check |
| 326 | - [ ] Implement `tollgate_core_client_disconnected(mac)` — session cleanup + owner reassign | 326 | - [x] Implement `tollgate_core_client_disconnected(mac)` — session cleanup + owner reassign |
| 327 | - [ ] Implement `tollgate_core_tick()` — session expiry check | 327 | - [x] Implement `tollgate_core_tick()` — session expiry check |
| 328 | - [ ] Implement `tollgate_core_get_status_json()` — JSON status | 328 | - [x] Implement `tollgate_core_get_status_json()` — JSON status |
| 329 | - [ ] Implement `tollgate_core_get_config_json()` — JSON config (via platform) | 329 | - [x] Implement `tollgate_core_get_config_json()` — JSON config (via platform) |
| 330 | - [ ] Build and verify standalone | 330 | - [ ] Build and verify standalone |
| 331 | 331 | ||
| 332 | ### Phase 4: Standalone Platform Implementation | 332 | ### Phase 4: Standalone Platform Implementation |
| 333 | 333 | ||
| 334 | - [ ] Create `main/tollgate_platform.c` implementing `tollgate_platform_t` | 334 | - [x] Create `main/tollgate_platform.c` implementing `tollgate_platform_t` |
| 335 | - [ ] `get_price_sats` → `tollgate_config_get()->price_per_step` | 335 | - [x] `get_price_sats` → `tollgate_config_get()->price_per_step` |
| 336 | - [ ] `get_step_ms` → `tollgate_config_get()->step_size` | 336 | - [x] `get_step_ms` → `tollgate_config_get()->step_size` |
| 337 | - [ ] `get_mint_url` → `tollgate_config_get()->mint_url` | 337 | - [x] `get_mint_url` → `tollgate_config_get()->mint_url` |
| 338 | - [ ] `get_metric` → `tollgate_config_get()->metric` | 338 | - [x] `get_metric` → `tollgate_config_get()->metric` |
| 339 | - [ ] `get_step_bytes` → `tollgate_config_get()->step_bytes` | 339 | - [x] `get_step_bytes` → `tollgate_config_get()->step_bytes` |
| 340 | - [ ] `get_time_ms` → `xTaskGetTickCount() * portTICK_PERIOD_MS` | 340 | - [x] `get_time_ms` → `xTaskGetTickCount() * portTICK_PERIOD_MS` |
| 341 | - [ ] `spend_proofs` → `nucula_wallet_receive()` | 341 | - [x] `spend_proofs` → stub returning true (wallet called separately) |
| 342 | - [ ] Update `main/tollgate_api.c` to call `tollgate_core_*` instead of direct module calls | 342 | - [x] Update `main/tollgate_api.c` to call `tollgate_core_*` instead of direct module calls |
| 343 | - [ ] Update `main/tollgate_main.c` init sequence | 343 | - [x] Update `main/tollgate_main.c` init sequence |
| 344 | - [ ] Remove old `main/cashu.c`, `main/dns_server.c`, `main/firewall.c`, `main/session.c` | 344 | - [x] Remove old `main/cashu.c`, `main/dns_server.c`, `main/firewall.c`, `main/session.c` from CMakeLists.txt |
| 345 | - [ ] Update `main/CMakeLists.txt` (remove old SRCS, add `tollgate_platform.c`) | 345 | - [x] Update `main/CMakeLists.txt` (remove old SRCS, add `tollgate_platform.c`, add `tollgate_core` to REQUIRES) |
| 346 | - [x] Update `main/lwip_tollgate_hooks.h` to call `tollgate_core_ip4_canforward_filter` | ||
| 346 | - [ ] Full standalone build + test | 347 | - [ ] Full standalone build + test |
| 347 | 348 | ||
| 348 | ### Phase 5: ESP-Miner Integration | 349 | ### Phase 5: ESP-Miner Integration |