CityPass

One Pass. One Button. Seamless Mobility.

Composable Pay-Per-Second Access Protocol for Real-World Infrastructure on Solana

Live Demo • Documentation • Contract Explorer

---

What Is CityPass?

CityPass is the first composable PayFi primitive for physical infrastructure on Solana — enabling pay-per-second access to parking, bikes, metro, coworking spaces, and EV chargers with trustless escrow and verifiable proof-of-usage.

The Problem

Real-world infrastructure is sold per booking, even though usage is time-based:

• Pay $10 for 2-hour parking, use 45 minutes → Waste $6
• Flat $5 bike rental, use 20 minutes → Waste $3
• $15/day EV charging, charge for 1 hour → Waste $10

Urban mobility studies show 30-60 minutes of wasted payment per session.

The Solution

Access should only exist while payment is actively flowing.

CityPass enforces per-second streaming payments with on-chain escrow:

1. Funds locked only during active usage
2. Payment stops when you pause/end trip
3. Unused funds automatically refunded
4. Immutable NFT receipt for proof-of-usage
5. 200,000x cheaper than Ethereum ($0.0001 per trip)

---

System Architecture

---

Key Features

For Users

• Zero Wallet Popups — Connect once, trip seamlessly
• Pay Only What You Use — Per-second billing (not flat fees)
• Instant Refunds — Unused funds returned automatically
• Proof of Usage — Soulbound NFT receipt (RWA primitive)
• Multi-Modal Routes — Combine parking + metro + bike in one trip

For Operators

• Real-Time Earnings — Trustless settlement via escrow
• No Custody Risk — Funds controlled by program logic
• Reputation Scoring — On-chain trust metrics
• Easy Onboarding — Register via register_access_point()

For Developers

• Composable Primitive — Use CityPass in your DApp
• Bundle-Ready — Atomic composition with Jito
• Open Source — MIT licensed, full IDL access
• Complete SDK — TypeScript helpers for all instructions

---

Quick Start

Prerequisites

- Node.js 18+
- Rust 1.70+
- Anchor CLI 0.29+
- Solana CLI 1.17+

Clone Repository

git clone https://github.com/0xsamalt/CityPass.git
cd CityPass

Install Dependencies

# Install all workspaces
yarn install

# Or per service
cd contracts && yarn install
cd ../frontend && yarn install
cd ../backend && yarn install

Setup Environment Variables

Frontend (.env.local):

NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com
NEXT_PUBLIC_CLUSTER=devnet
NEXT_PUBLIC_PROGRAM_ID=57H7AfQdybT1Q3Btcf22wNfmYEq5ZhJZxduNEjZQ9Squ
NEXT_PUBLIC_SOLANA_WS_URL=wss://api.devnet.solana.com

Backend (.env):

SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key
HELIUS_WEBHOOK_SECRET=your_helius_secret
PORT=3001
PROGRAM_ID=57H7AfQdybT1Q3Btcf22wNfmYEq5ZhJZxduNEjZQ9Squ

Build & Deploy Contract

cd contracts
anchor build
anchor deploy --provider.cluster devnet

# Register demo access points
ts-node scripts/register-access-point.ts

Run Frontend

cd frontend
npm run dev
# Open http://localhost:3000

Run Backend Indexer

cd backend
npm run dev
# Listening on http://localhost:3001

---

User Flow

Example Route

"Campus Commute" — Ahmedabad, Gujarat

• Downtown Parking (30 min @ 0.02 SOL/min)
• Metro Station A (15 min @ 0.02 SOL/min)
• CoWork Space (120 min @ 0.03 SOL/min)

Total Cost: 4.5 SOL (only for actual usage) Savings vs Flat Fee: ~35% ($7-10 per trip)

---

Why Solana (Post-Firedancer)?

1. Cost Economics (200,000x Cheaper)

A typical 12-minute trip with 2 pauses = 4 transactions:

• Solana: $0.0001 total
• Ethereum: $20-200 (prohibitive for micro-payments)
• Arbitrum/Optimism: $0.40-2.00 (still too expensive)

2. Client Diversity = Unbreakable Uptime

• Agave (Rust) + Firedancer (C) = Two independent validator clients
• Physical gates can't be "down" due to blockchain issues
• Launched mainnet Dec 12, 2024 (production-ready)

3. Sub-200ms Finality

Users expect instant feedback. When they tap "End Trip," settlement happens in 150-200ms.

4. PDA Architecture = Trustless Escrow

Program Derived Addresses let us build escrow without centralized custody. Users' funds are controlled by program logic, not a multisig.

---

Tech Stack

Layer	Technology	Purpose
Blockchain	Solana (Devnet)	Layer 1 settlement
Smart Contract	Anchor 0.29 (Rust)	Program logic & PDAs
Frontend	Next.js 14 + TypeScript	Web interface
UI Library	Tailwind + shadcn/ui + Aceternity	Component system
Wallet	@solana/wallet-adapter	Multi-wallet support
RPC	Helius (Devnet)	Transaction broadcasting
Indexer	Helius Webhooks	Event listening
Backend	Node.js + Express	API & analytics
Database	Supabase (Postgres)	Trip history storage
NFT Standard	Metaplex Token Metadata	Soulbound receipts

---

Smart Contract Overview

Core PDAs

1. AccessPoint

pub struct AccessPoint {
    pub id: u64,
    pub access_type: AccessType, // Parking | Bike | Metro | Cowork | Charger
    pub price_per_minute: u64,   // Lamports per minute
    pub operator: Pubkey,         // Payment recipient
    pub reputation_score: u16,    // Trust metric (0-100)
    pub active: bool,             // Availability status
    pub total_earned: u64,        // Cumulative earnings
    pub bump: u8,
}

