HashCloud System Architecture

Overview

This document explains the high-level architecture of the HashCloud mining platform, including the Staking Contract, Backend Server, and Miner CLI interactions.

---

🧩 System Components

1. Staking Contract (On-Chain Smart Contract)

• Controls 14-day reward cycle.

• Issues a new poolId at the start of each cycle.

• Stores user tiers (VIP0 to VIP4).

• Provides multiplier values based on user tier.

• Source of truth for:

  • activePoolId

  • user tier

Used by: Backend server and Miner CLI to read current activePoolId and tier multipliers.

---

2. Backend Server

• Subscribes to events from the staking contract.

• Caches current activePoolId.

• Maps user tier → reward multiplier.

• Receives and stores miner submissions (scores).

• After each cycle ends:

  • Calculates final rewards.

  • Signs reward claim data for miners.

API Endpoints Example:

• GET /api/pool/active → Returns current active poolId.

• POST /api/submit → Miner submissions with scores and wallet address.

---

3. Miner CLI (Mining Client Application)

• Fetches the current activePoolId from Backend.

• Begins mining only when a pool is active.

• Tags every submission with the poolId.

• Sends mined scores to Backend for reward calculation.

---

🔄 Workflow Summary

1. Staking Contract starts a 14-day cycle and sets activePoolId.

2. Backend Server listens, stores poolId, and prepares multiplier logic.

3. Miner CLI requests activePoolId and starts mining.

4. Miners submit scores → Backend collects and logs them.

5. At cycle end, Backend calculates rewards and signs claim data.

---

✅ Benefits of This Architecture

• Fair Reward Distribution via tier system and multipliers.

• Decentralized Trust (pool data is from on-chain contract).

• Scalable — miners only depend on minimal API endpoints.

• Secure — reward claims require server-side cryptographic signature.

---

📌 Next Steps

• Add diagrams to GitBook.

• Document exact API request/response payloads.

• Provide sample Miner CLI configuration.

---

Would you like me to add diagrams, API specs, or format this into Markdown for GitBook directly?

📊 System Diagram

graph TD;
A[Staking Contract] -->|activePoolId + user tier| B[Backend Server];
B -->|API: /api/pool/active, /api/submit| C[Miner CLI];


subgraph A1[Staking Contract]
A1A[Controls 14-day cycle]
A1B[Issues new poolId each cycle]
A1C[Stores user tier]
end


subgraph B1[Backend Server]
B1A[Listens to contract events]
B1B[Caches current poolId]
B1C[Maps tier to multiplier]
B1D[Receives miner submissions]
B1E[Signs reward claims per cycle]
end


subgraph C1[Miner CLI]
C1A[Fetches active poolId]
C1B[Starts mining only when active]
C1C[Tags submissions with poolId]
C1D[Sends scores to backend]
end