Off-grid gateway that bridges Reticulum radio mesh networks with Web3 transaction broadcasting, backed by a cloud credit system powered by Supabase and Stripe.
⚠️ PROTOTYPE — NOT FIELD VALIDATED: This system has been designed and documented but has not yet been tested in a live deployment. Claims about offline resilience, sync reliability, transaction throughput, and radio range are architectural expectations, not measured results. Do not deploy in any operational humanitarian environment until the full end-to-end flow has been validated in controlled testing, security has been independently audited, and load behaviour under real radio mesh conditions has been measured. All performance figures and quality metrics in this document are targets, not guarantees.
Field operators in connectivity-denied environments carry Reticulum-capable radio devices paired with a smartphone. They send signed blockchain transactions over the radio mesh to a gateway node running on a Raspberry Pi. The gateway operates as a store-and-forward asynchronous broker — the radio-facing side and the blockchain-facing side are fully decoupled, so a slow satellite link or a multi-minute block confirmation time never stalls the LoRa radio listener.
Transaction lifecycle:
- Incoming radio packet is authenticated against the local credit ledger by Reticulum hash
- One credit is atomically deducted
- An immediate
RECEIVED:acknowledgement is transmitted back over radio — the field device knows the gateway has custody - The transaction is queued for a background web3-worker thread, which broadcasts it to an Ethereum-compatible RPC endpoint with exponential backoff
- The tx_id is persisted to a local mailbox table — survives gateway restarts
- A background watcher thread polls the blockchain every 30 seconds for on-chain confirmation
- Once confirmed (or reverted), a final
CONFIRMED:orFAILED:receipt is delivered back over radio - If broadcast fails due to a network error the credit is auto-refunded; fatal user errors (insufficient funds, nonce too low) are not refunded
Credits are sold via a Telegram Mini App → Stripe payment flow. Confirmed payments are recorded in Supabase (PostgreSQL). A cron job on the Pi syncs the cloud ledger to a local SQLite cache every 5 minutes using delta-math — repeated syncs never inflate balances. The gateway continues to operate during satellite or internet outages, pushing locally-spent credits back to the cloud on reconnection.
A Telegram alerting module notifies ops staff of critical crashes, stale transactions, sync failures, and gateway restarts — so field technicians never need to check logs manually.
| Document | Description |
|---|---|
| WHY.md | The problem this system addresses, what has been tried, and the gap it fills |
| ARCHITECTURE.md | System diagrams: hardware stack, async data flow, credit flow, alerting flow |
| SYSTEM_FILES.md | Every file in the project, what it does, and where it runs |
| INSTALLATION.md | Prerequisites and step-by-step setup for all components |
| CHECKLIST.md | Ordered first-deployment checklist |
| SECURITY.md | Secrets management, RLS policies, and regulatory positioning |
| OPERATIONS.md | Day-to-day usage, alert reference, and troubleshooting |
| TELEMETRY.md | Six Sigma telemetry pipeline and performance metrics |
humanitarian_mesh_gateway/
│
├── README.md
├── LICENSE.md
├── .gitignore
│
├── docs/
│ ├── images/
│ │ └── system-overview.png
│ ├── WHY.md
│ ├── ARCHITECTURE.md
│ ├── SYSTEM_FILES.md
│ ├── INSTALLATION.md
│ ├── CHECKLIST.md
│ ├── SECURITY.md
│ ├── OPERATIONS.md
│ └── TELEMETRY.md
│
├── gateway/
│ ├── main_bot.py # Core gateway process — async pipe, dispatcher, watcher
│ ├── database_manager.py # Thread-safe SQLite — credit ledger + pending tx mailbox
│ ├── web3_bridge.py # Blockchain broadcast — validation, backoff, mempool handling
│ ├── cloud_sync.py # Bi-directional Supabase sync — delta-math, push deductions
│ ├── telegram_alerter.py # Ops alerting — crash, stale tx, sync failures, startup
│ ├── config.example.json # Committed template — copy to config.json and fill in values
│ ├── gateway.service # systemd unit — auto-start, auto-restart on crash
│ └── requirements.txt # Exact version-pinned Python dependencies
│
├── supabase/
│ ├── functions/
│ │ ├── stripe-webhook.ts # Webhook handler — signature verification, idempotency
│ │ └── create-checkout.ts # Checkout session creator — auth guard, server-side pricing
│ └── migrations/
│ ├── cloud_subscribers.sql
│ └── processed_stripe_events_migration.sql
│
├── frontend/
│ └── index.html # Telegram Mini App — credit purchase UI
│
└── ops/
└── system_performance.sql
For questions, deployment inquiries, partnership opportunities, or to report issues, please open a GitHub issue in this repository or reach out via the contact details below.
This project welcomes collaboration from humanitarian organisations, NGOs, research institutions, and developers interested in extending financial access to off-grid communities.
- GitHub Issues: Open an issue
- Email: humanitarianmeshgateway@duck.com
This project is licensed under the PolyForm Strict License 1.0.0. Please read the LICENSE file for details.
Built on Reticulum Network Stack · Supabase · Stripe · web3.py