From bf8e095b94fe500a9c35d7f2f616eb85569dbe5e Mon Sep 17 00:00:00 2001 From: Your Name Date: Sat, 23 May 2026 22:09:57 +0530 Subject: Phase 10a v1.2.0: MIT license, metadata update, full API docs - Bump idf_component.yml to v1.2.0 with MIT license, targets, tags - Add LICENSE (MIT) for IDF Component Registry compatibility - Update CHANGELOG.md with v1.2.0 entries (portal, stratum_client, mint_health, client) - Update README.md with all 13 modules documented, API reference table - Add REMAINING_PLAN.md with full execution plan and checklist - 25 unit tests pass, ESP-IDF build passes --- components/tollgate_core/README.md | 74 ++++++++++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 11 deletions(-) (limited to 'components/tollgate_core/README.md') diff --git a/components/tollgate_core/README.md b/components/tollgate_core/README.md index d83d634..57bab4d 100644 --- a/components/tollgate_core/README.md +++ b/components/tollgate_core/README.md @@ -4,14 +4,27 @@ ESP-IDF component providing paid WiFi hotspot logic with Cashu e-cash payments. ## Features -- **Session management** — time-based and bytes-based sessions with auto-expiry -- **Cashu token processing** — decode Cashu e-cash tokens, calculate allotments, multi-mint support -- **Per-client firewall** — whitelist-based NAT filtering with sandbox mode -- **DNS server** — per-client DNS hijack/forward with DoT rejection -- **Mining payment** — Stratum share tracking, hashprice calculation, difficulty conversion -- **Stratum proxy** — transparent TCP proxy for mining traffic with job management -- **Beacon price** — WiFi vendor IE construction for price/mint/geohash advertising -- **Market scanner** — discover and compare nearby TollGate prices +### Session & Payment +- **Session management** (`tollgate_core_session`) — time-based and bytes-based sessions with auto-expiry, extension, and revocation +- **Cashu token processing** (`tollgate_core_cashu`) — decode Cashu e-cash tokens, calculate allotments, multi-mint support, proof state checking +- **Per-client firewall** (`tollgate_core_firewall`) — whitelist-based NAT filtering with sandbox mode for unauthenticated clients + +### Network +- **DNS server** (`tollgate_core_dns`) — per-client DNS hijack/forward with DoT rejection +- **Stratum proxy** (`tollgate_core_stratum_proxy`) — transparent TCP proxy for mining traffic with job management + +### Mining +- **Mining payment** (`tollgate_core_mining`) — Stratum share tracking, hashprice calculation, difficulty conversion, share-to-allotment mapping +- **Stratum client** (`tollgate_core_stratum_client`) — Stratum V1 JSON protocol parsing (mining.notify, mining.set_difficulty), message construction (subscribe, authorize, submit) + +### Discovery & Market +- **Beacon price** (`tollgate_core_beacon`) — WiFi vendor IE construction for price/mint/geohash advertising +- **Market scanner** (`tollgate_core_market`) — discover and compare nearby TollGate prices via vendor IEs +- **Mint health** (`tollgate_core_mint_health`) — mint health state tracking with recovery threshold, reachable/unreachable transitions + +### Portal & Client +- **Portal rendering** (`tollgate_core_portal`) — HTML template rendering with multi-key substitution, usage calculation, captive URI detection +- **TollGate client** (`tollgate_core_client`) — upstream TollGate discovery JSON parsing, session/usage response parsing, renewal threshold logic, price comparison ## Integration @@ -26,7 +39,15 @@ static tollgate_platform_t platform = { .get_mint_url = my_get_mint_url, .get_metric = my_get_metric, .get_time_ms = my_get_time_ms, - // ... other callbacks + .spend_proofs = my_spend_proofs, + .get_stratum_url = my_get_stratum_url, + .get_stratum_port = my_get_stratum_port, + .get_stratum_user = my_get_stratum_user, + .get_stratum_pass = my_get_stratum_pass, + .get_mining_port = my_get_mining_port, + .get_hashprice_sats_per_ghs_day = my_get_hashprice, + .on_share_accepted = my_on_share_accepted, + .get_hashrate = my_get_hashrate, }; ``` @@ -54,9 +75,40 @@ tollgate_core_process_payment(client_ip, cashu_token_string); Call `tollgate_core_tick()` periodically (e.g., every second) to expire sessions. +### 5. Use sub-modules directly + +```c +#include "tollgate_core_portal.h" +char *html = tollgate_core_portal_render(template, subs, nsubs); + +#include "tollgate_core_stratum_client.h" +tollgate_core_stratum_build_subscribe(buf, size, req_id); + +#include "tollgate_core_mint_health.h" +tollgate_core_mint_health_update(&state, idx, probe_ok, status, err, time); + +#include "tollgate_core_client.h" +bool renew = tollgate_core_client_should_renew(remaining, allotment, threshold); +``` + ## API Reference -See `include/tollgate_core.h` for the public API and `include/tollgate_platform.h` for platform callbacks. +| Header | Description | +|--------|-------------| +| `tollgate_core.h` | Main API: init, process_payment, tick, status queries | +| `tollgate_platform.h` | Platform callback struct definition | +| `tollgate_core_session.h` | Session create/find/extend/revoke | +| `tollgate_core_cashu.h` | Token decode, checkstate, allotment | +| `tollgate_core_firewall.h` | Client grant/revoke, sandbox ports | +| `tollgate_core_dns.h` | DNS start/stop | +| `tollgate_core_mining.h` | Share tracking, hashprice, difficulty | +| `tollgate_core_stratum_proxy.h` | Proxy init/stop, job management | +| `tollgate_core_beacon.h` | IE construction, mint/npub hashing | +| `tollgate_core_market.h` | Market table, price comparison | +| `tollgate_core_portal.h` | Template rendering, usage calc, captive URIs | +| `tollgate_core_stratum_client.h` | Stratum V1 protocol parsing | +| `tollgate_core_mint_health.h` | Mint health state tracking | +| `tollgate_core_client.h` | Discovery/session parsing, renewal logic | ## Dependencies @@ -68,4 +120,4 @@ See `include/tollgate_core.h` for the public API and `include/tollgate_platform. ## License -Proprietary — see repository for details. +MIT — see [LICENSE](LICENSE). -- cgit v1.2.3