🌊 Xersha

Your Circle, Your Bank - Stack Together, Claim Sovereignty on Bitcoin's First ZK Rollup

Showcase

The Problem

Traditional banking and savings face critical challenges:

Banks Control Your Money - You need permission to access, send, or save your own funds
Geographic Barriers - Savings tools aren't available everywhere, exclude billions globally
Lack of Sovereignty - Third parties can freeze, seize, or restrict your wealth
Isolated Savings - Saving alone lacks accountability and motivation
No Transparency - Hidden fees, opaque terms, and unclear savings progress
Technology Barriers - Bitcoin and DeFi can feel intimidating and complex to adopt alone

Our Solution

Your circle, your bank. Xersha empowers you to stack Bitcoin with friends, claim financial sovereignty, and access borderless finance—all without traditional banks.

Built on Citrea (Bitcoin's first ZK Rollup), Xersha combines the security of Bitcoin with the accountability of saving together. Take control of your wealth, save without borders, and reach your goals faster with your closest circle.

How It Works

Create or Join Circles - Start a savings circle for any goal (vacation, wedding, community project)
Invite Friends - Add members to save together and stay accountable
Track Progress - See real-time updates as your circle reaches milestones
Celebrate Together - Share achievements through a social feed experience
Secure & Transparent - Built on Bitcoin for censorship-resistant, transparent savings

Powered by Citrea

Built on Citrea - Bitcoin's first zero-knowledge rollup that brings programmability to Bitcoin while maintaining its security guarantees.

What is Citrea?

Bitcoin's First ZK Rollup - Scalable Layer 2 built on Bitcoin
EVM Compatible - Full support for Solidity smart contracts
Trust-Minimized Bridge - Clementine bridge using BitVM technology
Bitcoin Security - Inherits Bitcoin's security model while adding programmability

Why Citrea for Cirkulo?

⚡ Smart Contracts - Programmable savings circles and automated distributions
🔒 Bitcoin Settlement - Final settlement on Bitcoin's secure base layer
🌐 Scalability - Handle thousands of circles without Bitcoin's throughput limitations
🛠️ Developer Friendly - Build with familiar EVM tools (Solidity, Hardhat, etc.)

Why Bitcoin + Citrea?

✅ Your Circle, Your Bank - You hold the keys, you control the funds—not banks, not us, not anyone
✅ Financial Sovereignty - True ownership and control over your wealth
✅ Save Without Borders - Access global finance from anywhere, no geographic restrictions
✅ Full Transparency - Every contribution recorded on Bitcoin's immutable blockchain
✅ Censorship-Resistant - No one can freeze, seize, or block your savings
✅ Smart Contract Automation - Programmable savings circles with transparent rules
✅ Stack Together - Bitcoin adoption is easier and more fun with friends by your side

Key Features

🏠 Social Savings Dashboard

Track all your active circles, view contribution history, and celebrate milestones with your community through an engaging social feed.

Friendly Onboarding

New to Bitcoin or crypto? No problem! Cirkulo makes it easy to get started:

Join circles with friends who can guide you through your first transactions
Learn together in a supportive community environment
No judgment, no pressure - everyone starts somewhere
Bitcoin and Citrea might sound unfamiliar, but your friends make it approachable

Explore Public Circles

Discover and join community fundraising initiatives:

🌱 Community gardens
🐕 Animal shelter support
📚 School supplies drives
💊 Medical funds for friends
⚽ Youth sports programs
🌳 Environmental projects

Citrea Smart Contracts on Bitcoin

Savings circles powered by smart contracts on Citrea (Bitcoin Layer 2):

Real-time progress tracking with on-chain verification
Immutable transaction history settled on Bitcoin
Programmable distribution rules for circle completion
Zero-knowledge proofs for enhanced privacy
No hidden fees or intermediaries

Progressive Web App

Install on any device (iOS, Android, Desktop)
Works offline with service workers
Native app-like experience
Fast, responsive, and accessible

Social Feed Experience

Share updates and celebrations
React to milestones with emojis
Comment on achievements
Tag hashtags for discoverability
See member activity in real-time

Comprehensive Analytics

Total saved across all circles
Active circles overview
Goals completed counter
Monthly savings trends
Individual circle progress bars

Tech Stack

Blockchain Layer

Citrea - Bitcoin's first zero-knowledge rollup
Smart Contracts - Deployed on Citrea testnet for savings circle logic
EVM Compatibility - Solidity development with familiar tooling
BitVM Bridge - Trust-minimized Clementine bridge to Bitcoin
Bitcoin Settlement - Final settlement on Bitcoin's base layer

Frontend Framework

React Router 7 - Modern SPA framework with file-based routing
TypeScript - Type-safe development with strict mode
Vite - Lightning-fast HMR and build tooling

Styling & Design

Tailwind CSS v4 - Latest version with @theme directive
OKLCH Color Space - Perceptually uniform colors for better gradients
shadcn/ui Patterns - Accessible component architecture
Lucide React - Beautiful, consistent iconography
Custom Momentum Wave Logo - 6 logo concepts designed in-house

Progressive Web App

Service Workers - Offline support and caching
Web App Manifest - Installable on all platforms
Responsive Design - Mobile-first approach (sm:, md:, lg:, xl: breakpoints)
Accessibility - WCAG AA compliant with proper ARIA labels

State Management

React 19 - Latest with new hooks and features
React Router Loaders - Data fetching and caching
Local State - useState, useReducer for component state
Context API - Authentication and global state

Developer Experience

TypeScript 5.9 - Latest type system features
ESLint + Prettier - Code quality and formatting
Hot Module Replacement - Instant feedback during development
Path Aliases - Clean imports with app/ prefix

Getting Started

Prerequisites

Node.js 18+ (LTS recommended)
npm 9+ or pnpm 8+
Git for cloning the repository

Installation

# Clone the repository
git clone https://github.com/pragma-collective/cirkulo.git
cd cirkulo

# Navigate to PWA directory
cd cirkulo-pwa

# Install dependencies
npm install

# Start development server
npm run dev

The app will be available at http://localhost:5173

Development Commands

# Start dev server with HMR
npm run dev

# Type checking
npm run typecheck

# Production build
npm run build

# Start production server
npm start

Environment Variables

Create a .env file in the cirkulo-pwa directory:

# Optional: Dynamic.xyz authentication environment ID
VITE_DYNAMIC_ENVIRONMENT_ID=your_environment_id

Docker Deployment

# Build Docker image
docker build --build-arg VITE_DYNAMIC_ENVIRONMENT_ID=your_id -t cirkulo-pwa .

# Run container
docker run -p 3000:3000 cirkulo-pwa

The production build uses Caddy for serving with SPA fallback routing.

Project Structure

cirkulo/
├── cirkulo-pwa/                  # Main PWA application
│   ├── app/
│   │   ├── components/
│   │   │   ├── landing/          # Landing page sections
│   │   │   ├── dashboard/        # Dashboard components
│   │   │   ├── explore/          # Explore page components
│   │   │   ├── ui/               # Reusable UI components
│   │   │   └── layouts/          # Layout components
│   │   ├── routes/               # Page routes
│   │   │   ├── home.tsx          # Landing page
│   │   │   ├── dashboard.tsx     # Main dashboard
│   │   │   ├── explore.tsx       # Public circles
│   │   │   ├── onboarding.tsx    # User onboarding
│   │   │   └── login.tsx         # Authentication
│   │   ├── lib/                  # Utilities and helpers
│   │   ├── types/                # TypeScript type definitions
│   │   ├── context/              # React context providers
│   │   └── app.css               # Global styles with OKLCH colors
│   ├── public/                   # Static assets
│   │   ├── manifest.json         # PWA manifest
│   │   └── favicon.svg           # App icon
│   ├── react-router.config.ts    # Router configuration (SPA mode)
│   ├── tailwind.config.ts        # Tailwind customization
│   └── package.json
└── README.md                     # This file

Key Files

app/routes.ts - Route definitions using React Router 7
app/app.css - OKLCH color system and Tailwind directives
app/components/xersha-logo.tsx - Active logo (Momentum Wave)
app/components/layouts/authenticated-layout.tsx - Shared layout for app pages
app/lib/mock-data.ts - Sample data for development
public/manifest.json - PWA configuration

Design Highlights

OKLCH Color System

We use the OKLCH color space for perceptually uniform colors and smoother gradients:

Primary (Orange): #ea7c3f - Inspired by Citrea, our Bitcoin Layer 2
Secondary (Purple): Accent color for variety and visual interest
Semantic Colors: Success (teal), Warning (amber), Error (red), Info (blue)
WCAG AA Compliant: All text meets 4.5:1 contrast ratio minimum

Logo System

Designed 6 unique logo concepts, each with Icon, Horizontal, and Full variants:

Momentum Wave (Current) - Three ascending waves representing growth
Spark Circle - Celebration and community energy
Cosmic Unity - Interconnected orbits
Golden Abundance - Prosperity and wealth
Unity Circles - Interlocking rings of community
Connected X - Network effect visualization

View all logos at /logo-showcase route.

Mobile-First Responsive Design

Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
Bottom Navigation: Mobile-only tab bar (hidden md:)
Desktop Navigation: Header nav links (visible md:+)
Adaptive Layouts: 1-col mobile, 2-col tablet, 3-col desktop
Touch Targets: Minimum 44x44px for WCAG AAA compliance

Accessibility Features

✅ Semantic HTML with proper heading hierarchy
✅ ARIA labels and roles throughout
✅ Keyboard navigation with visible focus indicators
✅ Screen reader friendly (tested with NVDA, VoiceOver)
✅ Color contrast compliance (WCAG AA)
✅ Progress bars with proper aria attributes
✅ Skip links for main content

🏗️ Built With

❤️ Passion for financial inclusion and community
⚡ Speed - Vite + React Router 7 for instant dev experience
🎨 Design - Custom OKLCH color system and 6 logo concepts
♿ Accessibility - WCAG AA compliant from day one
📱 Mobile-First - Progressive Web App architecture
🔗 Citrea - Bitcoin's first ZK Rollup for programmable savings
🔒 Security - BitVM bridge and Bitcoin settlement for trust-minimized Layer 2

Made with ❤️ by Pragma Collective

Your circle, your bank. Stack together, claim sovereignty. Save without borders on Bitcoin.

Name		Name	Last commit message	Last commit date
.claude/agents		.claude/agents
cirkulo-api		cirkulo-api
cirkulo-contracts		cirkulo-contracts
cirkulo-internal-pwa		cirkulo-internal-pwa
cirkulo-pwa		cirkulo-pwa
docs		docs
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
CLAUDE.md		CLAUDE.md
README.md		README.md
llm.md		llm.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

🌊 Xersha

Showcase

The Problem

Our Solution

How It Works

Powered by Citrea

Why Bitcoin + Citrea?

Key Features

🏠 Social Savings Dashboard

Friendly Onboarding

Explore Public Circles

Citrea Smart Contracts on Bitcoin

Progressive Web App

Social Feed Experience

Comprehensive Analytics

Tech Stack

Blockchain Layer

Frontend Framework

Styling & Design

Progressive Web App

State Management

Developer Experience

Getting Started

Prerequisites

Installation

Development Commands

Environment Variables

Docker Deployment

Project Structure

Key Files

Design Highlights

OKLCH Color System

Logo System

Mobile-First Responsive Design

Accessibility Features

🏗️ Built With

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages