Feature: STAR Points Store / Shop

[InverseAltruism]

Feature: STAR Points Store / Shop

🛒 Overview

Create a STAR Points Store where Star Skrumpey holders can redeem STAR points earned from staking for exclusive rewards:

• Whitelist spots

• NFTs / digital collectibles

• Physical merchandise

• Access passes

• Community perks

Supports two distribution models:

• FCFS (First Come First Served)

• Lottery (randomly selected winners)

---

🎯 Goals

• Add real utility to STAR points beyond governance

• Support both instant and randomized distribution

• Ensure fairness and transparency

• Provide admin tooling for full lifecycle management

• Track all purchases, entries, and redemptions

---

🧱 Architecture Overview

Store Front      → Browse, filter, purchase, enter lottery
Distribution     → FCFS stock handling + lottery draw logic
Admin Dashboard  → Create, edit, pause, draw, fulfill
Database Layer   → Items, purchases, lottery entries/results

---

📊 Core Data Model

Key entities

• store_items

• store_purchases (FCFS)

• lottery_entries

• lottery_results

• redemptions (physical items)

Supports:

• Supply limits

• Per-wallet limits

• Time-based lotteries

• Eligibility requirements (NFT count, STAR balance, variants)

---

🗂️ Suggested Folder Structure

app/
├── store/
│   ├── page.tsx              # Store front
│   ├── [itemId]/page.tsx    # Item detail
│   └── admin/               # Admin dashboard
│
├── api/store/
│   ├── items/               # CRUD items
│   ├── purchase/            # FCFS purchase
│   ├── lottery/             # Enter / draw / claim
│   └── history/             # User history
│
lib/
├── hooks/useStore.ts        # Store logic + state
└── store/
    ├── types.ts             # Shared types
    ├── db.ts                # DB operations
    └── lottery.ts           # Lottery logic

---

🔁 Distribution Logic

FCFS

• Instant purchase

• STAR deducted immediately

• Stock decremented atomically

• Optional fulfillment workflow (merch)

Lottery

• STAR committed on entry

• Randomized draw at scheduled time

• Winners can claim rewards

• Non-winners are refunded automatically

• Deterministic seed stored for auditability

---

🧩 Implementation Notes

• Fully server-verified STAR balances

• Wallet-based auth for all actions

• Admins defined via config or env

• Lottery logic isolated and testable

• Store is read-only for non-holders

Full TypeScript types, hooks, and lottery logic already drafted and can be split further if needed.

---

🔐 Admin Features

• Create / edit / pause items

• Switch between FCFS and Lottery

• Trigger lottery draws

• View entries and winners

• Manage merch fulfillment

• Export winner / shipping data

---

📋 API Summary

Endpoint | Method | Purpose | Auth -- | -- | -- | -- /api/store/items | GET | List items | Public /api/store/items | POST | Create item | Admin /api/store/items/[id] | PATCH | Update item | Admin /api/store/purchase | POST | FCFS purchase | Holder /api/store/lottery/enter | POST | Enter lottery | Holder /api/store/lottery/draw | POST | Draw winners | Admin /api/store/lottery/claim | POST | Claim prize | Winner /api/store/history | GET | User history | Holder

---

🔒 Security Considerations

• Server-side STAR balance checks

• Rate limiting on purchase/entry

• Signed wallet messages

• Admin-only draw execution

• Verifiable randomness (upgradeable to on-chain VRF later)

---

🗺️ Roadmap

Phase 1: MVP

• Item catalog

• FCFS purchase flow

• Purchase history

Phase 2: Lottery

• Entry system

• Automated draw

• Claim + refund logic

Phase 3: Admin

• Item management

• Lottery controls

• Order fulfillment

Phase 4: Polish

• Notifications (email / Discord)

• Mobile UX

• Analytics

---

🏷️ Labels

• feature

• store

• star-points

• lottery

• fcfs

• admin

---

⏱️ Estimated Effort

• MVP: 2 weeks

• Lottery: 1 week

• Admin: 1 week

• Polish: 1 week

Total: ~5 weeks

---

Outcome:
A transparent, extensible rewards economy that turns STAR points into real, desirable utility.