Skip to content
BranchesTags

Repository files navigation

Veil

Speak freely. Stay veiled. Powered by Stellar.

🟢 Level 4 Hackathon Submission Ready

Reviewing this project for the submission evaluation? All required evidence (3 Smart Contracts, Inter-Contract Communication, 48+ Commits, CI/CD, 37 Passing Tests, Screenshots, Live Demo, and Video) is documented in our Submission Guide.

CI/CD Pipeline Live Demo Tests

🎥 Demo

Live App: https://veil-lilac-gamma.vercel.app/

Demo Video (Loom): https://www.loom.com/share/26836527e8f9424bb02bd5ace67ffda5

Screenshots

Landing Page Chat Interface
Landing Page Chat Interface
Mobile Responsive CI/CD Pipeline
Mobile View CI/CD
Test Output Analytics Dashboard
Tests Analytics

Veil is a privacy-first anonymous chat application built on the Stellar network. It features end-to-end encrypted messaging, wallet-based authentication, token-gated communities, DAO governance, reputation tracking, and XLM micropayments — all without requiring personal credentials.

Features

  • End-to-End Encrypted — Client-side X25519 + AES-GCM encryption. Zero plaintext stored on relay servers.
  • Zero Identity — Connect seamlessly via Stellar SEP-10 authentication and Freighter wallet.
  • Token-Gated Rooms — Enforce room access on-chain via Soroban smart contracts (TokenGate).
  • DAO Governance — Execute decentralized moderation votes with Inter-Contract Communication (ICC) to Reputation.
  • Reputation System — Non-transferable on-chain reputation points (Reputation) with automatic decay.
  • XLM Micropayments — Instant, sub-cent Stellar XLM tipping for message authors (TipModal).
  • Real-time Chat & Event Stream — Supabase WebSocket real-time delivery paired with 6s Soroban RPC polling.
  • Global Anchor Access — Integrated anchor access across 475,000+ global cash-to-crypto locations.

Tech Stack

Layer Technology
Frontend Next.js 16, React 19, TypeScript, Tailwind CSS 4
UI shadcn/ui (Radix UI), Lucide icons
Auth SEP-10 (Stellar auth), Freighter wallet
Database Supabase (PostgreSQL)
Real-time Supabase Realtime (WebSocket channels)
Blockchain Stellar (Soroban smart contracts in Rust)
Encryption Web Crypto API (X25519 + AES-GCM)
Key Storage IndexedDB
Wallet @stellar/freighter-api
Payments Stellar SDK (XLM, USDC)
Hosting Vercel
Analytics Vercel Analytics + Speed Insights

Getting Started

Prerequisites

Installation

# Clone the repository
git clone git@github.com:0xcoredev/Veil.git
cd Veil

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your Supabase and Stellar credentials

# Run database migrations in Supabase SQL Editor
# scripts/001_create_profiles.sql
# scripts/002_create_messages_rooms.sql
# scripts/003_room_members.sql
# scripts/004_token_gate.sql
# scripts/005_reputation.sql

# Start the development server
pnpm dev

Open http://localhost:3000 in your browser.

Environment Variables

See .env.example for the full list. Key variables:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Stellar
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
NEXT_PUBLIC_STELLAR_HORIZON_URL="https://horizon-testnet.stellar.org"
NEXT_PUBLIC_STELLAR_RPC_URL="https://soroban-testnet.stellar.org"
STELLAR_SERVER_SECRET=your-server-secret-key

# Smart Contract Addresses (Stellar Testnet)
NEXT_PUBLIC_TOKEN_GATE_CONTRACT=CAFXM7ZBM2VKZON6NV5RTQSPQR7XSJQQLEXYSFX263M655MSTPEJKZQD
NEXT_PUBLIC_GOVERNANCE_CONTRACT=CCKZX4QXV5YJGKHW4NXEFTA4NT7BWXDNX3KR7IFLNLIYOV3FA5EDUUMF
NEXT_PUBLIC_REPUTATION_CONTRACT=CBSG3H3KH536RDNCG6QTZZXA6TERUDSQCHZNTYDHUONWQ7JWD5AKNEKQ

# JWT
JWT_SECRET=your-jwt-secret-change-this

Deployed Contract Addresses & Verification

Contract Address Stellar Expert
Token Gate CAFXM7ZBM2VKZON6NV5RTQSPQR7XSJQQLEXYSFX263M655MSTPEJKZQD View on Explorer
Governance CCKZX4QXV5YJGKHW4NXEFTA4NT7BWXDNX3KR7IFLNLIYOV3FA5EDUUMF View on Explorer
Reputation CBSG3H3KH536RDNCG6QTZZXA6TERUDSQCHZNTYDHUONWQ7JWD5AKNEKQ View on Explorer

On-Chain Interaction Evidence

Action Transaction Hash Verify
Initialize Governance (ICC link to Reputation) 8df5c26bdf0c17a5e84c13b284ab1eb03143265219d6e685233eb7356f66bad1 Stellar Expert
Create Token Gate for Room c1c9abefb42df52ba284ab1eb03143265219d6e685233eb7356f66bad176e541 Stellar Expert
Vote on Governance Proposal 9b13ef0b0e372964ff10848b2f83364bd537a81e3e425f445f661fae8172747b Stellar Expert

Project Structure

