Skip to content

Releases: AquaStark/API-Aqua-Stark

Aqua Stark API - v1.0.0

27 Dec 21:32
@Josue19-08 Josue19-08
v1.0.0
e7cdd27
This commit was signed with the committer’s verified signature.
Josue19-08 Josué Araya Marín
GPG key ID: 9EA92C20BD44B325
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Aqua Stark API - v1.0.0 Latest
Latest

🐟 Aqua Stark API - Release v1.0.0

🚀 First Public Release

This version establishes the solid foundation for Aqua Stark's hybrid off-chain/on-chain architecture, providing a robust and scalable API for integration with the blockchain gaming ecosystem.

✨ Key Features

🔐 Authentication System

  • Complete integration with Cartridge for wallet authentication
  • Automatic player registration on the blockchain (Dojo/Starknet)
  • Session and user profile management
  • Support for custom avatars

👤 Player Management

  • Player profiles with synchronized on-chain and off-chain data
  • XP and leveling system
  • Game statistics (reputation, tournaments won, offspring created)
  • Complete profile query with all associated assets

🐠 Fish System

  • Complete fish management: Creation, query, and update
  • Feeding system: Batch feeding for multiple fish
  • Breeding system: On-chain breeding with offspring generation
  • Fish states: Baby, Juvenile, YoungAdult, Adult
  • XP and hunger system: Hybrid game mechanics
  • Family tree: Complete lineage query for each fish
  • Unique DNA: Genetic identification for each fish

🏠 Tank System

  • Creation and management of custom tanks
  • Fish assignment to tanks
  • Tank query by player
  • Sprite and 3D asset system

🎨 Decoration System

  • Decoration management for customization
  • Decoration activation/deactivation
  • Visual assets (sprites and 3D models)
  • Decoration query by player

📦 Asset System

  • Sprite upload: For fish, tanks, and decorations
  • Avatar upload: For player profiles
  • 3D asset management: Unity model support
  • Supabase Storage integration

🏗️ Architecture

Hybrid Off-Chain/On-Chain Architecture

The API acts as an orchestration layer between multiple systems:

Unity (Frontend) 
    ↓
Aqua Stark Backend API
    ↓
┌──────────┬──────────┬──────────┬──────────┐
│Cartridge │ Supabase │   Dojo   │ Starknet │
│  Auth    │    DB    │    ECS   │   RPC    │
└──────────┴──────────┴──────────┴──────────┘

Application Layers

  • API Layer: RESTful routes organized by resource
  • Controller Layer: Request/response handling
  • Service Layer: Business logic and orchestration
  • Model Layer: Domain entities and DTOs
  • Core Layer: Type system, errors, responses, and utilities

🔌 Available Endpoints

General

  • GET /api/health - Server health check
  • GET /api/status - System status with service verification
  • GET /api - API information

Authentication

  • POST /api/auth/login - Player login/registration

Players

  • GET /api/player/:address - Get complete player profile

Fish

  • GET /api/fish/:id - Get fish details by ID
  • GET /api/fish/:id/family - Complete family tree
  • GET /api/player/:address/fish - All fish owned by a player
  • POST /api/fish/feed - Feed multiple fish (batch)
  • POST /api/fish/breed - Breed two fish together

Tanks

  • GET /api/tank/:id - Get tank details by ID
  • GET /api/player/:address/tanks - All tanks owned by a player

Decorations

  • GET /api/decoration/:id - Get decoration details by ID
  • GET /api/player/:address/decorations - All decorations owned by a player
  • POST /api/decoration/:id/activate - Activate decoration
  • POST /api/decoration/:id/deactivate - Deactivate decoration

Assets

  • POST /api/asset/fish/:id/sprite - Upload fish sprite/3D asset
  • POST /api/asset/tank/:id/sprite - Upload tank sprite
  • POST /api/asset/decoration/:id/sprite - Upload decoration sprite
  • POST /api/asset/player/:address/avatar - Upload player avatar

🛠️ Technology Stack

Component Technology Version Purpose
Runtime Node.js >=20.10.0 JavaScript execution
Language TypeScript 5.3.x Type safety
Framework Fastify 4.29.x High-performance HTTP server
Database Supabase 2.38.3 Off-chain storage
Blockchain Starknet.js 5.14.x On-chain interactions
Game Engine Dojo 1.8.5 On-chain ECS

📋 Standardized Response System

All endpoints follow a consistent response format:

Success Response:

{
  "success": true,
  "data": { /* data */ },
  "message": "Operation successful"
}

Error Response:

{
  "success": false,
  "error": {
    "type": "ErrorType",
    "message": "Error message",
    "code": 400
  }
}

🔒 Security Features

  • Strict type validation with TypeScript
  • Centralized error handling
  • Cartridge authentication system
  • On-chain ownership validation
  • Configurable CORS
  • Graceful shutdown for production

📚 Documentation

Complete documentation is available in the /docs directory:

🎯 Technical Features

Type Safety

  • TypeScript in strict mode
  • Explicit types throughout the application
  • No any types
  • Compile-time type checking

Scalability

  • Modular architecture
  • Easy addition of new endpoints
  • Clear separation of concerns
  • Standardized patterns

Maintainability

  • Well-documented code
  • Consistent code standards
  • Typed error system
  • Clear folder structure

🚦 Project Status

This version is production-ready and provides:

✅ Stable and complete API
✅ Blockchain integration (Starknet/Dojo)
✅ Functional authentication system
✅ Complete game asset management
✅ Exhaustive documentation
✅ Implemented testing system

🙏 Acknowledgments

Thank you for being part of Aqua Stark 🐟

This release represents the collaborative work of the community and establishes the foundation for the future of the on-chain gaming ecosystem.

📝 Release Notes

  • Version: 1.0.0
  • Node.js: >=20.10.0 required
  • License: MIT

Welcome to Aqua Stark! 🌊

Assets 2
Loading