hana rewards v4

[FidelVe]

Hana Rewards Design Document

System Overview

Purpose

A reward platform that incentivizes user engagement with the Balanced DeFi platform on ICON blockchain through seasonal tasks and point-based rewards. Users register for seasons and complete various tasks (both on-chain and off-chain) to earn points, which translate to rewards at the end of each season.

System Architecture

The system consists of several distinct services that work together:

Frontend Layer

1. Hana Rewards Frontend

   • User interface
   • Interacts with REST server through NGINX

2. NGINX Reverse Proxy

   • Routes requests
   • SSL termination
   • Load balancing

API Layer

1. Hana Rewards REST Server

   • Public-facing API
   • Handles frontend requests
   • Interacts with Auth Server

2. Auth Server

   • Manages authentication
   • User authorization
   • Session management

Task Manager Layer

A separate service containing multiple components:

1. Private REST Server

   • Internal API endpoints
   • Read-only access to MongoDB
   • Task management endpoints

2. Task Producer

   • Schedules tasks
   • Creates task messages
   • Sends to RabbitMQ

3. Task Consumer

   • Processes messages from RabbitMQ
   • Executes task logic
   • Writes results to MongoDB

4. MongoDB

   • Central database
   • Read by Private REST Server
   • Written to by Task Consumer

5. RabbitMQ

   • Message queue
   • Connects Producer and Consumer
   • Task distribution

Service Communication Flow

Component Details

1. Frontend to REST Communication

• Frontend makes HTTP requests through NGINX
• NGINX routes to Hana REST Server
• Authentication handled by Auth Server
• REST Server communicates with Task Manager

2. Task Manager Internal Flow

Key Responsibilities

1. Task Production

   • Schedules task execution timing
   • Creates task messages based on:
   • On-chain events (Balanced DeFi activities)
   • Time-based triggers (daily/weekly tasks)
   • User actions (off-chain activities)
   • Publishes messages to RabbitMQ queues

2. Task Consumption

   • Subscribes to RabbitMQ queues
   • Processes task messages
   • Executes task-specific logic
   • Updates user progress in database
   • Calculates and awards points

Task Types

1. On-chain Tasks

   • Balanced DeFi interactions
   • Collateral deposits
   • Loan management
   • Savings rates deposits
   • in the future swaps and tracking other platforms can be integrated

2. Off-chain Tasks

   • Daily check-in
   • Newsletter subscription
   • Social media engagement

Key Points

1. Separation of Concerns

   • Clear separation between public and private APIs
   • Task execution isolated in Task Manager
   • Read/Write separation for MongoDB access

2. Data Flow Control

   • One-way data flow through the system
   • Private REST server has read-only access
   • Task Consumer has write access to MongoDB

3. Security

   • Public API separated from task execution
   • Authentication layer
   • NGINX as reverse proxy