2. Trip

pub struct Trip {
    pub user: Pubkey,
    pub access_points: Vec<u64>,           // Active infrastructure
    pub access_point_rates: Vec<AccessPointRate>, // Pricing info
    pub start_ts: i64,                     // Unix timestamp
    pub last_update_ts: i64,               // Last settlement time
    pub status: TripStatus,                // Active | Paused | Completed
    pub stall_threshold: i64,              // Auto-pause safety (seconds)
    pub total_rate_per_minute: u64,        // Combined cost
    pub bump: u8,
}

3. PaymentVault

pub struct PaymentVault {
    pub trip: Pubkey,              // Associated trip
    pub deposited_amount: u64,     // Initial escrow
    pub spent_amount: u64,         // Accumulated cost
    pub bump: u8,
}

Settlement Logic

// Deterministic per-second calculation
elapsed_seconds = current_timestamp - last_update_timestamp
cost_per_second = sum(access_points.price_per_minute) / 60
amount_to_settle = elapsed_seconds * cost_per_second

// Weighted distribution to operators
operator_share = (total_spent * operator_rate) / total_rate

Security Invariants

Funds cannot be released without an active trip Access cannot remain active if payment stops Operators only claim funds earned by time Users can pause/end safely Final usage produces immutable receipt Stalled trips auto-pause after threshold

---

Frontend Features

Components

• RouteCard — Visual selection of infrastructure paths
• TripTimer — Real-time countdown & cost accumulation
• PaymentVisualizer — Animated streaming effect (frontend only)
• ReceiptNFT — Display soulbound proof with metadata
• MapView — Interactive route visualization (Ahmedabad demo)

Custom Hooks

• useWallet — Wallet adapter integration
• useTrip — Trip state management & RPC calls
• useTripHistory — Fetch past trips from backend API

---

API Reference

Backend Endpoints

GET /api/trips/:userPublicKey

Fetch trip history for a wallet.

Response:

{
  "trips": [
    {
      "tripPda": "...",
      "user": "...",
      "status": "Completed",
      "startTime": 1703001234,
      "totalPaid": 4500000,
      "refund": 500000,
      "accessPoints": [1, 3, 4],
      "receiptNft": "..."
    }
  ]
}

POST /webhook/helius

Receives blockchain events from Helius.

Payload (TripStarted):

{
  "type": "TripStarted",
  "data": {
    "trip": "...",
    "user": "...",
    "accessPoints": [1, 2],
    "depositedAmount": 5000000,
    "timestamp": 1703001234
  }
}

---

Demo Access Points (Ahmedabad)

ID	Name	Type	Price/Min	Location
1	Downtown Parking	Parking	0.02 SOL	Prahladnagar
2	City Bike Station	Bike	0.005 SOL	SG Highway
3	Metro Station A	Metro	0.02 SOL	Thaltej
4	CoWork Space	Cowork	0.03 SOL	Bodakdev
5	EV Charging Point	Charger	0.015 SOL	Satellite

---

Ecosystem Positioning

PayFi × DePIN × RWA Convergence

┌──────────────┐
│    PayFi     │ ← Sphere, Helio (streaming payments)
└──────┬───────┘
       │
       ↓
┌──────────────┐
│  CITYPASS    │ ← First physical infrastructure PayFi primitive
└──────┬───────┘
       │
       ↓
┌──────────────┐
│    DePIN     │ ← Helium model for mobility
└──────┬───────┘
       │
       ↓
┌──────────────┐
│     RWA      │ ← Receipt NFTs = Real-World Asset proof
└──────────────┘

Market Opportunity

• DePIN TVL: +340% YoY growth
• RWA on Solana: $24B+ TVL
• PayFi emergence: Jito bundles enable atomic settlements
• Physical infrastructure TAM: Multi-trillion dollar market (parking, mobility, energy)

---

Future Roadmap

Phase 1: MVP (Current)

• Core smart contract (6 instructions)
• Web frontend with wallet integration
• Backend indexer with Helius webhooks
• Demo routes (Ahmedabad campus mobility)
• Soulbound receipt NFTs

Phase 2: Bundle Composition (Q1 2025)

• Jito bundle integration for atomic operations
• Dialect notifications (real-time alerts)
• Metaplex compressed NFTs (scalable receipts)
• Dynamic pricing with Pyth oracles

Phase 3: Platform Expansion (Q2 2025)

• Operator dashboard & analytics
• Multi-city deployment (Mumbai, Bangalore, Delhi)
• Mobile app (React Native)
• Reputation system for users & operators
• SDK for third-party integrations

Phase 4: DAO & Tokenomics (Q3 2025)

• Governance token (CPASS)
• Operator staking mechanisms
• Fee distribution to token holders
• Cross-chain bridges (Wormhole)

---

Built For

Solana University Hackathon 2025

Team

• Developer: 0xsamalt
• Category: DePIN × PayFi × RWA

Links

• Website: [Coming Soon]
• Demo Video: 3-minute walkthrough
• GitBook: docs.citypass.xyz

---

Acknowledgments

• Solana Foundation — For the incredible blockchain infrastructure
• Anchor Framework — For making Solana development accessible
• Helius — For reliable RPC & webhook infrastructure
• Metaplex — For NFT standard primitives
• shadcn/ui — For beautiful component library

---

Built on Solana

"Access should only exist while payment is actively flowing."