Leveraging Psy Protocol's zero-knowledge proofs for decentralized messaging with absolute privacy.
Note: This project is an MVP prototype. ZK proof generation and Poseidon2 hashing are simulated with drop-in replacements ready for production Psy Protocol integration.
ZeroTrace main interface - Clean, modern messaging UI with identity management
- Rust (latest stable version) - Install Rust
- Modern web browser (Chrome, Firefox, Edge)
# Clone the repository
git clone https://github.com/0xali3n/psy
cd psy
# Build the project
cargo build
# Run the server
cargo run --bin serverOpen browser: http://127.0.0.1:8080
Server running on http://127.0.0.1:8080 - Actix-web backend with API endpoints
Creating a new ED25519 identity - Identity hash and public key generated
- Browser A: Create identity, copy hash
Connecting two users via QR code or identity hash - Secure peer-to-peer connection
- Browser B: Create identity, connect using Browser A's hash
End-to-end encrypted messaging with ZK proof status indicators
- Send Message: Type message, verify ZK proof status
- Verify: Check console (F12) and server terminal
User settings and technical details - Identity keys, CSTATE root, and proof information
✔ Built in Rust - Full backend in Rust (Actix-web, Tokio) with type-safe, high-performance code
✔ Implements Psy Concepts - Identity (SDKey-style ED25519), CSTATE (Merkle tree state), Commitments (Poseidon2-style), CFC proofs (Psy Protocol format)
✔ Scalable Architecture - Stateless server design; server instances can horizontally scale behind a load balancer. Merkle tree state enables efficient sync.
✔ Privacy-by-Design - E2E encryption (XChaCha20-Poly1305) + ZK-style state transitions. Server never sees plaintext.
✔ Clear Migration Path - Trait-based architecture ready for Psy Protocol testnet integration (plonky2-hwa, Realm, UCON, DA Miner)
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ ZeroTrace System Architecture │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ CLIENT LAYER (Browser) │ │
│ ├─────────────────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Frontend │ │ Identity │ │ Encryption │ │ Local │ │ │
│ │ │ (HTML/JS) │ │ Manager │ │ Engine │ │ Storage │ │ │
│ │ │ │ │ (ED25519) │ │(XChaCha20) │ │(localStorage)│ │ │
│ │ │ - UI/UX │ │ - Keypair │ │ - Encrypt │ │ - Keys │ │ │
│ │ │ - QR Code │ │ - Hash │ │ - Decrypt │ │ - Identity │ │ │
│ │ │ - Chat UI │ │ - Sign │ │ - Nonce │ │ - State │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────────────┘ │ │
│ │ │ │ │ │ │
│ │ └──────────────────┴──────────────────┘ │ │
│ │ │ │ │
│ │ │ HTTP/JSON │ │
│ └──────────────────────────────┼────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ API SERVER LAYER (Rust/Actix-web) │ │
│ ├─────────────────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ HTTP │ │ Message │ │ Identity │ │ ZK Proof │ │ │
│ │ │ Router │ │ Store │ │ State │ │ Engine │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ - /send │ │ - Messages │ │ - Public │ │ - CFC Proof │ │ │
│ │ │ - /read │ │ - Threads │ │ Keys │ │ - Verify │ │ │
│ │ │ - /identity │ │ - CSTATE │ │ - Hashes │ │ - EndCap │ │ │
│ │ │ - /cstate │ │ - Keys │ │ - Nonces │ │ - SimProver │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ │ │ │ │ │ │ │
│ │ └──────────────────┴──────────────────┴──────────────────┘ │ │
│ │ │ │ │
│ │ │ Internal Calls │ │
│ └──────────────────────────────┼────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────┴─────────────────────────────────────────────────────┐ │
│ │ CRYPTOGRAPHIC SERVICES LAYER │ │
│ ├─────────────────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ │ Encryption │ │ Commitments │ │ State │ │ │
│ │ │ Service │ │ Service │ │ Management │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ XChaCha20- │ │ Poseidon2-style │ │ Merkle Tree │ │ │
│ │ │ Poly1305 │ │ Hashing │ │ Construction │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ - 256-bit key │ │ - Message │ │ - CSTATE Root │ │ │
│ │ │ - 192-bit nonce │ │ Commitment │ │ - Thread Roots │ │ │
│ │ │ - AEAD │ │ - Plaintext │ │ - State Updates │ │ │
│ │ │ - Auth Tag │ │ Hash │ │ - Rollback │ │ │
│ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ FUTURE: Psy Protocol Integration Layer │ │
│ ├─────────────────────────────────────────────────────────────────────────────────────┤ │
│ │ Realm → EndCap Submission │ UCON → CSTATE Storage │ DA Miner → Blob Storage │ │
│ │ CLEAF → CFC Whitelist │ Indexer → Message Query │ │
│ └─────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
Client Side:
1. Encrypt message (XChaCha20-Poly1305)
2. Compute commitment (Poseidon2-style)
3. Send to server
Server Side:
1. Get current CSTATE root
2. Update CSTATE (Merkle tree)
3. Generate ZK proof (CFC proof, simulated)
4. Create EndCap (proof + signature + nonce)
5. Store message & update state
Client Side (Recipient):
1. Poll for messages
2. Decrypt message
3. Verify commitment & proof
4. Display message
Flow Description: Messages are encrypted client-side before transmission. The server never sees plaintext. Each message generates a commitment hash and a ZK proof that verifies the state transition is valid. The CSTATE (Contract State) is a Merkle tree that tracks all message commitments, creating an immutable, verifiable history. Recipients decrypt messages locally and verify both the commitment and ZK proof to ensure message integrity and state consistency.
┌─────────────────────────┐
│ CSTATE Root │
│ (Merkle Root) │
│ "0x4d5e6f..." │
└───────────┬─────────────┘
│
┌───────────────┴───────────────┐
│ │
┌───────▼────────┐ ┌────────▼────────┐
│ Thread 1 Root │ │ Thread 2 Root │
│ "0x1a2b3c..." │ │ "0x7f8e9d..." │
└───────┬────────┘ └────────┬────────┘
│ │
┌───────┴────────┐ ┌────────┴────────┐
│ │ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌─▼──────┐ ┌──────▼──────┐
│ Message │ │ Message │ │Message │ │ Message │
│ Commitment │ │ Commitment │ │Commit. │ │ Commitment │
│ "0xabc..." │ │ "0xdef..." │ │"0x123" │ │ "0x456..." │
└──────────────┘ └─────────────┘ └────────┘ └─────────────┘
Each message adds a new commitment to the thread's Merkle tree.
The thread root updates, which updates the CSTATE root.
This creates an immutable, verifiable history of all messages.
- E2E Encryption: XChaCha20-Poly1305 (server never sees plaintext)
- ZK Proofs: Psy Protocol CFC proofs verify state transitions (simulated, ready for plonky2-hwa)
- Identity System: ED25519 keypairs with privacy-preserving hashes. Server stores only public keys. Private keys remain in browser localStorage.
- Replay Protection: VAA nonces per identity
- Commitments: Only hashes stored, plaintext off-chain
- Encryption: XChaCha20-Poly1305 (256-bit key, 192-bit nonce)
- Signatures: ED25519 (Ed25519-SHA512)
- Hashing: SHA-256, Keccak256 (Poseidon2-style placeholder for MVP)
- ZK Proofs: CFC proofs (plonky2-hwa ready, currently simulated)
| Method | Endpoint | Description |
|---|---|---|
POST |
/identity/create |
Create ED25519 identity |
POST |
/send |
Send encrypted message with ZK proof |
GET |
/read/{thread_id} |
Get decrypted messages |
GET |
/cstate/{identity_hash} |
Get CSTATE root |
GET |
/threads/{identity_hash} |
Get all threads |
GET |
/health |
Check server status |
struct Message {
thread_id: String, // "hash1:hash2" (sorted)
sender_id: String, // Identity hash
ciphertext: String, // Base64 encrypted
iv: String, // Base64 nonce
timestamp: u64,
message_commitment: String, // Poseidon2-style commitment
endcap: Option<EndCap>, // ZK proof + metadata
}Merkle tree of user's message state. Root = CSTATE root (updated on each message). Leaves = thread roots (one per conversation).
- Keypair: ED25519 (32-byte public key)
- Identity Hash:
SHA256("zerotrace_identity" || public_key) - Privacy: Identity hash used instead of public key
- ✅ Identity system (ED25519)
- ✅ Encryption (XChaCha20-Poly1305)
- ✅ Commitments (Poseidon2-style, SHA-256 placeholder for MVP)
- ✅ ZK proof structure (CFC format)
- 🚧 Real plonky2-hwa integration (simulated, drop-in replaceable)
- 🚧 On-chain submission (format ready, Realm integration planned)
┌─────────────────────────────────────────────────────────────┐
│ Psy Protocol Components │
├─────────────────────────────────────────────────────────────┤
│ Realm → Submit EndCaps (simulated EndCap generation) │
│ UCON → Store CSTATE roots per identity │
│ CLEAF → Whitelist of allowed CFCs │
│ DA Miner → Store encrypted message blobs │
│ Indexer → Index messages, handle reorgs │
└─────────────────────────────────────────────────────────────┘
- SimProver → Plonky2Prover: Trait-based, drop-in replacement
- SHA-256 → Poseidon2: Trait-based hashing, ready to swap
- In-memory → Database: Architecture supports sled/Postgres
- Real plonky2-hwa integration for ZK proofs
- Database persistence (sled or Postgres)
- WebSocket support for real-time messaging
- Real Poseidon2 hash implementation
- Psy Protocol testnet integration
- Simulated EndCap generation (Realm integration planned)
- DA Miner integration for blob storage
- Indexer for message querying
- Multi-device state sync
- Group chat support (multi-party encryption)
- Perfect Forward Secrecy (Double Ratchet)
- Message reactions and read receipts
- Push notifications
- Mobile app (Rust core + native UI)
Q: How does this integrate with Psy Protocol?
A: The proof system uses CFCProof::for_send_message() which generates proofs in Psy Protocol format. EndCap structure matches Psy Protocol spec. Ready for integration when plonky2-hwa is available.
Q: What about persistence?
A: Currently in-memory for demo. Architecture supports easy swap to sled (embedded) or Postgres. All storage is abstracted through MessageStore.
Q: How do you handle key management?
A: Private keys never leave client (in production). Server only stores public keys. Identity hash derived from public key using SHA-256.
Q: What's the scalability plan?
A: Stateless API design allows horizontal scaling. Merkle tree state enables efficient sync. WebSocket ready for real-time (currently using polling).
Q: What makes this production-ready?
A: Type-safe Rust code, proper error handling, thread-safe operations, authenticated encryption, replay protection, and extensible architecture.
Q: What's simulated vs real?
A: Real: E2E encryption, ED25519 identities, commitments, CSTATE management. Simulated: ZK proof generation (ready for plonky2-hwa), Poseidon2 hashing (uses SHA-256 placeholder).
Built with Rust and Psy Protocol