VSS Ticketing

A blockchain-powered event ticketing platform with invisible crypto UX. Users buy and sell tickets with credit cards — blockchain handles ownership, settlement, and verification behind the scenes.

Architecture

User ──→ Next.js Frontend ──→ API Routes ──→ PostgreSQL
                                          ──→ Stripe (payments)
                                          ──→ Relayer ──→ HyperEVM (smart contracts)
                                          ←── Indexer ←── HyperEVM (events)

Layer	Description
Smart Contracts	Solidity on HyperEVM — ticket issuance, marketplace, settlement, check-in
Frontend	Next.js 15 App Router, Tailwind CSS, shadcn/ui, RainbowKit
API	Next.js Route Handlers — auth, checkout, listings, QR codes, check-in
Relayer	Polls DB for paid orders, submits on-chain transactions
Indexer	Polls HyperEVM for contract events, syncs to PostgreSQL
Database	PostgreSQL via Prisma ORM — users, events, tickets, orders, listings
Payments	Stripe Checkout — primary sales and marketplace purchases

Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 16+ (or Docker)
• Foundry (for smart contracts)

1. Clone and install

git clone <repo-url>
cd TICKETS-BIG
cd frontend && npm install

2. Start PostgreSQL

docker-compose up -d postgres

3. Configure environment

cp frontend/.env.local.example frontend/.env.local
# Fill in: AUTH_SECRET, AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET,
#          STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, QR_SECRET

4. Set up database

cd frontend
npx prisma migrate dev
npx tsx ../prisma/seed.ts

5. Run the frontend

cd frontend
npm run dev

Open http://localhost:3000.

6. (Optional) Run indexer and relayer

# Terminal 2
cd indexer && npm install && npm run dev

# Terminal 3
cd relayer && npm install && npm run dev

Project Structure

├── contracts/           # Solidity smart contracts (Foundry)
│   ├── interfaces/      # All I*.sol interface files
│   ├── core/            # Registry contracts
│   ├── event/           # EventFactory, EventController, TicketCollection
│   ├── modules/         # PrimarySale, Marketplace, Treasury, CheckIn
│   └── libraries/       # SparseMerkleTree, utilities
├── test/                # Foundry tests (unit, integration, invariant)
├── script/              # Deployment scripts
├── frontend/            # Next.js 15 application
│   ├── app/             # App Router pages and API routes
│   ├── components/      # UI components (shadcn/ui)
│   └── lib/             # Auth, API client, Prisma, QR, wagmi
├── indexer/             # Chain event indexer (viem + Prisma)
├── relayer/             # On-chain transaction relayer (viem + Prisma)
├── prisma/              # Database schema and seed data
└── docs/                # Architecture specs and interface docs

Smart Contracts

Built with Foundry. Solidity ^0.8.24, OpenZeppelin v5.

forge build
forge test

Environment Variables

Frontend (.env.local)

Variable	Description
DATABASE_URL	PostgreSQL connection string
AUTH_SECRET	NextAuth.js secret
AUTH_GOOGLE_ID	Google OAuth client ID
AUTH_GOOGLE_SECRET	Google OAuth client secret
STRIPE_SECRET_KEY	Stripe secret key
STRIPE_PUBLISHABLE_KEY	Stripe publishable key
STRIPE_WEBHOOK_SECRET	Stripe webhook signing secret
QR_SECRET	HMAC secret for QR code signing (min 32 chars)
RPC_URL	HyperEVM RPC endpoint
NEXT_PUBLIC_RPC_URL	Public RPC URL for wallet connections

Indexer / Relayer (.env)

Variable	Description
DATABASE_URL	PostgreSQL connection string
RPC_URL	HyperEVM RPC endpoint
RELAYER_PRIVATE_KEY	Relayer wallet private key
PRIMARY_SALE_ADDRESS	PrimarySaleModule contract address
MARKETPLACE_ADDRESS	MarketplaceModule contract address
EVENT_FACTORY_ADDRESS	EventFactory contract address