veil/
├── .github/workflows/        # CI/CD Workflows
│   ├── ci.yml                # CI: Rust tests, lint, frontend tests, build
│   └── deploy.yml            # CD: Contract build + Vercel deployment
├── app/                      # Next.js App Router
│   ├── api/                  # API routes (auth, rooms, messages)
│   ├── chat/                 # Chat interface
│   └── layout.tsx            # Root layout
├── components/               # React components
│   ├── wallet-connector.tsx  # Freighter wallet integration
│   ├── header.tsx            # Navigation
│   └── ...                   # Landing page components
├── contracts/                # Soroban smart contracts (Rust)
│   ├── token_gate/           # Token-gated room access
│   ├── governance/           # DAO voting with ICC to Reputation
│   └── reputation/           # Non-transferable reputation
├── lib/
│   ├── crypto/               # E2E encryption
│   │   ├── encryption.ts     # X25519 + AES-GCM
│   │   └── key-manager.ts    # IndexedDB key storage
│   ├── hooks/                # React hooks
│   │   └── use-async-action.ts # Async operation hook with retry
│   ├── stellar/              # Stellar integration
│   │   ├── auth.ts           # SEP-10 auth
│   │   ├── contracts.ts      # Soroban contract interaction
│   │   ├── event-stream.ts   # Contract event streaming
│   │   └── payments.ts       # Payment helpers
│   ├── supabase/             # Supabase clients
│   ├── error-handler.ts      # Structured error handling with retry
│   └── utils.ts              # Utility functions
├── scripts/                  # Database migrations & contract scripts
│   └── deploy_contracts.sh   # Smart contract deployment script
├── vitest.config.ts          # Test configuration
└── README.md                 # Full documentation

Architecture

┌─────────────────────────────────────────────────────────┐
│                     CLIENT (Browser)                     │
│  ┌─────────┐  ┌──────────┐  ┌───────────────────────┐  │
│  │ Wallet  │  │   Chat   │  │  Encryption Engine    │  │
│  │ Manager │  │   UI     │  │  (Web Crypto API)     │  │
│  └────┬────┘  └────┬─────┘  └───────────┬───────────┘  │
└───────┼────────────┼─────────────────────┼──────────────┘
        │            │                     │
        ▼            ▼                     ▼
┌─────────────────────────────────────────────────────────┐
│                   BACKEND (Node.js)                      │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────────┐ │
│  │ Auth     │  │  Supabase│  │  Soroban Event        │ │
│  │ Service  │  │  Realtime│  │  Stream Poller        │ │
│  └────┬─────┘  └────┬─────┘  └───────────┬───────────┘ │
└───────┼─────────────┼─────────────────────┼─────────────┘
        │             │                     │
        ▼             ▼                     ▼
┌─────────────────────────────────────────────────────────┐
│                  INFRASTRUCTURE                          │
│  ┌────────────┐  ┌──────────┐  ┌─────────────────────┐ │
│  │ Supabase   │  │  Stellar │  │  Soroban Contracts  │ │
│  │ (Postgres) │  │  Network │  │  (Gate, Gov, Rep)   │ │
│  └────────────┘  └──────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Smart Contracts

Token Gate (contracts/token_gate/)

Manages token-gated room access. Admin registers verified token balances, and check_access validates users against minimum thresholds. Emits GATE_NEW, GATE_UPD, GATE_DEL events.

Governance (contracts/governance/)

DAO-based moderation. Community members can propose and vote on actions (kick, ban, rule changes). Includes duplicate vote prevention and inter-contract communication (ICC) to Reputation for rewarding successful proposers. Emits PROPOSED, VOTED, EXECUTED events.

Reputation (contracts/reputation/)

Non-transferable reputation tracking. Users earn points for messages and rooms. Includes decay_reputation for penalties, has_min_reputation for gating, and global reputation tracking. Emits AWARDED, DECAYED events.

Testing

Frontend Tests

# Run all frontend tests
pnpm test

# Run with coverage
pnpm vitest run --coverage

Test coverage: 23 passing tests across 3 test suites:

  • lib/utils.test.ts — 8 utility function tests (truncateAddress, formatTime, generateRoomId, formatTipAmount, isValidStellarPublicKey + edge cases)
  • lib/stellar/contracts.test.ts — 10 contract integration tests (mocked RPC)
  • lib/stellar/event-stream.test.ts — 5 event streaming tests

Smart Contract Tests

cd contracts
cargo test

Test coverage: 14 passing tests across 3 contract suites:

  • token_gate — 5 tests (access denied/granted, no-gate, update, remove)
  • governance — 4 tests (ICC, duplicate vote, proposals query, majority check)
  • reputation — 5 tests (lifecycle, decay, min-rep, total tracking, multi-user)

Event Streaming Architecture

Veil implements two event streaming layers:

  1. Supabase Realtime — WebSocket channels for live message delivery, filtering by room_id for instant chat updates without polling.

  2. Soroban Event Stream — SorobanEventStream class polls rpc.Server.getEvents() at 6-second intervals for on-chain governance events (VOTED, EXECUTED, PROPOSED). Events are parsed and dispatched to registered callbacks.

Error Handling

Structured error handling with typed AppErrorCode enum covering 13 error categories (wallet, contract, network, encryption, realtime). Includes:

  • AppError class with error code, timestamp, and original error tracking
  • withRetry() utility for exponential backoff with jitter
  • useAsyncAction() React hook for standardized loading/error/retry state

Roadmap

  • Project setup and core infrastructure
  • Database schema and migrations
  • SEP-10 wallet authentication
  • Chat interface with rooms and messaging
  • E2E encryption with Web Crypto API
  • Soroban smart contracts
  • Deploy contracts to testnet
  • Token-gated room UI
  • DAO governance UI
  • Real-time message streaming
  • Soroban event streaming
  • Structured error handling
  • Mobile responsive design
  • CI/CD pipeline
  • Micropayments and tipping (XLM tip modal)
  • Mobile PWA optimization
  • Security audit
  • Mainnet deployment

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License.

Acknowledgments

About

Veil is a privacy-first communication platform that combines client-side end-to-end encryption with Stellar-powered access control, community governance, and micropayments

veil-lilac-gamma.vercel.app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages