ReliefMesh Documentation

A comprehensive guide to the decentralized architecture, privacy-preserving zero-knowledge protocols, and Soroban smart contracts powering ReliefMesh.

1. System Overview

ReliefMesh is a decentralized financial router designed to bypass corrupt bureaucratic bottlenecks during natural disasters. Instead of sending pallets of physical cash or routing funds through opaque central banks, relief agencies (Admins) deposit stablecoins (USDC) into an on-chain Relief Pool.

From the Command Center Dashboard, Admins can route funds directly to affected victims. Victims withdraw these funds as local physical fiat from established, vetted Shopkeepers (local grocers or merchants). Every single transaction is settled on the Stellar ledger in ~4 seconds at a fraction of a cent.

2. Smart Contract Architecture

ReliefPool (Vault)

Acts as the master escrow. Organizations fund the pool. When an admin executes `distribute_aid`, the Pool locks USDC for the victim's immediate claim.

VictimRegistry (Identity)

Stores cryptographic hashes of victim identities (Zero-Knowledge Commitments). No human-readable PII (Names, Phone Numbers, ID cards) is ever committed to the ledger, protecting vulnerable refugees while maintaining Sybil resistance.

ShopkeeperRegistry (Agents)

Maintains the decentralized network of verified cash-out points. Tracks their total daily liquidity limits, processed volume, and dispute counts. Shopkeepers act as the "last mile" to convert stablecoins into physical cash.

ClawbackController (Governance)

Empowered by Stellar's Native Clawback Asset feature. If a shopkeeper defrauds a victim or attempts to charge exorbitant fees ("price gouging"), the Admin can execute an irrevocable clawback, ripping the stolen USDC out of the malicious shopkeeper's balance and restoring it to the Relief Pool.

3. Data Integrity & ZK Privacy

Public ledgers are immutable, which makes them dangerous for storing refugee and victim details. If a malicious actor knew an individual just received $5,000 in aid, it poses a severe physical security risk to the victim.

Client-Side Hashing: Before data leaves the browser, Identity & Phone Numbers are hashed via `crypto.subtle.digest(SHA-256)`.
On-Chain Verification: The smart contract only stores the `identity_hash` string. Claim generation simply requires the user to prove they know the pre-image.
Anonymous Routing: When "Distribute Aid" is clicked, USDC is technically credited to a mathematically derived Victim ID, completely isolated from real-world identities.