⭐

Stellar-Star

⚡ Stellar-star - Split Bills. Pay On-Chain.

Decentralized expense splitting on Stellar Testnet.
Create expenses, split by equal/percentage/weight, and settle shares
with real XLM transfers and verifiable transaction hashes.

     

---

Table of Contents

#	Section
1	📖 Project Description
2	✨ Features
3	🛠️ Tech Stack
4	📸 Screenshots
5	🔄 How It Works
6	📜 Smart Contract
7	✅ Submission Checklist Evidence
8	🚀 Quick Start
9	🔐 Environment Variables
10	🧪 Testing
11	🚢 Deployment
12	📁 Project Structure
13	📚 Documentation
14	📄 License

---

Project Description

Stellar-star solves the common "IOU but no payment" problem in group expense apps.

Most split apps only track debts. Stellar-star closes the loop by letting members settle instantly with XLM and verify results on-chain.

Every payment can be traced through an explorer transaction hash, and settlement metadata is stored via Soroban contract calls for transparency and dispute resistance.

🔑 Core Properties

Property	Description
🔐 Non-custodial	Users sign with their own wallet
🔗 On-chain verifiable	Each payment has a real tx hash
💼 Multi-wallet UX	Freighter, xBull, Lobstr support
⚡ Realtime sync	Supabase updates shared state across participants

---

Features

Feature	Status
Multi-wallet connect (Freighter, xBull, Lobstr)	✅ Live
Expense split modes (equal, percentage, weighted/custom)	✅ Live
Per-share XLM settlement flow	✅ Live
Soroban duplicate-settlement checks (is_paid)	✅ Live
On-chain payment recording (record_payment)	✅ Live
Transaction hash receipt links	✅ Live
SEP-0007 QR generation	✅ Live
Trip net-balance optimization	✅ Live
Realtime sync (Supabase + contract events)	✅ Live
Responsive mobile-first UI	✅ Live
Duplicate wallet address validation (trip and expense forms)	✅ Live

---

Tech Stack

Layer	Technology
App Framework	Next.js 15 (App Router) + TypeScript
UI	Tailwind CSS, Framer Motion, Radix UI
Blockchain	@stellar/stellar-sdk, Horizon, Soroban RPC
Smart Contract	Rust + soroban-sdk
Data Sync	Supabase (PostgreSQL + Realtime)
Testing	Jest + ts-jest + React Testing Library

---

Screenshots

📱 Mobile Views

Landing Page on Phone

Dashboard on Phone

Mobile responsive proof

🏠 Landing Page

📊 Dashboard

💰 Expenses Page

🧳 Trips Page

📝 New Expense Form

🧪 Test Output

---

How It Works

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│   Connect    │───▶│    Create     │───▶│  Choose Split │───▶│   Calculate   │
│   Wallet     │    │   Expense    │    │     Mode     │    │    Shares     │
└─────────────┘    └──────────────┘    └──────────────┘    └───────┬───────┘
                                                                   │
                   ┌──────────────┐    ┌──────────────┐    ┌───────▼───────┐
                   │  Sync State  │◀───│  Record on   │◀───│  Build/Sign   │
                   │  via Events  │    │   Soroban    │    │  & Submit TX  │
                   └──────────────┘    └──────────────┘    └───────────────┘

📋 Step-by-Step Flow

Step	Action
1	User connects wallet (Freighter / xBull / Lobstr)
2	Expense is created with split strategy and participant weights
3	App computes each member's share in XLM
4	Payment transaction is built client-side and signed in wallet
5	Signed envelope is submitted to Horizon
6	Contract read/write checks enforce no duplicate settlement
7	UI updates from tx hash receipts, event polling, and realtime sync

---

Smart Contract

Latest deployed settlement contract (this workspace session):

Detail	Value
Contract ID	CBS2BJQ4ZC2ZSAZ5XS47BGC6Q7VTMJA4SE2PVHFXGXAZI5ES6H645WHO
Deploy Transaction	View on Stellar Expert
Contract Explorer	View Contract

✅ Verified On-Chain Transactions

Transaction	Link
Settlement deploy tx	View
Pool deploy tx	View
Pool init tx (pool_ini)	View
Settlement init tx (stx_ini)	View
Inter-contract settlement proof (record_payment + internal pool withdraw)	View

🔧 Main Contract Functions

record_payment(trip_id, expense_id, payer, member, amount, tx_hash)
get_payments(trip_id)
is_paid(expense_id, member)

💰 Settlement Pool Contract

Stellar-star employs a pool contract architecture where member balances are tracked. When recording a payment on-chain, the settlement contract calls the pool contract to withdraw the member's share amount:

