⚡ StellarVote

Multi-Wallet Stellar dApp × Soroban Smart Contract × Real-Time SSE Events

🌐 Overview

StellarVote is a full-stack Web3 dApp on the Stellar network featuring:

Soroban Smart Contract — Decentralized poll creation & voting on Stellar testnet
Multi-Wallet Support — Connect via Freighter, Albedo, Lobstr, xBull, Rabet, or Hana
Real-Time SSE Events — Live activity feed powered by a Rust/Axum event server
Clerk Authentication — Secure sign-up/sign-in with email, Google, GitHub, and more
Dark Mode UI — Sleek, responsive interface built with Tailwind CSS v4
Leaderboard System — Track top voters and community engagement
Poll Templates — Quick-start templates for common poll types
Category Filtering — Organize polls by governance, community, technical, and fun

✨ Features

🔐 Authentication

Clerk-powered sign-up/sign-in
Email, Google, GitHub providers
Protected dashboard routes

👛 Multi-Wallet

Freighter, Albedo, Lobstr, xBull, Rabet, Hana
StellarWalletsKit integration
One-click connect & switch

📊 Live Polling

Create polls with custom options
Set deadline (hours/days)
Real-time vote updates via SSE
Quick-start poll templates

🏆 Leaderboard

Track top voters by vote count
Gold/Silver/Bronze badge system
Personal performance stats
Community engagement metrics

🏷️ Poll Categories

Governance, Community, Technical, Fun
Visual category filtering
Category-aware poll creation

🚀 User Onboarding

First-time welcome modal with step-by-step guide
4-step interactive walkthrough
Persists completion in localStorage

🔗 Poll Sharing

Share poll links via native Web Share API
Copy-to-clipboard support
Shareable URL with contract reference

⏱️ Live Countdown Timer

Real-time countdown to poll deadline
Animated digit transitions
Auto-detects expired polls

📜 Vote History

Local voting history with tx hash links
Expandable history panel
Clear history option

⚡ Real-Time Events

Server-Sent Events (SSE) stream
Live vote notifications
Instant poll creation alerts

🤖 AI Chat Assistant

Mistral AI-powered chat widget
Web3 & Stellar knowledge base
In-chat feedback collection

📱 Mobile Responsive Design

The dashboard and landing page are fully responsive across all device sizes:

🚀 Quick Start

Prerequisites

Tool	Version
Node.js	18+
Rust	latest stable
Stellar Wallet	Freighter / Albedo / Lobstr

Frontend

# Install dependencies
cd frontend
npm install

# Set up environment
cp .env.example .env
# Edit .env with your Clerk key & backend URL

# Start dev server
npm run dev

Smart Contract (Poll)

cd contracts/poll
cargo build --target wasm32v1-none --release

Smart Contract (Reward — Inter-Contract)

cd contracts/reward
cargo build --target wasm32v1-none --release

Backend (SSE Server)

cd backend
cargo run
# Runs on http://localhost:3001

🧱 Architecture

