Aqua Stark is a Web3 game on StarkNet where players can collect, raise and evolve fish in a decentralized ecosystem. 🏝️🎮
✔️ Fish breeding and evolution with unique genetics.
✔️ Decentralized Marketplace to buy and sell fish and decorations.
✔️ True asset ownership thanks to StarkNet and Cairo.
✔️ Aquarium customization with exclusive items and expansions.
✔️ Special events and tournaments with rare fish and rewards.
- Front: React.js + Vite + TailwindCSS
- Backend: Node.js + Express + Supabase
- Blockchain: Dojo Engine
- Monorepo Management: pnpm workspaces
/AQUA-STARK
│── /client # Web client (frontend)
│ ├── /node_modules # Dependencies
│ ├── /public # Static assets
│ ├── /src # Frontend source code
│ ├── .gitignore
│ ├── README.md # Frontend documentation
│ ├── package.json # Dependencies and scripts
│ ├── vite.config.ts # Vite configuration
│── /backend # Backend API server
│ ├── /src # Backend source code
│ ├── /tests # Backend tests
│ ├── package.json # Backend dependencies
│── /contract # Smart contracts and game logic
│ ├── /src # Smart contract source code
│ ├── .gitignore
│ ├── README.md # Backend documentation
│ ├── LICENSE # Project license
│ ├── Scarb.toml # Scarb configuration
│── pnpm-workspace.yaml # Workspace configuration
│── pnpm-lock.yaml # Lock file
│── package.json # Root scripts and dev dependencies
│── README.md # This file 🚀- Node.js 20+
- pnpm 10.13.1+
- Rust toolchain (for Cairo/Scarb)
- Dojo CLI tools (sozo, katana, torii)
# Clone the repository
git clone https://github.com/AquaStark/Aqua-Stark.git
cd Aqua-Stark
# Install all dependencies
pnpm installFor a complete local development environment setup, follow our comprehensive guide:
📖 Local Development Guide - Complete setup from clone to running environment in <30 minutes
🛠️ Troubleshooting Guide - Common issues and solutions
From the repository root, you can run these commands:
# Install dependencies for all packages
pnpm install
# Run development server for frontend
pnpm dev
# Run linting for all packages
pnpm lint
# Run type checking for all packages
pnpm typecheck
# Build all packages
pnpm build
# Run tests for all packages
pnpm test
# Run tests with coverage
pnpm test:coverage
# Format code
pnpm format
# Check code formatting
pnpm format:checkYou can also run commands for specific packages:
# Frontend only
pnpm --filter client dev
pnpm --filter client build
pnpm --filter client lint
# Backend only
pnpm --filter backend dev
pnpm --filter backend test🔹 Frontend README: Frontend Documentation
🔹 Architecture Decisions: ADR Documentation - Key architectural decisions and rationale
To play, make sure you have a StarkNet-compatible wallet like ArgentX or Braavos. Game assets are backed by Cairo smart contracts, ensuring authenticity and scarcity.
Aqua Stark is an open-source project! To contribute, follow these steps:
1️⃣ Fork the repository
git fork https://github.com/AquaStark/Aqua-Stark.git 2️⃣ Clone your fork
git clone https://github.com/YOUR_USERNAME/Aqua-Stark.git
cd Aqua-Stark 3️⃣ Set up local development environment
# Follow our comprehensive setup guide
# 📖 [Local Development Guide](docs/local-development.md)4️⃣ Create a new branch
git checkout -b feature-new 5️⃣ Make your changes and commit them
git commit -m "feat: Add new feature" 6️⃣ Push the changes to your fork
git push origin feature-new 7️⃣ Open a Pull Request 🚀
- 📖 Local Development Guide - Complete setup from clone to running environment
- 🛠️ Troubleshooting Guide - Common issues and solutions
- 🔧 Dojo Documentation - Framework reference
feat/feature-name→ For new featuresfix/bug-name→ For bug fixeschore/task-name→ For maintenance or refactoringdocs/documentation-change→ For documentation updates
feat: add new login functionalityfix: resolve issue with fish animationschore: refactor contract logicdocs: update README with latest changes
If you encounter issues with pnpm store:
# Clear pnpm store
pnpm store prune
# Reinstall dependencies
pnpm install --forceIf you see lockfile conflicts:
# Remove lockfile and node_modules
rm pnpm-lock.yaml
rm -rf node_modules
rm -rf client/node_modules
rm -rf backend/node_modules
# Reinstall
pnpm installIf builds fail, ensure you're running from the repository root:
# Always run from root
pnpm build
# Not from individual packages
cd client && pnpm build # ❌ Avoid this🌊🐠 Dive into Aqua Stark and build your dream aquarium! 🎮🚀