Skip to content

README.md

Latest commit

 

History

History
162 lines (115 loc) · 5.25 KB

README.md

File metadata and controls

162 lines (115 loc) · 5.25 KB

🌌 Stellarcade

Stellar Build Status Test Coverage License: MIT

Stellarcade is a decentralized arcade platform built on the Stellar network using Soroban smart contracts. We provide provably fair games, community prize pools, and a seamless gaming experience using Stellar's fast and low-cost infrastructure.

✨ Key Features

  • Provably Fair Gaming: Our Random Number Generator (RNG) contract ensures every game result is verifiable and fair.
  • Decentralized Prize Pools: Play and win from pools managed entirely by smart contracts.
  • Stellar Speed: Lightning-fast transactions and minimal fees.
  • Multiple Games: Coin Flip, Trivia, and more—all on-chain.
  • Open Source: Built by the community, for the community.

🛠 Tech Stack

  • Smart Contracts: Rust & Soroban SDK
  • Backend: Node.js, Express, PostgreSQL, Redis
  • Frontend: Vite + React (TypeScript)
  • Infrastructure: Docker, GitHub Actions

🚀 Quick Start

Prerequisites

Local Development Setup

For a complete local development environment:

# Clone the repository
git clone https://github.com/stellar/stellarcade.git
cd stellarcade

# Enable Git hooks (mirrors CI checks locally)
git config core.hooksPath .githooks

# Start all services (PostgreSQL, Redis, Backend)
docker-compose up -d

# Build contracts
cd contracts && soroban contract build && cd ..

# Set up backend
cd backend && npm install && npm run migrate && cd ..

# Set up frontend
cd frontend && pnpm install && cd ..

See the complete Setup Guide for detailed instructions, verification steps, and troubleshooting.

📁 Project Structure

stellarcade/
├── contracts/          # Soroban smart contracts (Rust)
│   ├── prize-pool/    # Prize pool management
│   ├── coin-flip/     # Coin flip game
│   ├── random-generator/  # Provably fair RNG
│   └── ...
├── backend/           # Node.js API server
│   ├── src/          # Source code
│   ├── migrations/   # Database migrations
│   └── tests/        # API tests
├── frontend/          # React + Vite frontend
│   ├── src/          # React components
│   └── tests/        # Frontend tests
├── docs/             # Documentation
└── scripts/          # Utility scripts

📚 Documentation

Document Description
Setup Guide Complete local development setup
Architecture System design and components
API Reference REST API documentation
Game Rules Game mechanics and rules
Deployment Production deployment guide
Contributing How to contribute

Subsystem Documentation

  • Backend - API server setup and development
  • Frontend - Frontend development guide
  • Contracts - Smart contract development

🧪 Testing

# Run contract tests
cd contracts && cargo test

# Run backend tests
cd backend && npm test

# Run frontend tests
cd frontend && pnpm test

🐳 Docker Commands

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Rebuild and restart
docker-compose up -d --build

🤝 Contributing

We welcome contributions! Here's how to get started:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Enable Git hooks (git config core.hooksPath .githooks)
  4. Make your changes and run tests
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

🛡 Security

For security concerns or to report vulnerabilities, please see our SECURITY.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Community

🙏 Acknowledgments

  • Built on Stellar and Soroban
  • Inspired by the decentralized gaming movement
  • Created with ❤️ by the community

Created with ❤️ for the Stellar Ecosystem (2026)