stellar-vote/
├── frontend/                    # React + Vite SPA
│   ├── src/
│   │   ├── main.tsx            # Entry point
│   │   ├── App.tsx             # Auth router + ErrorBoundary
│   │   ├── Dashboard.tsx       # Main dashboard with tabs
│   │   ├── LandingPage.tsx     # Marketing page with stats
│   │   ├── OnboardingModal.tsx # First-time user onboarding
│   │   ├── PollShareButton.tsx # Share poll via URL/clipboard
│   │   ├── CountdownTimer.tsx  # Live poll deadline countdown
│   │   ├── VoteHistory.tsx     # Persistent vote history panel
│   │   ├── Leaderboard.tsx     # NEW — Top voters leaderboard
│   │   ├── PollCategories.tsx  # NEW — Category filter for polls
│   │   ├── PollTemplates.tsx   # NEW — Quick poll templates
│   │   ├── StatsCounter.tsx    # NEW — Animated stats counter
│   │   ├── HowItWorks.tsx      # NEW — Step-by-step guide
│   │   ├── CommunitySection.tsx # NEW — Open source community
│   │   ├── ErrorBoundary.tsx   # React error boundary
│   │   ├── LoadingSkeleton.tsx # Loading skeletons
│   │   ├── FeedbackWidget.tsx  # Floating feedback button
│   │   ├── FeedbackView.tsx    # Admin feedback viewer
│   │   ├── ThemeProvider.tsx   # Dark/light theme
│   │   ├── types.ts            # Shared types
│   │   ├── index.css           # Tailwind + theme + animations
│   │   ├── test/               # Frontend tests
│   │   └── services/
│   │       ├── wallets.ts      # Multi-wallet kit
│   │       ├── contract.ts     # Soroban interactions
│   │       ├── backend.ts      # SSE client
│   │       ├── analytics.ts    # PostHog analytics
│   │       └── voteHistory.ts  # Vote history persistence
│   ├── screenshots/            # App screenshots
│   └── vercel.json             # Vercel SPA config
├── contracts/
│   ├── poll/                   # Soroban poll contract
│   │   └── src/lib.rs          # + 4 unit tests
│   └── reward/                 # Inter-contract reward contract
│       └── src/lib.rs
├── backend/                    # Rust Axum SSE server
│   └── src/main.rs
├── scripts/
│   ├── deploy.sh               # Unix contract deploy
│   └── deploy.ps1              # Windows contract deploy
├── .github/workflows/
│   └── ci.yml                  # CI/CD pipeline
└── README.md

🤖 CI/CD Pipeline

The project uses GitHub Actions for continuous integration. On every push to main and every pull request, the pipeline runs:

Job	What it does
Frontend	`npm ci`, `npm run lint`, `npm run build`, `npm test` (14 tests)
Contract	`cargo build` (poll + reward), `cargo test` (4 tests)
Backend	`cargo build` (Rust Axum server)

Run Tests Locally

# Frontend tests (Vitest)
cd frontend && npm test

# Contract tests (Rust)
cd contracts/poll && cargo test

Test Suite	Tests	Status
Frontend types	4	✅
Frontend backend service	3	✅
Frontend helpers	7	✅
Poll contract	4	✅
Reward contract	3	✅
Total	21	✅

🔗 Inter-Contract Communication

The contracts/reward contract demonstrates cross-contract calls by importing the compiled poll contract WASM via contractimport.

// contracts/reward/src/lib.rs
contractimport!("../poll/target/wasm32v1-none/release/stellar_poll.wasm");

🚢 Deployment Scripts

Script	Platform
`scripts/deploy.sh`	Unix (Linux/macOS)
`scripts/deploy.ps1`	Windows PowerShell

🔗 Deployed Contracts

Contract	ID	Explorer
Poll Contract	`CDROSAGWRIQG5TSRF2FFFFXZD3RGPWDS6I3IWUTC67MELRRLZHNOE6ID`	View on Stellar Expert

📡 API — Rust Backend

Endpoint	Method	Description
`/health`	GET	Health check
`/api/events`	GET	SSE stream for live events
`/api/publish`	GET	Publish vote/poll events

📜 On-Chain Transactions

#	Type	Tx Hash	Explorer	Date
1	Contract Deploy	`d36f72ac…`	View ↗	2026-06-23
2	Init Poll	`1cc35079…`	View ↗	2026-06-23
3	Cast Vote	`60b5477f…`	View ↗	2026-06-23

🛠️ Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Vite 8, Tailwind CSS v4
Authentication	Clerk
Blockchain	Stellar, Soroban SDK, @stellar/stellar-sdk v16
Wallet	StellarWalletsKit (Freighter, Albedo, Lobstr, xBull, Rabet, Hana)
Backend	Rust, Axum, tokio, SSE
Contract	Soroban SDK (Rust), WASM
Hosting	Vercel (frontend), Render (backend)

📬 Deliverables

Live Demo: https://frontend-one-rose-14.vercel.app
Contract ID: CDROSAGWRIQG5TSRF2FFFFXZD3RGPWDS6I3IWUTC67MELRRLZHNOE6ID
GitHub Repo: pritamscodee/stellar-Vote
CI Pipeline: GitHub Actions

🔵 Level 5 — Blue Belt Submission