• deposit(member, amount): Allows any member to deposit mock pool credits for themselves (requires member's signature).
• withdraw(from, amount): Withdraws credit from a member (requires member's signature).
• balance_of(member): Returns the current mock pool credit balance for a member.

🛡️ Contract Guarantees

• ✅ Prevent duplicate settlement for same expense/member pair
• ✅ Persist immutable settlement evidence (tx_hash)
• ✅ Return payment history by trip for reconciliation

⚠️ Frontend-Handled Contract Errors

Error Code	Name	Description
#1	InvalidAmount	Amount is zero or negative
#2	AlreadyPaid	Duplicate settlement attempt
#3	EmptyId	Missing trip or expense identifier

---

Submission Checklist Evidence

Requirement	Evidence
Public repository	GitHub Repo
Live demo	stellar-star-five.vercel.app
Demo video	YouTube
Contract details and tx proof	Smart Contract section
UI screenshots	Screenshots section
Mobile screenshot proof	public/mobile-responsive.png
Test output screenshot	public/testcase.png
Release/runbook/proof docs	Documentation section

---

Quick Start

Prerequisites

Requirement	Version
Node.js	18+
npm	9+
Rust toolchain	Latest (for contract work)
Stellar CLI	Latest (for contract deploy)
Freighter wallet	Set to Testnet

Install and Run

# 1. Install dependencies
npm install

# 2. Start the dev server
npm run dev

Open http://localhost:3000 in your browser.

First time setup?

# Copy the environment template
cp .env.local.example .env.local

Then:

1. Add your Supabase URL, anon key and JWT secret to .env.local

2. Create the database schema — open the Supabase Dashboard, go to SQL Editor -> New Query, paste the whole of supabase-setup.sql and hit Run. The script is idempotent, so it is safe to run again after any change.

3. Verify the connection end to end:

   npm run db:check

   This checks the env vars, confirms SUPABASE_JWT_SECRET really signs this project's tokens, proves the tables exist, and exercises the whole sign-up write path (including that one wallet cannot read or take over another wallet's rows). It cleans up everything it creates.

4. Ensure your wallet is on Stellar Testnet

Nothing loads after signing up? That is almost always step 2: without the tables, every query returns PGRST205 and the app falls back to an empty local cache. npm run db:check will tell you in one line.

---

Database & Data Flow

Layer	File	Responsibility
Schema, RLS, triggers	supabase-setup.sql	Tables, policies, realtime, integrity triggers
Row types	types/supabase.ts	Typed mirror of the SQL schema
Session	lib/supabase/session.ts	Stores the wallet JWT; notifies React when it changes
Client	lib/supabase/client.ts	One shared client that attaches the current token per request
Queries	lib/supabase/queries.ts	Every read and write, plus row-to-domain mapping
Live data	lib/supabase/useRealtimeCollection.ts	Fetch + realtime + per-wallet offline cache
Server	lib/supabase/server.ts	Route-handler clients (never bundled for the browser)

Authentication. There is no Supabase Auth user. /api/auth/challenge issues a nonce, the wallet signs it, and /api/auth/verify checks the signature and mints an HS256 JWT with a wallet_address claim, signed with the project's JWT secret. Postgres verifies that token on every request, and every RLS policy reads identity from it via public.current_wallet(). The same call also creates or refreshes the user's profile, so sign-up completes in one round trip.

Access control. member_wallets is derived by a database trigger from the members JSON, never sent by the client, so the array RLS filters on cannot drift out of sync with the member list. created_by_wallet is frozen on update, so a member can edit a shared trip or expense without taking ownership of it.

---

Environment Variables

Use .env.local (or copy from .env.local.example):

# ── Stellar Network ──────────────────────────────
NEXT_PUBLIC_STELLAR_NETWORK=TESTNET
NEXT_PUBLIC_HORIZON_URL=https://horizon-testnet.stellar.org
NEXT_PUBLIC_STELLAR_EXPLORER=https://stellar.expert/explorer/testnet

# ── Soroban / Smart Contract ─────────────────────
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
# Deployed contract ID (example or placeholder)
NEXT_PUBLIC_CONTRACT_ID=CBS2BJQ4ZC2ZSAZ5XS47BGC6Q7VTMJA4SE2PVHFXGXAZI5ES6H645WHO

# ── Supabase ─────────────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
# Supabase JWT secret used for server-side auth challenge signatures
SUPABASE_JWT_SECRET=your-supabase-jwt-secret-here

# ── App Metadata ─────────────────────────────────
NEXT_PUBLIC_APP_NAME=Stellar-star
NEXT_PUBLIC_APP_VERSION=1.0.0
NEXT_PUBLIC_SITE_URL=http://localhost:3000

---

Testing

Run all frontend/unit tests:

npm test -- --runInBand

Generate coverage report:

npm run test:coverage

Run browser end-to-end tests (Playwright):

npm run test:e2e            # headless, all projects (desktop + mobile viewports)
npm run test:e2e:ui         # interactive UI mode
npx playwright test --project=chromium   # single browser, fastest (what CI runs)

Playwright starts the dev server itself and covers landing, auth prompt, dashboard, expenses, trips, and trip detail pages plus two mobile-viewport (Pixel 5 / iPhone 12) tests - see e2e/e2e.spec.ts. No real wallet or Supabase project is needed; it asserts unauthenticated-state UI and responsive layout. Full details in docs/RUNBOOK.md.

Verify proof assets & docs links (issue #73):

npm run proof:links

This standalone script (script: scripts/proof-link-check.js) confirms that:

• public/mobile-responsive.png exists (the mobile viewport screenshot).
• README.md references the local mobile proof asset.
• All remote proof URLs in README.md, docs/REQUIREMENT_PROOF_MATRIX.md, docs/ARCHITECTURE_AND_LIMITATIONS.md, and docs/RELEASE_CHECKLIST.md resolve successfully.

It is also wired into the quality job of .github/workflows/ci.yml, so every PR and push to main runs the same checks.

Current status in this workspace:

• Run npm test -- --runInBand to see the latest total suites/tests after any new test cases are added.
• Run npm run lint, npx tsc --noEmit, npm run proof:links, and npm run build for release checks.
• Duplicate wallet address validation (trip and expense forms) is covered by __tests__/split/calculator.test.ts, __tests__/hooks/useExpenseFormValidation.test.ts, and __tests__/components/trips/TripFormDuplicateWallet.test.tsx.
• Pending on-chain retry persistence (localStorage, wallet-scoped, survives refresh) is covered by __tests__/utils/pendingOnChain.test.ts and __tests__/payment/usePayment.retry-persistence.test.tsx.

For Rust contract checks:

cd contract
cargo check
# optional
cargo test

📝 Pre-Release Verification Checklist

#	Command	Purpose
1	npm run lint	Lint checks
2	npx tsc --noEmit	Type checking
3	npm test -- --runInBand	Run tests
4	npm run proof:links	Verify mobile proof asset & docs links
5	npm run build	Production build
6	cd contract && cargo check	Rust contract check

---

Deployment

App Build

npm run build
npm run start

Contract Deploy (Stellar Testnet)

Script:

bash scripts/deploy-contract.sh <stellar-cli-account-alias-or-secret> <token-contract-id>

Example:

bash scripts/deploy-contract.sh stellar-star-deployer C... # Stellar Asset Contract ID

The script builds, deploys, and cross-initializes both the Stellar-star Settlement contract and the Settlement Pool contract on testnet automatically.

After deployment, update:

• NEXT_PUBLIC_CONTRACT_ID and NEXT_PUBLIC_SETTLEMENT_CONTRACT_ID with the printed settlement contract ID.
• NEXT_PUBLIC_POOL_CONTRACT_ID with the printed pool contract ID.
• NEXT_PUBLIC_POOL_TOKEN_ID with the token contract ID supplied to the script.

Notes:

• If the script is not executable in your shell, run it via bash scripts/deploy-contract.sh <alias-or-secret> <token-contract-id>.
• The script resolves the deployer's address to initialize both contract structures properly.
• Always verify the returned contract IDs on Stellar Expert explorer.

---

Project Structure

stellar-star/
│
├── 📂 app/                -> Next.js app routes
├── 📂 components/         -> UI and feature components
├── 📂 context/            -> React context providers
├── 📂 hooks/              -> App hooks (wallet, payment, events, etc.)
├── 📂 lib/                -> Utilities, Stellar integration, Supabase client
├── 📂 contract/           -> Soroban Rust smart contract
├── 📂 __tests__/          -> Jest test suites
├── 📂 docs/               -> Runbook, checklist, architecture, requirement matrix
├── 📂 scripts/            -> Deployment scripts
└── 📂 types/              -> Shared TypeScript types

---

Documentation

Document	Link
Release Checklist	RELEASE_CHECKLIST.md
Production Runbook	RUNBOOK.md
Requirement Proof Matrix	REQUIREMENT_PROOF_MATRIX.md
Architecture and Limitations	ARCHITECTURE_AND_LIMITATIONS.md

---

License

MIT (2026) Stellar-star