Spaces:
Running
Running
| # Architecture | |
| ## Actors | |
| - **Issuer**: a company issuing a stablecoin/token on Stellar (e.g. a MoneyGram-style MGUSD issuer, an anchor, an RWA platform). | |
| - **Compliance Officer**: a non-technical staff member at the issuer who configures rules via the dashboard. | |
| - **User**: a wallet holder transacting in the issuer's token. | |
| - **Regulator/Auditor**: reviews aggregate compliance evidence without seeing individual user data. | |
| ## Data flow | |
| 1. **Rule configuration**: Compliance Officer uses the no-code dashboard to define rules (e.g. "block sanctioned wallets", "cap daily transfer at $10,000", "require KYC tier 2 above $1,000"). Rules are stored and compiled into circuit parameters. | |
| 2. **Sanctions/KYC data ingestion**: The oracle service periodically pulls a sanctions/PEP list (simulated here) and KYC attestations, builds a Merkle tree, and publishes the current Merkle root on-chain (or to a location the contract can read). | |
| 3. **Proof generation**: When a User initiates a transfer, their wallet (or a client-side proving service) generates a zero-knowledge proof that: | |
| - their address is NOT in the current sanctions Merkle tree (non-membership proof), AND | |
| - they hold a valid KYC credential of the required tier, AND | |
| - the transaction amount is within their configured limit. | |
| None of the underlying identity data or exact balance is revealed — only that the proof is valid. | |
| 4. **On-chain verification**: The Soroban compliance hook contract (SEP-0057-style) verifies the proof using Stellar's native pairing-check host functions before allowing the token transfer to proceed. | |
| 5. **Audit reporting**: The dashboard aggregates verification events (pass/fail counts, thresholds triggered) into a regulator-facing report — without ever exposing which specific user triggered which event. | |
| ## Why Stellar specifically | |
| - **Protocol 25 "X-Ray"**: native BN254 pairing operations + Poseidon hashing make ZK proof verification a first-class, low-level operation instead of an expensive custom implementation. | |
| - **SLP-4**: cut non-refundable Soroban resource costs and roughly halved/quartered typical invocation costs, making per-transaction ZK verification commercially viable. | |
| - **Anchor network**: 170+ country cash-in/cash-out network means KYC/compliance attestations can eventually be tied to real-world onboarding points, not just crypto-native wallets. | |
| ## Components in this repo, mapped to the flow above | |
| | Step | Component | | |
| |------|-----------| | |
| | Rule configuration | `dashboard/index.html` (no-code rule builder) | | |
| | Sanctions ingestion + Merkle root | `oracle/sanctions-feed.js` | | |
| | Proof generation (spec) | `circuits/sanctions_proof/CIRCUIT_SPEC.md` | | |
| | On-chain verification | `contracts/compliance_hook/src/lib.rs` | | |
| | Audit reporting | `dashboard/index.html` (audit tab) | | |