# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hashcloud.sh/architecture-overview/hashcloud-system-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.