pos-system/services/mining-service-net/docs/en/README.md

Mining Service .NET

Mining Point management service with Pi Network-inspired mechanism for GoodGo Platform.

Overview

The Mining Service provides a gamified loyalty point mining system inspired by Pi Network, allowing users to accumulate Mining Points (MP) through daily engagement, social referrals, and community building activities.

Key Features

Feature	Description
Daily Mining	Tap-to-mine mechanism - users activate daily mining sessions
Mining Rate	Base rate increases through referrals and circle building
🔥 Streak Bonus	TikTok-style consecutive daily mining rewards
Security Circles	Trusted groups that boost mining rate and network security
Referral System	Multi-level referral bonuses for network growth
User Roles	Pioneer, Contributor, Ambassador, Node Operator tiers
Point Conversion	Convert Mining Points to platform loyalty points

---

Architecture Design

System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         API Gateway (Traefik)                        │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
┌────────────────────────────────▼────────────────────────────────────┐
│                     Mining Service .NET                              │
├─────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Mining    │  │   Circle    │  │  Referral   │  │    Rate     │ │
│  │   Session   │  │   Manager   │  │   Tracker   │  │  Calculator │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│                         Domain Layer                                 │
│  ┌─────────────────────┐  ┌─────────────────────┐                   │
│  │   MinerAggregate    │  │  CircleAggregate    │                   │
│  │   - MiningSession   │  │  - CircleMember     │                   │
│  │   - MiningHistory   │  │  - TrustLevel       │                   │
│  │   - MiningRate      │  │  - CircleBonus      │                   │
│  └─────────────────────┘  └─────────────────────┘                   │
├─────────────────────────────────────────────────────────────────────┤
│                     Infrastructure Layer                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │  PostgreSQL  │  │    Redis     │  │  RabbitMQ    │               │
│  │   (EF Core)  │  │   (Cache)    │  │  (Events)    │               │
│  └──────────────┘  └──────────────┘  └──────────────┘               │
└─────────────────────────────────────────────────────────────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        ▼                        ▼                        ▼
┌───────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  IAM Service  │      │ Wallet Service  │      │ Social Service  │
│  (Auth/Users) │      │ (Point Convert) │      │   (Friends)     │
└───────────────┘      └─────────────────┘      └─────────────────┘

Clean Architecture Structure

mining-service-net/
├── src/
│   ├── MiningService.API/              # API Layer
│   │   ├── Controllers/
│   │   │   ├── MiningController.cs     # Mining session APIs
│   │   │   ├── CirclesController.cs    # Security circle APIs
│   │   │   └── ReferralsController.cs  # Referral APIs
│   │   └── Application/
│   │       ├── Commands/               # Write operations
│   │       └── Queries/                # Read operations
│   │
│   ├── MiningService.Domain/           # Domain Layer
│   │   ├── AggregatesModel/
│   │   │   ├── MinerAggregate/         # User mining profile
│   │   │   ├── CircleAggregate/        # Security circles
│   │   │   └── ReferralAggregate/      # Referral tracking
│   │   ├── Events/                     # Domain events
│   │   ├── Exceptions/                 # Domain exceptions
│   │   └── Services/                   # Domain services
│   │
│   └── MiningService.Infrastructure/   # Infrastructure Layer
│       ├── EntityConfigurations/       # EF Core mappings
│       ├── Repositories/               # Data access
│       └── MiningServiceContext.cs     # DbContext
│
├── tests/
│   ├── MiningService.UnitTests/
│   └── MiningService.FunctionalTests/
│
├── docs/
│   ├── en/
│   └── vi/
│
└── Dockerfile

---

Domain Model

Core Aggregates

1. Miner Aggregate (User Mining Profile)

┌────────────────────────────────────────────────────────────────────┐
│                          Miner (Entity)                             │
├────────────────────────────────────────────────────────────────────┤
│ Properties:                                                         │
│   - Id: Guid                                                        │
│   - UserId: Guid (from IAM Service)                                 │
│   - Role: MinerRole (Pioneer/Contributor/Ambassador/NodeOperator)  │
│   - TotalMinedPoints: decimal                                       │
│   - CurrentMiningRate: MiningRate (Value Object)                   │
│   - CurrentSession: MiningSession?                                  │
│   - SecurityCircle: Circle?                                         │
│   - ReferralCode: string                                            │
│   - ReferredBy: Guid?                                               │
│   - Status: MinerStatus (Active/Suspended/Banned)                  │
│   - CreatedAt: DateTime                                             │
├────────────────────────────────────────────────────────────────────┤
│ Behaviors:                                                          │
│   - StartMiningSession() → MiningSession                           │
│   - ClaimMiningReward() → MiningPoints                             │
│   - UpgradeRole(role) → void                                        │
│   - JoinCircle(circle) → void                                       │
│   - RecalculateMiningRate() → MiningRate                           │
└────────────────────────────────────────────────────────────────────┘