Submission Checklist

Requirement	Status	Details
Public GitHub Repository	✅	pritamscodee/stellar-Vote
20+ Meaningful Commits	✅	90+ commits on master
Live Deployed Application	✅	steller-vote.vercel.app
PPT / Pitch Deck	✅	StellarVote Pitch Deck (PPT)
Demo Video	✅	Watch Video
50+ Testnet Users	🔄	10+ verified users onboarded (growing) · See Proof Below
Analytics / Transaction Proof	✅	PostHog + on-chain explorer links
Updated README & Docs	✅	This document
User Feedback Iteration	✅	See below

📝 User Onboarding — Google Form

📋 Google Form: StellarVote User Onboarding Form

📊 User Onboarding Data

#	Name	Email	Public Key (Stellar)	Transaction Link	Rating	Feedback
1	Aditya Jha	jha073803@gmail.com	`GDFKLTB5WKKDDJ2NRU2V5OG476HYEGWT4UFV7BID7BNGWZGRZYL3LL6Z`	View Tx	⭐⭐⭐⭐⭐ 5/5	Great Product! Liked the UI
2	Souvik Mandal	souvikmandals10@gmail.com	`GAG3SUKHIF7VAWGTDRH52XETMLZXXNXBAZLLXHSLXAQPOBBCN43YLKR4`	View Tx	⭐⭐⭐⭐ 4/5	Polling on blockchain that's nice idea!!!
3	Ankita Barman	poulumidui@gmail.com	`GCV5X5CKYUAPQLE3OYQS3PDXKX4TRV767YUCJ66PWWGZD2BXE744T276`	View Tx	⭐⭐⭐⭐⭐ 5/5	Great product, helpful for polling in medical schools
4	Debansh Tiwari	debanshtiwari712@gmail.com	`GA4SXARZZ4RPF6N7VOAH3B5OKMFAP3FGY6M6TO3DZJL4TMU2KOVBHCIY`	View Tx	⭐⭐⭐⭐⭐ 5/5	Great UI. Very user-friendly product. No issues
5	Priyasha Debnath	popololo229099@gmail.com	`GCKMODNZEAI4X6AL6SL77PNJLUUJAQAWECXDTXJZGXBOSSSF7THC3XH6`	View Tx	⭐⭐⭐ 3/5	Overall good, keep improving, add realtime microservices
6	Papita Kumari	poppritu@gmail.com	`GACMLTEWZ23NGJ5WZ2THYGLODFYTEKECB7J2U33H3DCSW2PEAQUEIZED`	View Tx	⭐⭐⭐⭐⭐ 5/5	Best design and well application
7	Probir Sha	proumg2@gmail.com	`GAEAB4UWRUODGUKBYGDXBZULSOI3HJ6HQKJNNLTY66IF3ATXMRYUCSNX`	View Tx	⭐⭐⭐⭐ 4/5	Dashboard and analytics is awesome, really better than any other
8	Abhishek Kumar	ak0001736@gmail.com	`GBENUMINONHMCBALY7UMD4JQV7XXOQHAO4KNVV4UJC5ZTGHNE7PWQ7HR`	View Tx	⭐⭐⭐⭐⭐ 5/5	Good
9	Pritam Dey	pritamsdev2@gmail.com	`GATJMD6BGNK4FQYNFWB354N7RP4XHA2R74GNSYM472ALNLJFX7NXBS3X`	View Tx	⭐⭐⭐⭐ 4/5	Good UI/UX, perfect suitable and clean design
10	Sayan Sadhukhan	sayansadhukhan544@gmail.com	`GCVT3KDQT3Z2JPWODBMHLX4ODSIKDZ7CTZYZTKHXIQLTWLF5TBRNXJHC`	View Tx	⭐⭐⭐⭐⭐ 5/5	StellarVote makes on-chain voting simple and transparent

📊 User Feedback & Adoption

📈 Metric	🚀 Value
Total Users	10+
Average Rating	⭐ 4.5 / 5
5-Star Reviews	⭐⭐⭐⭐⭐ 6 (60%)
4-Star Reviews	⭐⭐⭐⭐ 3 (30%)
3-Star Reviews	⭐⭐⭐ 1 (10%)
Wallet Verification	✅ 100% On-Chain Verified (Stellar Testnet)

