StellarID

Verify once. Prove everywhere.

A decentralized identity verification platform where users verify once and prove everywhere using Zero-Knowledge Proofs — without revealing personal data.

Live Demo • How It Works • Tech Stack • Features • Architecture • Getting Started

🔥 The Problem

Every time you sign up for a service, you hand over your name, address, date of birth, income, government ID — to a database you don't control.

Problem	Reality
Repeated KYC	Users verify identity 10+ times across platforms. Same documents. Same friction. Every time.
Data Breaches	4.5 billion records exposed in 2024 alone. Your personal data is sitting in 50+ company databases.
No Ownership	You don't own your identity. Platforms do. They sell it, lose it, or revoke it without consent.

The internet has a login system. It doesn't have an identity system.

💡 The Solution

StellarID flips the model. Instead of sharing raw data, you generate a zero-knowledge proof — a cryptographic guarantee that something is true, without revealing the underlying data.

Before StellarID	With StellarID
Share full passport to prove age	Prove "I am over 18" — nothing else
Upload bank statements for income	Prove "Income > $50K" — no numbers exposed
Re-verify on every new platform	Verify once, prove anywhere, forever
Platform owns your data	You own your identity

One verification. Infinite proofs. Zero data exposure.

⚡ Live Demo

Resource	Link
🌐 Live App	StellarID Live App
🎥 Demo Video	StellarID Demo Video (Google Drive)
📊 User Feedback	Feedback Spreadsheet (Google Sheets)
🔍 Testnet Explorer	Stellar Expert

📸 Screenshots

Landing Page — Verify once. Prove everywhere.

Dashboard — Credential management & ZK proof generation

Admin Analytics — Real-time platform metrics & activity feed

Verification Page — Public proof verification with badge

API Documentation — Interactive docs with code examples

🧠 How It Works

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Connect    │────▶│   Verify     │────▶│   Get NFT       │
│   Wallet     │     │   Identity   │     │   Credential    │
│  (Freighter) │     │  (GitHub/KYC)│     │  (On-chain)     │
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                   │
                    ┌──────────────┐     ┌─────────▼────────┐
                    │   Share      │◀────│   Generate       │
                    │   Proof      │     │   ZK Proof       │
                    │  (Link/PDF)  │     │  (Client-side)   │
                    └──────────────┘     └──────────────────┘

5 steps. Zero personal data transmitted. Fully verifiable on-chain.

Connect — User connects their Stellar wallet via Freighter
Verify — Complete identity verification through an issuer (e.g., GitHub OAuth)
Receive — Get an NFT-based credential minted on Stellar (Soroban)
Prove — Generate a ZK proof client-side (never sends raw data anywhere)
Share — Share proof via link, PDF with QR code, or embeddable badge

🛠️ Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 14, React 18, TypeScript	App shell, SSR, routing
Styling	Tailwind CSS	Utility-first responsive design
Backend	Node.js, Express, TypeScript	REST API, business logic
Database	PostgreSQL	Users, credentials, proofs, issuers
Cache	Redis	Session cache, analytics caching
Blockchain	Stellar + Soroban	Smart contracts, credential NFTs
ZK Proofs	Circom + snarkjs	ZK-SNARK circuit compilation & proving
Storage	IPFS (Pinata)	Decentralized credential metadata
Auth	JWT + Stellar Wallet	Wallet-based authentication
DevOps	Docker, GitHub Actions CI/CD	Containerization, automated testing

🔥 Key Features

🪪 Identity & Credentials

Wallet-based login — No passwords. Connect with Freighter wallet
NFT credentials — Verifiable on-chain credentials minted as Soroban NFTs
GitHub OAuth issuer — Verify developer identity via GitHub
Multi-type credentials — Age, income, residency, membership, and more

🔐 Privacy & Proofs

ZK proof generation — Client-side proving with Circom/snarkjs (age, income, residency, membership circuits)
Selective disclosure — Prove specific claims without revealing underlying data
Downloadable PDF Certificates — Export verification as beautifully rendered PDFs containing embedded Scan-to-Verify QR codes (via pdfkit & qr-image)
Shareable verification — Public link for anyone to verify a proof's authenticity
Verification badge — ✅ VERIFIED or ❌ REVOKED status displayed publicly