2. Circle Aggregate (Security Circle)

┌────────────────────────────────────────────────────────────────────┐
│                          Circle (Entity)                            │
├────────────────────────────────────────────────────────────────────┤
│ Properties:                                                         │
│   - Id: Guid                                                        │
│   - OwnerId: Guid (Miner who created the circle)                   │
│   - Members: List<CircleMember> (max 5)                            │
│   - Name: string                                                    │
│   - TrustScore: decimal (0-100)                                    │
│   - BonusMultiplier: decimal                                        │
│   - Status: CircleStatus (Active/Incomplete/Disbanded)             │
│   - CreatedAt: DateTime                                             │
├────────────────────────────────────────────────────────────────────┤
│ Behaviors:                                                          │
│   - AddMember(miner) → void                                         │
│   - RemoveMember(minerId) → void                                    │
│   - CalculateTrustScore() → decimal                                 │
│   - CalculateBonusMultiplier() → decimal                           │
│   - Validate() → bool (min 3 members required)                     │
└────────────────────────────────────────────────────────────────────┘

3. Referral Aggregate

┌────────────────────────────────────────────────────────────────────┐
│                        Referral (Entity)                            │
├────────────────────────────────────────────────────────────────────┤
│ Properties:                                                         │
│   - Id: Guid                                                        │
│   - ReferrerId: Guid (who invited)                                 │
│   - ReferredId: Guid (who was invited)                             │
│   - ReferralCode: string                                            │
│   - BonusRate: decimal                                              │
│   - IsActive: bool                                                  │
│   - Level: int (1 = direct, 2 = indirect)                          │
│   - CreatedAt: DateTime                                             │
├────────────────────────────────────────────────────────────────────┤
│ Behaviors:                                                          │
│   - Activate() → void                                               │
│   - Deactivate() → void                                             │
│   - CalculateBonus(baseRate) → decimal                             │
└────────────────────────────────────────────────────────────────────┘

Value Objects

/// Mining Rate calculation
public record MiningRate(
    decimal BaseRate,           // Default: 0.25 MP/hour
    decimal CircleBonus,        // +0.25x for valid circle
    decimal ReferralBonus,      // +25% per active referral
    decimal RoleBonus,          // Based on role tier
    decimal TotalRate           // Combined rate
);

/// Mining Session tracking
public record MiningSession(
    Guid SessionId,
    DateTime StartTime,
    DateTime EndTime,           // StartTime + 24 hours
    decimal AccumulatedPoints,
    MiningSessionStatus Status  // Active/Completed/Expired
);

/// Mining Points
public record MiningPoints(
    decimal Amount,
    DateTime EarnedAt,
    string Source               // Mining/Referral/CircleBonus/RoleBonus
);

---

Mining Mechanism

🔥 Streak Bonus System (TikTok-style)

Consecutive daily mining rewards users with escalating bonuses:

%%{init: {'theme':'dark'}}%%
flowchart LR
    subgraph Streak["🔥 Streak Tiers"]
        D1["Day 1-2<br/>+0%"] --> D3["Day 3-6<br/>+10%"]
        D3 --> D7["Day 7-13<br/>+25%"]
        D7 --> D14["Day 14-29<br/>+50%"]
        D14 --> D30["Day 30+<br/>+100%"]
    end
    
    style D1 fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
    style D3 fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style D7 fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style D14 fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style D30 fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:3px

Streak Mechanics

Streak Days	Bonus	Milestone Reward
Day 1-2	+0%	-
Day 3-6	+10%	🎁 3-day badge
Day 7-13	+25%	🎁 7-day badge + 50 MP bonus
Day 14-29	+50%	🎁 14-day badge + 100 MP bonus
Day 30-59	+100%	🔥 30-day badge + 300 MP bonus
Day 60-89	+125%	🏆 60-day badge + 500 MP bonus
Day 90+	+150%	👑 90-day badge + 1000 MP bonus

Streak Protection Rules

