╔══════════════════════════════════════════════════════╗
║                                                      ║
║    ██████╗ ██████╗  █████╗  ██████╗ ██╗   ██╗███████╗║
║   ██╔═══██╗██╔══██╗██╔══██╗██╔═══██╗██║   ██║██╔════╝║
║   ██║   ██║██████╔╝███████║██║   ██║██║   ██║█████╗  ║
║   ██║   ██║██╔═══╝ ██╔══██║██║▄▄ ██║██║   ██║██╔══╝  ║
║   ╚██████╔╝██║     ██║  ██║╚██████╔╝╚██████╔╝███████╗║
║    ╚═════╝ ╚═╝     ╚═╝  ╚═╝ ╚══▀▀═╝  ╚═════╝ ╚══════╝║
║                                                      ║
╚══════════════════════════════════════════════════════╝

Private payments. Provable reputation. Zero exposure.

Stealth addresses and on-chain ZK reputation on Stellar (Soroban + Freighter).

GitHub

---

Overview

Opaque is an open protocol for unlinkable payments and proof-backed reputation on Stellar. It combines:

1. Stealth payments (DKSAP) — Each receive uses a fresh, one-time Stellar account derived from a published meta-address. Senders pay XLM to that address; only the recipient can discover and sweep funds.
2. Programmable Stealth Reputation (PSR) — Issuers register schemas and attest to stealth identities (hashed, not wallet-linked). Holders prove traits with Groth16 ZK proofs verified on Soroban.

The reference wallet runs in the browser: Freighter for signing, WASM for scanning announcements, snarkjs for proofs.

---

How it works

Stealth payments

Opaque implements the Dual-Key Stealth Address Protocol (DKSAP) (EIP-5564 / ERC-6538 compatible cryptography on secp256k1):

Recipient                              Sender
─────────                              ──────
Publishes meta-address  V ∥ S
                                       Ephemeral key r, shared secret, view tag
                                       Stealth pubkey P → Stellar account (Ed25519)
                                       Pays XLM + announces on stealth-announcer
Scanner (WASM) filters by view tag, derives matching stealth keys, sweeps to main wallet

Stealth Stellar accounts are derived deterministically from the stealth secp256k1 point (opaque-stellar-stealth-v1 domain separation).

Private reputation

• Schema registry — Field layouts and authorities on Soroban.
• Attestation engine — Credentials bound to keccak256(stealth_address), not a public wallet.
• Groth16 verifier — BN254 pairing via Soroban crypto primitives.
• Reputation verifier — Merkle root checks, nullifiers, and proof verification.

---

Repository map

Path	Contents
frontend/	React / TypeScript wallet UI (Freighter, send, receive, scan, reputation)
contracts/	Soroban contracts: registry, announcer, schema registry, attestation, Groth16, reputation
scanner/	Rust → WASM: DKSAP engine, view-tag filter, attestation discovery
circuits/	Circom Groth16 circuit for stealth attestation proofs

---

Soroban contracts

Contract	Role
stealth-registry	Map Stellar account → stealth meta-address
stealth-announcer	On-chain announcements (ephemeral key, view tag, metadata)
schema-registry	Register attestation schemas
attestation-engine-v2	Issue / revoke attestations
groth16-verifier	Verify Groth16 proofs (BN254)
reputation-verifier	PSR verification + nullifiers

Deploy with the Stellar CLI, then record contract IDs in the canonical manifest at deployments/v1/testnet.json (see deployments/README.md). Optional VITE_<NETWORK>_* overrides in frontend/.env are for local dev only.

---

Running locally

Prerequisites

• Rust (stable)
• Stellar CLI
• Node.js 18+
• wasm-pack (scanner WASM)
• Freighter browser extension

1. Clone

git clone https://github.com/collinsadi/opaque.git
cd opaque

2. Build contracts

stellar contract build
# Deploy to testnet and note contract IDs

3. Build scanner (WASM)

cd scanner
wasm-pack build --target web --out-dir ../frontend/public/pkg
cd ..

4. Frontend

cd frontend
cp .env.example .env
# Edit VITE_STELLAR_NETWORK; contract IDs come from deployments/v1/testnet.json
npm install
npm run dev

Open http://localhost:5173, connect Freighter on testnet.

5. Circuits (optional)

Only if you change the attestation circuit:

cd circuits/v2
npm install
npm run build

---

Environment variables

See frontend/.env.example and deployments/README.md. Key settings:

• VITE_STELLAR_NETWORK — testnet | mainnet | futurenet | local
• VITE_STELLAR_RPC_URL / VITE_STELLAR_HORIZON_URL (optional; manifest defaults)
• Canonical contract IDs — deployments/v1/testnet.json / deployments/v1/mainnet.json
• Release evidence — RELEASE_NOTES.md

---

Cryptographic stack

Layer	Primitive	Purpose
Stealth keys	secp256k1 ECDH	DKSAP shared secret
Address hash	Keccak-256	Cross-chain stealth identifier (EVM-compatible hex)
Stellar account	Ed25519 from hashed stealth point	One-time receive accounts
View tag	1 byte from shared secret	Fast announcement filtering
ZK	Groth16 (BN254)	In-browser reputation proofs
On-chain verify	Soroban BN254	Pairing verification in contracts
Nullifiers	Poseidon	Replay resistance

---

Standards & cross-chain

Opaque follows the same DKSAP layout as the Ethereum Opaque implementation:

• EIP-5564 — Stealth addresses
• ERC-6538 — Stealth meta-address registry

Meta-addresses and scanner logic are compatible across chains; settlement layer is Stellar (XLM + Soroban).

Disclaimer: Experimental software. Read DISCLAIMER.md before using with real funds.

---

License

MIT — Built in public by Collins Adi.

Every transaction deserves the right to be private.