🛡️ Security & Governance

Revocation system — On-chain credential revocation by issuers
Expiry management — Automatic credential expiry with cron enforcement
Admin analytics dashboard — Real-time platform metrics, 24h activity feed, top issuers
Rate limiting — API protection against abuse
Role-based access — Admin/user role separation

📡 Integration

REST API — Full API for third-party verification integration
Modern docs — Interactive API documentation with code examples
Docker-ready — One-command deployment with Docker Compose

📡 API Reference

Full REST API for programmatic access:

Method	Endpoint	Description	Auth
`POST`	`/api/v1/auth/connect`	Connect wallet & get JWT	—
`GET`	`/api/v1/auth/me`	Get current user profile	🔐 JWT
`POST`	`/api/v1/credentials`	Issue a new credential	🔐 JWT
`GET`	`/api/v1/credentials/my`	List user's credentials	🔐 JWT
`POST`	`/api/v1/verify`	Submit verification request	🔐 JWT
`POST`	`/api/v1/proofs`	Create shareable proof record	🔐 JWT
`GET`	`/api/v1/proofs/:token`	Public proof verification	—
`GET`	`/api/v1/proofs/:token/pdf`	Download proof PDF	—
`GET`	`/api/v1/issuers`	List registered issuers	—
`GET`	`/api/v1/admin/stats`	Platform analytics	🔐 Admin
`GET`	`/api/v1/admin/activity`	Last 24h activity	🔐 Admin
`GET`	`/api/v1/admin/chart-data`	30-day trend data	🔐 Admin
`GET`	`/api/v1/admin/top-issuers`	Top issuers by volume	🔐 Admin

Full interactive docs available at /docs route.

⚡ Performance

Metric	Value	Notes
ZK Proof Generation	~0.87s	Client-side, no server round-trip
API Response (cached)	<100ms	Redis-backed analytics queries
API Response (uncached)	<300ms	PostgreSQL with indexed queries
Contract Deployment	~5s	Soroban testnet via Stellar CLI
Frontend Build	~8s	Next.js 14 optimized production build
WASM Contract Size	12–17 KB	Optimized with `opt-level = "z"`
PDF Generation	<500ms	Server-side with pdfkit + QR code

📊 Admin Dashboard & Proof System

Analytics Panel

A full SaaS-style admin dashboard showing real-time platform health:

Metric	Description
Total Credentials	All credentials issued across the platform
Total Proofs	ZK proofs generated and verified
Active Users	Registered wallet addresses
Success Rate	Verification success percentage
30-Day Trend	Interactive area chart (Recharts) with proofs + credentials
Last 24h Activity	Real-time feed of recent verifications and issuances
Top Issuers	Ranked table of most active credential issuers

Proof System

Feature	How It Works
Generate Proof	Client-side ZK-SNARK computation using snarkjs
Download PDF	Generates a branded cryptographic certificate on-the-fly (`pdfkit`) with dynamic scan-to-verify QR codes (`qr-image`)
Share Link	Public `/verify/{token}` page — anyone can verify the proof
Badge Display	Green VERIFIED ✅ or Red REVOKED ❌ with status details

🔗 Smart Contracts (Stellar Testnet)

Three Soroban smart contracts deployed on Stellar Testnet:

Contract	Purpose	Contract ID
Credential NFT	Mint, transfer, validate credential NFTs	`CBIO5S7UB6JVO337KTMHZPTRSXQLNPQPDAMCH57MBI6N2NDC4WWO3RYX`
Revocation Registry	On-chain credential revocation by issuers	`CDRPLFWJLBFX7O552DK4P5QUYXP2ZCUVLNEICLHWVTPVSL7WWXU5PRL3`
Disclosure Contract	Selective disclosure verification records	`CDRUH5UI7HSKRXWB3BOOT5CL5V7GWRYQ25AAOA3OLTYZYWRNA7JLZ4U2`