• Grace Period: Miss 1 day → streak pauses (not reset)
• Streak Freeze: Use 1 Freeze Token to protect streak (earn 1 token per 7-day streak)
• Streak Recovery: Within 24h of missing → pay 50 MP to restore streak
• Maximum Streak: Unlimited (displayed on leaderboard)

Streak Value Object

/// Streak tracking for consecutive mining
public record MiningStreak(
    int CurrentStreak,          // Current consecutive days
    int LongestStreak,          // Personal best
    DateTime LastMiningDate,    // Last successful claim
    int FreezeTokens,           // Available streak protections
    bool IsGracePeriod,         // Currently in grace period
    decimal BonusMultiplier     // Current streak bonus
);

---

Mining Rate Formula

Total Mining Rate = Base Rate × (1 + Role) × (1 + Circle) × (1 + Referral) × (1 + Streak)

Where:
- Base Rate: 0.25 MP/hour (configurable)
- Role Multiplier: Pioneer=0%, Contributor=10%, Ambassador=25%, Node=50%
- Circle Bonus: 25% if valid circle (3-5 trusted members)
- Referral Bonus: 25% per active direct referral (capped at 100%)
- Streak Bonus: 0-150% based on consecutive daily mining

Example with Streak:

Component	Value	Multiplier
Base Rate	0.25 MP/hour	-
Role (Ambassador)	+25%	× 1.25
Valid Circle	+25%	× 1.25
2 Referrals	+50%	× 1.50
30-Day Streak	+100%	× 2.00
Total	1.17 MP/hour	28.12 MP/day

Mining Session Flow

%%{init: {'theme':'dark'}}%%
sequenceDiagram
    participant U as 📱 User
    participant A as 🌐 Mining API
    participant M as ⚙️ MinerAggregate
    participant R as 🧮 RateCalculator
    participant DB as 💾 PostgreSQL
    participant C as ⚡ Redis Cache

    U->>A: POST /api/v1/mining/start
    A->>M: StartMiningSession()
    M->>R: CalculateMiningRate()
    R-->>M: MiningRate
    M->>M: CreateSession(24h duration)
    M->>DB: SaveSession()
    M->>C: CacheSessionInfo()
    A-->>U: 200 OK { session_id, rate, end_time }
    
    Note over U: 24 hours later...
    
    U->>A: POST /api/v1/mining/claim
    A->>M: ClaimMiningReward()
    M->>M: CalculateEarnedPoints()
    M->>M: AddToTotalPoints()
    M->>DB: SaveMiningHistory()
    A-->>U: 200 OK { earned_points, total_points }

User Roles & Benefits

Role	Requirements	Mining Bonus	Benefits
Pioneer	Sign up	0%	Basic mining
Contributor	Valid security circle (3+ members)	+10%	Circle bonus active
Ambassador	5+ active referrals	+25%	Referral bonus cap increased
Node Operator	Run node software (future)	+50%	Network rewards

---

API Endpoints

Mining APIs

Method	Endpoint	Description
GET	/api/v1/mining/me	Get current mining status
POST	/api/v1/mining/start	Start 24-hour mining session
POST	/api/v1/mining/claim	Claim mining rewards
GET	/api/v1/mining/history	Get mining history
GET	/api/v1/mining/rate	Get current mining rate breakdown
GET	/api/v1/mining/leaderboard	Get top miners leaderboard

Security Circle APIs

Method	Endpoint	Description
GET	/api/v1/circles/me	Get my security circle
POST	/api/v1/circles	Create security circle
POST	/api/v1/circles/invite	Invite member to circle
POST	/api/v1/circles/accept/{inviteId}	Accept circle invitation
DELETE	/api/v1/circles/members/{memberId}	Remove circle member
GET	/api/v1/circles/trust-score	Get circle trust score

Referral APIs

Method	Endpoint	Description
GET	/api/v1/referrals/code	Get my referral code
GET	/api/v1/referrals	List my referrals
GET	/api/v1/referrals/stats	Get referral statistics
POST	/api/v1/referrals/apply	Apply referral code (during signup)

Admin Backoffice APIs

🔧 Configuration Management

Method	Endpoint	Description
GET	/api/v1/admin/config	Get all system configuration
PUT	/api/v1/admin/config	Update system configuration
GET	/api/v1/admin/config/mining	Get mining configuration
PUT	/api/v1/admin/config/mining	Update mining rates
GET	/api/v1/admin/config/streak	Get streak configuration
PUT	/api/v1/admin/config/streak	Update streak bonuses
GET	/api/v1/admin/config/referral	Get referral configuration
PUT	/api/v1/admin/config/referral	Update referral bonuses