All wallet addresses used for verification are genuine Stellar Testnet accounts, ensuring authentic on-chain interactions.

🔄 User Feedback Iteration (Level 5)

Based on user feedback collected through the in-app feedback widget and Google Form:

Feedback Area	What Users Said	Iteration Made	Commit
Leaderboard	"Want to see top voters"	Added Leaderboard tab with gold/silver/bronze badges	Level 5 redesign
Poll Templates	"Creating polls takes too long"	Added quick-start poll templates (Yes/No, 4 Options, Community, Quick)	Level 5 redesign
Categories	"Hard to find specific polls"	Added PollCategories filter (Governance, Community, Technical, Fun)	Level 5 redesign
Stats	"Want to see platform growth"	Added animated StatsCounter on landing page (Users, Votes, Polls, Uptime)	Level 5 redesign
How It Works	"Didn't know where to start"	Added HowItWorks 4-step guide section on landing page	Level 5 redesign
Community	"Want to contribute"	Added CommunitySection with GitHub, Issues, and PRs links	Level 5 redesign
Onboarding	"Didn't know where to start"	Added 4-step OnboardingModal walkthrough	`d4519f3`
Sharing	"How do I share a poll?"	Added PollShareButton with Web Share API + copy-to-clipboard	`d4519f3`
Poll Deadline	"When does this poll end?"	Added CountdownTimer with animated digits	`d4519f3`
Vote Tracking	"What did I vote on?"	Added VoteHistory panel with tx hash explorer links	`d4519f3`
Mobile UX	"Hard to use on phone"	Responsive redesign with mobile-first Tailwind layout	`1207046`
Dark Mode	"Text invisible in dark mode"	Fixed all contrast issues across glass cards	`252b17b`

🎯 Growth Strategy

Phase	Action	Target
Phase 1	Share on Stellar Discord, Reddit r/Stellar	50 users
Phase 2	Tweet demo with #Stellar hashtag, Dev.to blog post	100 users
Phase 3	Partner with Stellar ecosystem projects for cross-promotion	200+ users

🗺️ Future Roadmap

Feature	Description	Priority
On-Chain Poll Results	Store vote tallies directly in the Soroban contract	High
Multi-Choice Voting	Support ranked-choice and yes/no/abstain polls	High
Poll Categories	Organize polls by topic (governance, community, dev)	Medium
Notifications	Push notifications when polls you voted on close	Medium
Poll Embeds	Embeddable poll widgets for websites and docs	Low
Gas Sponsorship	Backend sponsors XLM for new user transactions	Low

📦 Architecture Overview

Layer	Technology	Purpose
Frontend	React 19, TypeScript, Vite 8, Tailwind CSS v4	SPA with dark/light theme
Auth	Clerk	Email, Google, GitHub sign-in
Wallet	StellarWalletsKit	Freighter, Albedo, Lobstr, xBull, Rabet, Hana
Smart Contract	Soroban SDK (Rust) → WASM	On-chain poll creation & voting
Backend	Rust, Axum, tokio	SSE event streaming
Analytics	PostHog	User behavior tracking
Hosting	Vercel (frontend), Render (backend)	Production deployment

📊 Analytics & Monitoring

PostHog is integrated for product analytics:

Page views tracked automatically via route changes
Wallet connections captured with wallet name
Vote casting tracked with option index
Poll creation tracked with question preview
User identification via Clerk user ID (when available)

Metric	Value
Unique Visitors	23+
Page Views	53+
Sessions	28+
Avg. Session Duration	2m 57s
Bounce Rate	14%

Built with ❤️ on Stellar · Report Issue

Name		Name	Last commit message	Last commit date
Latest commit History 129 Commits
.github/workflows		.github/workflows
backend		backend
contracts		contracts
docs		docs
frontend		frontend
scripts		scripts
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.vercelignore		.vercelignore
LEVEL4_IDEA.md		LEVEL4_IDEA.md
README.md		README.md
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation