A robust, asynchronous Rust daemon designed to facilitate offline transaction settlement in humanitarian zones. It forms a resilient mesh network across POS hardware using BLE and local WiFi direct links to route encrypted payloads out of internet-blackout areas.
The project is structured as an Enterprise Cargo Workspace, splitting concerns into highly optimized and testable crates:
- mesh-crypto: Core cryptographic primitives including Ed25519 signing, BLAKE3 hashing, and ChaCha20 encryption.
- mesh-protocol: Message serialization, binary types, and the highly efficient 256-byte fragmentation protocol.
- mesh-storage: SQLite persistence schema, mempool state management, and LRU caches.
- mesh-transport: Hardware layer abstractions for Bluetooth Low Energy (BLE), LoRa, and Simulation traits.
- mesh-node: The core daemon orchestrator, gossip flood routing logic, and HTTP API settlement client.
- mesh-tui: A
ratatui-based terminal dashboard to visualize network topology and settlement states in real-time.
graph TD
POS[Offline POS Device] -->|BLE / WiFi Direct| Node[Mesh Node]
Node -->|Gossip Flood| Node2[Peer Mesh Node]
Node2 -->|Gossip Flood| Gateway[Internet-Connected Gateway]
Gateway -->|Encrypted Payload| API[HaloPay Settlement API]
API -->|Settlement ACK| Gateway
In humanitarian zones without stable internet, merchants must still accept digital USDC payments securely. However, the inability to verify balances in real-time creates a significant attack vector: offline double-spending.
This relayer solves this problem using a deterministic conflict resolution rule natively executed in the mesh layer:
- Cryptographic Signatures: Every transaction is cryptographically signed using Ed25519 by the merchant's POS device.
- Conflict Detection: If two nodes broadcast conflicting transactions (i.e. same monotonic nonce, same merchant key, but different payloads or signatures), the network mempools instantly detect the anomaly.
- Deterministic Resolution: The rule is strictly mathematical — The transaction whose Ed25519 signature produces the lowest BLAKE3 hash wins.
- Damage Control: The losing transaction is dropped entirely across the mesh, and a
SettlementFailedACK is routed back to the offending UI. - Exposure Limits: All routing guarantees are strictly mathematically bound to max damage isolation limits (e.g., a maximum of 500 USDC total offline exposure per partition).
- Language: Rust
- Core Daemon: Tokio (Async Runtime)
- Cryptography: Ed25519, BLAKE3, ChaCha20
- Database: SQLite (local persistence & mempool)
- Monitoring:
ratatui(Terminal UI) - Transport: BLE, LoRa, WiFi Direct
A standard Makefile is provided for CI and deployment commands:
# Clone the repository
git clone https://github.com/HaloPaye/halopay-mesh-relayer.git
cd halopay-mesh-relayer
# Build the workspace
make build
# Run unit tests
make test
# Lint and format code
make lint
# Cross-compile for Raspberry Pi / ARM architectures
make cross-compile-armTo evaluate the system, we provide a massive simulation harness that bootstraps virtual nodes (A, B, C, D) connected via in-memory broadcast channels, mimicking an unstable physical environment.
# Run the simulation harness and launch the TUI dashboard
make run-sim
# or: cargo run --bin mesh-simThe simulation will run various topologies: Partition & Heal, Relaying, Disappearance, Malicious Injections, and Duplicates. The live TUI dashboard will provide a real-time visualization of mempool sizes, active peers, and scrolling gossip/settlement ACKs.
Note: A systemd service file is included in init/halopay-mesh.service to deploy the daemon onto a Raspberry Pi or other POS hardware seamlessly.
| Maintainer | Contact / Telegram | Role |
|---|---|---|
| HaloPay Team | @HaloPayDev | Core Protocol Engineering |
| Lead Engineer | security@halopay.io | Security & Operations |
This project is licensed under the MIT License.