👥 User Management

Method	Endpoint	Description
GET	/api/v1/admin/miners	List all miners (paginated)
GET	/api/v1/admin/miners/{id}	Get miner details
PUT	/api/v1/admin/miners/{id}/suspend	Suspend miner
PUT	/api/v1/admin/miners/{id}/ban	Ban miner
PUT	/api/v1/admin/miners/{id}/restore	Restore suspended miner
PUT	/api/v1/admin/miners/{id}/adjust-points	Adjust miner points
PUT	/api/v1/admin/miners/{id}/reset-streak	Reset miner streak

📊 Analytics & Reports

Method	Endpoint	Description
GET	/api/v1/admin/analytics/overview	Dashboard overview stats
GET	/api/v1/admin/analytics/miners	Miner statistics
GET	/api/v1/admin/analytics/circles	Circle statistics
GET	/api/v1/admin/analytics/referrals	Referral network stats
GET	/api/v1/admin/analytics/points	Points statistics
GET	/api/v1/admin/analytics/streaks	Streak distribution
GET	/api/v1/admin/audit-logs	View configuration change logs

---

Admin Configuration Entity

MiningConfiguration Aggregate

%%{init: {'theme':'dark'}}%%
classDiagram
    class MiningConfiguration {
        +Guid Id
        +decimal BaseRate
        +int SessionDurationHours
        +bool IsGloballyEnabled
        +DateTime UpdatedAt
        +Guid UpdatedBy
    }
    
    class StreakConfiguration {
        +Guid Id
        +List~StreakTier~ Tiers
        +bool GracePeriodEnabled
        +int GracePeriodHours
        +decimal RecoveryCost
        +int FreezeTokenDays
    }
    
    class StreakTier {
        +int MinDays
        +int MaxDays
        +decimal BonusPercent
        +string BadgeName
        +decimal MilestoneMpBonus
    }
    
    class ReferralConfiguration {
        +Guid Id
        +decimal BonusPercentPerReferral
        +decimal MaxBonusPercent
        +bool KycRequired
        +int MaxReferralLevels
    }
    
    class CircleConfiguration {
        +Guid Id
        +int MinMembers
        +int MaxMembers
        +decimal ValidCircleBonus
    }
    
    MiningConfiguration --> StreakConfiguration
    MiningConfiguration --> ReferralConfiguration
    MiningConfiguration --> CircleConfiguration
    StreakConfiguration --> "*" StreakTier

Configuration Value Objects

/// System-wide mining configuration (admin-editable)
public record MiningConfig(
    decimal BaseRate,              // Default: 0.25 MP/hour
    int SessionDurationHours,      // Default: 24
    bool IsGloballyEnabled         // Emergency kill switch
);

/// Streak tiers configuration (admin-editable)
public record StreakConfig(
    List<StreakTierConfig> Tiers,
    bool GracePeriodEnabled,       // Default: true
    int GracePeriodHours,          // Default: 24
    decimal RecoveryCostMp,        // Default: 50
    int FreezeTokenEarnDays        // Default: 7
);

public record StreakTierConfig(
    int MinDays,
    int MaxDays,
    decimal BonusPercent,
    string BadgeName,
    decimal MilestoneMpBonus
);

/// Referral configuration (admin-editable)
public record ReferralConfig(
    decimal BonusPercentPerReferral, // Default: 25%
    decimal MaxBonusPercent,         // Default: 100%
    bool KycRequired,                // Default: true
    int MaxReferralLevels            // Default: 1
);

/// Circle configuration (admin-editable)
public record CircleConfig(
    int MinMembers,                // Default: 3
    int MaxMembers,                // Default: 5
    decimal ValidCircleBonus       // Default: 25%
);

Admin Configuration Flow

%%{init: {'theme':'dark'}}%%
sequenceDiagram
    participant Admin as 🔐 Admin Backoffice
    participant API as 🌐 Mining API
    participant Config as ⚙️ ConfigService
    participant Cache as ⚡ Redis
    participant DB as 💾 PostgreSQL
    participant MQ as 📨 RabbitMQ
    
    Admin->>API: PUT /api/v1/admin/config/streak
    API->>Config: UpdateStreakConfig(newConfig)
    Config->>DB: SaveConfiguration()
    Config->>Cache: InvalidateConfigCache()
    Config->>MQ: Publish ConfigUpdatedEvent
    Config->>DB: SaveAuditLog(adminId, changes)
    API-->>Admin: 200 OK { updated_config }
    
    Note over Cache: All miners will use<br/>new config on next claim

Default Configuration Values

Category	Parameter	Default	Description
Mining	Base Rate	0.25 MP/hour	Points earned per hour
Mining	Session Duration	24 hours	Mining session length
Mining	Global Enabled	true	Emergency kill switch
Streak	Day 3-6 Bonus	10%	Early streak bonus
Streak	Day 7-13 Bonus	25%	Week streak bonus
Streak	Day 14-29 Bonus	50%	2-week streak bonus
Streak	Day 30-59 Bonus	100%	Month streak bonus
Streak	Day 60-89 Bonus	125%	2-month streak bonus
Streak	Day 90+ Bonus	150%	Max streak bonus
Streak	Grace Period	24 hours	Time before streak loss
Streak	Recovery Cost	50 MP	Cost to restore streak
Streak	Freeze Token Days	7	Days to earn freeze token
Referral	Bonus Per Referral	25%	Rate increase per referral
Referral	Max Bonus	100%	Maximum referral bonus
Referral	KYC Required	true	Require KYC for bonus
Circle	Min Members	3	Minimum for valid circle
Circle	Max Members	5	Maximum circle size
Circle	Valid Circle Bonus	25%	Bonus for valid circle

Audit Logging

All admin configuration changes are logged:

public record ConfigAuditLog(
    Guid Id,
    Guid AdminUserId,
    string ConfigType,          // "Mining" | "Streak" | "Referral" | "Circle"
    string PreviousValue,       // JSON of old config
    string NewValue,            // JSON of new config
    string Reason,              // Admin's reason for change
    DateTime CreatedAt,
    string IpAddress
);

---

Integration Points

Service Dependencies

┌─────────────────────────────────────────────────────────────────────┐
│                        Mining Service                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐     Authenticates      ┌──────────────────────┐  │
│  │              │◄────────────────────────│    IAM Service       │  │
│  │              │                         │  - User validation   │  │
│  │              │                         │  - JWT tokens        │  │
│  │              │                         └──────────────────────┘  │
│  │              │                                                   │
│  │   Mining     │     Point Conversion   ┌──────────────────────┐  │
│  │   Service    │────────────────────────►│   Wallet Service    │  │
│  │              │                         │  - Convert MP to LP  │  │
│  │              │                         │  - Transaction       │  │
│  │              │                         └──────────────────────┘  │
│  │              │                                                   │
│  │              │     Social Graph       ┌──────────────────────┐  │
│  │              │◄───────────────────────►│   Social Service    │  │
│  │              │                         │  - Friend list       │  │
│  │              │                         │  - Trust validation  │  │
│  └──────────────┘                         └──────────────────────┘  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Integration Events (RabbitMQ)

Event	Publisher	Consumer(s)	Description
MinerCreatedEvent	Mining Service	IAM Service	New miner profile created
MiningSessionStartedEvent	Mining Service	-	Mining session started
PointsMinedEvent	Mining Service	Wallet Service	Points claimed, sync to wallet
CircleCompletedEvent	Mining Service	-	Security circle became valid
ReferralActivatedEvent	Mining Service	-	Referral became active
UserRegisteredEvent	IAM Service	Mining Service	Create miner profile
FriendAddedEvent	Social Service	Mining Service	Update circle suggestions

---

Tech Stack

Component	Technology	Purpose
Framework	.NET 10	Latest LTS framework
API Layer	Controllers + MediatR	REST endpoints with CQRS pattern
Database	PostgreSQL + EF Core 10	Persistent storage with migrations
Caching	Redis + HybridCache	L1+L2 caching with stampede protection
Real-time	SignalR	Live MP updates, session notifications
Message Queue	RabbitMQ (MassTransit)	Integration events between services
Validation	FluentValidation	Request validation pipeline
API Docs	Swagger/OpenAPI	API documentation
Logging	Serilog	Structured logging
Observability	Prometheus + Grafana	Metrics and dashboards

---

Implementation Notes

1. HybridCache cho Mining Rate (Stampede Protection)

%%{init: {'theme':'dark'}}%%
sequenceDiagram
    participant R1 as 📱 Request 1
    participant R2 as 📱 Request 2
    participant R3 as 📱 Request 3
    participant HC as 🔄 HybridCache
    participant DB as 💾 PostgreSQL
    
    Note over R1,R3: Stampede Protection
    R1->>HC: GetMiningRate(userId)
    R2->>HC: GetMiningRate(userId)
    R3->>HC: GetMiningRate(userId)
    HC->>DB: Single DB query
    DB-->>HC: MiningRate data
    HC-->>R1: cached result
    HC-->>R2: cached result
    HC-->>R3: cached result

Lợi ích: Ngăn quá tải DB khi hàng nghìn user claim cùng lúc.

// Configure HybridCache in Program.cs
builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        LocalCacheExpiration = TimeSpan.FromMinutes(5),
        Expiration = TimeSpan.FromMinutes(30)
    };
});

2. SignalR cho Real-time Updates

// Mining Hub for real-time MP updates
public class MiningHub : Hub
{
    public async Task JoinMinerGroup(Guid minerId)
    {
        await Groups.AddToGroupAsync(Context.ConnectionId, $"miner:{minerId}");
    }
}

// Notify user of MP update
await _hubContext.Clients.Group($"miner:{minerId}")
    .SendAsync("PointsUpdated", new { earnedPoints, totalPoints, streakDays });

Stateful Reconnect: Giúp trải nghiệm mượt mà khi mạng chập chờn.

3. EF Core Concurrency Handling

Quan trọng cho cập nhật số dư điểm:

public class Miner : Entity
{
    public decimal TotalMinedPoints { get; private set; }
    
    // Concurrency token
    [Timestamp]
    public byte[] RowVersion { get; set; }
}

// Handle concurrent point additions
try
{
    miner.AddPoints(earnedPoints);
    await _unitOfWork.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
    await _context.Entry(miner).ReloadAsync();
    miner.AddPoints(earnedPoints);
    await _unitOfWork.SaveChangesAsync();
}

4. Background Tasks

// Daily streak processing
public class StreakProcessingService : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            await ProcessExpiredStreaksAsync();
            await AwardMilestoneRewardsAsync();
            await Task.Delay(TimeSpan.FromHours(1), ct);
        }
    }
}

5. Architecture Checklist

• Controllers + MediatR for CQRS pattern
• FluentValidation with ValidatorBehavior
• HybridCache với stampede protection
• SignalR với Stateful Reconnect cho real-time updates
• EF Core concurrency handling cho point balance
• BackgroundService cho streak/session processing
• Domain Events + MassTransit cho integration events

---

Configuration

Environment Variables

Variable	Description	Required	Default
DATABASE_URL	PostgreSQL connection	Yes	-
REDIS_URL	Redis connection	Yes	-
RABBITMQ_URL	RabbitMQ connection	Yes	-
JWT_AUTHORITY	JWT issuer URL	Yes	-
MINING_BASE_RATE	Base mining rate (MP/hour)	No	0.25
MINING_SESSION_HOURS	Session duration	No	24
CIRCLE_MIN_MEMBERS	Minimum circle members	No	3
CIRCLE_MAX_MEMBERS	Maximum circle members	No	5
REFERRAL_BONUS_PERCENT	Bonus per referral	No	25
REFERRAL_BONUS_CAP	Max referral bonus	No	100

---

Security Considerations

Anti-Fraud Measures

1. Rate Limiting - Max 1 mining session start per 24 hours
2. Device Fingerprint - Track device changes, flag suspicious activity
3. IP Monitoring - Detect multiple accounts from same IP
4. Circle Validation - Members must be real, active users
5. Referral Verification - Referrals must pass KYC to activate bonus
6. Activity Scoring - Penalize inactive or bot-like patterns

Data Protection

• Mining history encrypted at rest
• Personal data follows GDPR compliance
• Audit logs for all admin actions

---

Roadmap

Phase 1: Core Mining (MVP)

• Miner profile creation
• Daily tap-to-mine sessions
• Basic mining rate calculation
• Mining history

Phase 2: Social Features

• Security circles
• Referral system
• Circle bonus calculation

Phase 3: Advanced Features

• User role progression
• Point conversion to wallet
• Leaderboards

Phase 4: Node Network (Future)

• Node operator role
• Decentralized validation
• Network rewards

---

Resources

• Architecture Documentation
• GoodGo Platform Docs
• Pi Network Whitepaper (Inspiration)
• Wallet Service Integration

License

Proprietary - GoodGo Platform