# Verify on Stellar Explorer
https://stellar.expert/explorer/testnet/contract/CBIO5S7UB6JVO337KTMHZPTRSXQLNPQPDAMCH57MBI6N2NDC4WWO3RYX
https://stellar.expert/explorer/testnet/contract/CDRPLFWJLBFX7O552DK4P5QUYXP2ZCUVLNEICLHWVTPVSL7WWXU5PRL3
https://stellar.expert/explorer/testnet/contract/CDRUH5UI7HSKRXWB3BOOT5CL5V7GWRYQ25AAOA3OLTYZYWRNA7JLZ4U2

Contract Functions:

Credential NFT	Revocation Registry	Disclosure Contract
`initialize`	`initialize`	`initialize`
`mint_credential`	`revoke`	`verify_and_record`
`get_credential`	`is_revoked`	`get_verification`
`is_valid`	`get_revocation_record`	`get_verification_history`
`revoke`	`get_revocation_list`
`transfer`
`register_issuer`
`is_registered_issuer`
`get_owner_credentials`

🧪 Testnet Wallets

The following testnet wallets were used during development and testing:

Role	Stellar Address
Admin	`GBMQJ3G5LDWODZKUUQWGGT6NIKMM7KL5NLHVIG53WLNLWB27Z4AKH3F4`
Test User 1 (Satish)	`GDZWLHG6WBRYIGWE2JXJRI4LTXLWQSTBCSXK3XB6HLB2QOTS4DNXDSKP`
Test User 2 (Mufti)	`GA5RKOAUAVEA5POB4HKI2HCIZ3K67SZYLUW5SOACOAKCNDSM4XLC5BPR`
Test User 3 (Amit)	`GCUOCLOPD3I7ECINEXFOJVGFQFNJILYW26BERBCCQBQ7WHJMICHR2WPM`
Test User 4 (Rajdeep)	`GB2CC6D3E3SXRJUPNJ43WGMFFYEN5CNP6NRY5L2S7NUDLEAZW5IMRVLK`
Test User 5 (Manjeet)	`GDLQU6LOKWYX2EUNU7PNOK3IT27MEQD7FDR7EDWTWYVZ66HXSNKGAMO6`

All wallets funded via Stellar Friendbot

🏗️ Architecture

graph TB
    subgraph Client["🖥️ Client Layer"]
        User["User (Browser)"]
        Wallet["Freighter Wallet"]
    end

    subgraph Frontend["⚡ Frontend (Next.js 14)"]
        UI["React UI + Tailwind"]
        ZK["ZK Prover (snarkjs)"]
        Store["Zustand State"]
    end

    subgraph Backend["🔧 Backend (Express API)"]
        API["REST API"]
        Auth["JWT Auth"]
        AdminAPI["Admin Analytics"]
        ProofAPI["Proof Service"]
        PDF["PDF Generator"]
    end

    subgraph Data["💾 Data Layer"]
        PG["PostgreSQL"]
        Redis["Redis Cache"]
        IPFS["IPFS (Pinata)"]
    end

    subgraph Blockchain["⛓️ Stellar Blockchain"]
        Soroban["Soroban Runtime"]
        NFT["Credential NFT"]
        Revoke["Revocation Registry"]
        Disclose["Disclosure Contract"]
    end

    User -->|Connect| Wallet
    User -->|Interact| UI
    UI -->|API Calls| API
    UI -->|Generate Proof| ZK
    Wallet -->|Sign TX| Soroban

    API -->|Authenticate| Auth
    API -->|Query| PG
    API -->|Cache| Redis
    API -->|Store Metadata| IPFS
    API -->|Invoke| Soroban

    AdminAPI -->|Aggregate| PG
    AdminAPI -->|Cache| Redis
    ProofAPI -->|Store| PG
    ProofAPI -->|Generate| PDF

    Soroban --> NFT
    Soroban --> Revoke
    Soroban --> Disclose

    style Client fill:#1a1a2e,stroke:#7c3aed,color:#fff
    style Frontend fill:#0d0030,stroke:#00e676,color:#fff
    style Backend fill:#12003a,stroke:#7c3aed,color:#fff
    style Data fill:#0a0020,stroke:#00e676,color:#fff
    style Blockchain fill:#08001a,stroke:#a855f7,color:#fff

