# 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) |