⚙️ Environment Setup

Backend `.env` (Already Configured)

The backend is configured to run on port 5555. Key settings:

# Server
PORT=5555
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

# Database
DATABASE_URL=postgresql://stellarid_user:stellarid_pass@localhost:5432/stellarid_db

# Cache
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=stellarid_local_dev_secret
JWT_EXPIRES_IN=7d

# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_PASSPHRASE=Test SDF Network ; September 2015

# Smart Contracts
CREDENTIAL_NFT_CONTRACT_ID=CBIO5S7UB6JVO337KTMHZPTRSXQLNPQPDAMCH57MBI6N2NDC4WWO3RYX
REVOCATION_CONTRACT_ID=CDRPLFWJLBFX7O552DK4P5QUYXP2ZCUVLNEICLHWVTPVSL7WWXU5PRL3
DISCLOSURE_CONTRACT_ID=CDRUH5UI7HSKRXWB3BOOT5CL5V7GWRYQ25AAOA3OLTYZYWRNA7JLZ4U2

# IPFS (Pinata)
IPFS_API_URL=https://api.pinata.cloud
IPFS_PROJECT_ID=<your_pinata_project_id>
IPFS_PROJECT_SECRET=<your_pinata_secret>

# GitHub OAuth
GITHUB_CLIENT_ID=Ov23limO4e1dWIJmQf4c
GITHUB_CLIENT_SECRET=<configured>
GITHUB_CALLBACK_URL=http://localhost:5555/api/v1/github-issuer/callback

Frontend `.env` (Already Configured)

NEXT_PUBLIC_API_URL=http://localhost:5555/api/v1

✅ Development environment is already configured. Both .env files contain the correct settings.

🚀 Getting Started

Prerequisites

Node.js ≥ 18
PostgreSQL ≥ 14 (running on port 5432)
Redis ≥ 7 (running on port 6379)
Freighter Wallet (Chrome Extension)

Note: Database and Redis are typically already running in the development environment.

Quick Start

# Clone the repository
git clone https://github.com/iamomm-hack/StellarID.git
cd StellarID

# Backend setup
cd backend
npm install
npm run dev                   # Starts on http://localhost:5555

# Frontend setup (new terminal)
cd frontend
npm install
npm run dev                   # Starts on http://localhost:3000

Using the App

Open Frontend: http://localhost:3000
Connect Wallet: Click "Connect Wallet" → Approve in Freighter
Link GitHub: Click "Get GitHub Credential" → Authorize with GitHub
Request Credentials: Click "Request Credential" → Select issuer & type
Generate Proof: Click "Generate ZK Proof" on any credential
Logout: Click "Logout" in the GitHub greeting banner

Architecture

Backend API: http://localhost:5555/api/v1
Frontend: http://localhost:3000
Database: PostgreSQL on localhost:5432
Cache: Redis on localhost:6379

👥 User Validation & Onboarding

As part of our MVP phase, we conducted live testing with 5 real testnet users to validate our ZK-identity flow.

User Feedback Summary

📊 Live Feedback Spreadsheet (Google Sheets)

Date	Name	Wallet Address	Email	UX Rating	Favorite Feature	Bugs/Errors	Future Improvement
Mar 22, 2026	Satish jalan	`GDZWLHG6WBRYIGWE2JXJRI4LTXLWQSTBCSXK3XB6HLB2QOTS4DNXDSKP`	satishjalan9163@gmail.com	5/5	ZK Proof PDF	None	On-chain ZK-proof verification via Soroban smart contracts
Mar 22, 2026	Mufti Armaan	`GA5RKOAUAVEA5POB4HKI2HCIZ3K67SZYLUW5SOACOAKCNDSM4XLC5BPR`	flamecyborg5@gmail.com	5/5	PDF with QR Code	None	A small guide or tooltip for Freighter wallet connection
Mar 23, 2026	Amit Shah	`GCUOCLOPD3I7ECINEXFOJVGFQFNJILYW26BERBCCQBQ7WHJMICHR2WPM`	as3131257@gmail.com	5/5	Speed of proof generation	None	None
Mar 23, 2026	Rajdeep Dutta	`GB2CC6D3E3SXRJUPNJ43WGMFFYEN5CNP6NRY5L2S7NUDLEAZW5IMRVLK`	rajdeepdutta393@gmail.com	5/5	PDF report with QR code — practical and satisfying	Dashboard loading lag — thought page stopped working	Smoother dashboard loading with animation
Mar 24, 2026	Manjeet s.	`GDLQU6LOKWYX2EUNU7PNOK3IT27MEQD7FDR7EDWTWYVZ66HXSNKGAMO6`	manjeetsharma0796@gmail.com	4/5	ZK Concept	None	More credentials to store

✅ Completed Iteration (Post-Feedback)

Issue Identified: User Rajdeep Dutta noted that the "Dashboard takes a bit of time while loading credentials. At first I thought the page had stopped working."

Improvement Applied: We immediately implemented a modern Skeleton Loading System across the Dashboard. Instead of a blank screen or a single spinner, users now see structured placeholders that indicate data is being fetched, significantly improving the perceived performance.

🔗 Improvement Commit: feat: add skeleton loaders to improve dashboard UX

📈 Future Roadmap & Evolution

Based on the collected user feedback and our long-term vision, we have outlined the following evolution for StellarID:

Phase 1: Performance & UX Polish

Web Worker Proving: Move ZK-SNARK computation to a dedicated web worker to ensure the main UI thread remains 100% responsive.
Granular Progress Tracking: Implement a step-by-step progress indicator for the 3-stage verification (Querying → Proving → Uploading).

Phase 2: Ecosystem Expansion

Social Connectors: Expand identity issuers beyond GitHub to include LinkedIn, Twitter (X), and Discord.
Custom Claims: Allow platforms to request custom ZK-circuits (e.g., "Prove balance > 1000 XLM" without showing the amount).

Phase 3: Mobile & Enterprise

StellarID Mobile: A dedicated mobile app with biometric security (FaceID/Fingerprint) for instant on-the-go ZK verification.
Enterprise SDK: A plug-and-play SDK for corporate platforms to integrate StellarID verification with two lines of code.

🤝 Contributing

We welcome contributions from the community!

# Fork the repo
# Create your feature branch
git checkout -b feature/amazing-feature

# Commit your changes
git commit -m "feat: add amazing feature"

# Push to the branch
git push origin feature/amazing-feature

# Open a Pull Request

Please read our Contributing Guide for details on our code of conduct and development process.

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

📬 Contact

Channel	Link
GitHub	@iamomm-hack
Twitter/X	@omdotcmd
Email	iamkumarom.edu@gmail.com

Built with ❤️ on Stellar
_{StellarID — Verify once. Prove everywhere.}

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github/workflows		.github/workflows
backend		backend
contracts		contracts
docs		docs
frontend		frontend
scripts		scripts
zk-circuits		zk-circuits
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
copy_artifacts.js		copy_artifacts.js
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

StellarID

Verify once. Prove everywhere.

🔥 The Problem

💡 The Solution

⚡ Live Demo

📸 Screenshots

🧠 How It Works

🛠️ Tech Stack

🔥 Key Features

🪪 Identity & Credentials

🔐 Privacy & Proofs

🛡️ Security & Governance

📡 Integration

📡 API Reference

⚡ Performance

📊 Admin Dashboard & Proof System

Analytics Panel

Proof System

🔗 Smart Contracts (Stellar Testnet)

🧪 Testnet Wallets

🏗️ Architecture

⚙️ Environment Setup

Backend .env (Already Configured)

Frontend .env (Already Configured)

🚀 Getting Started

Prerequisites

Quick Start

Using the App

Architecture

👥 User Validation & Onboarding

User Feedback Summary

✅ Completed Iteration (Post-Feedback)

📈 Future Roadmap & Evolution

Phase 1: Performance & UX Polish

Phase 2: Ecosystem Expansion

Phase 3: Mobile & Enterprise

🤝 Contributing

📜 License

📬 Contact

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Backend `.env` (Already Configured)

Frontend `.env` (Already Configured)

Packages