Files
miner/EXTERNAL_MINER_PROTOCOL.md
T

256 lines
8.9 KiB
Markdown

# External Miner Protocol Specification
This document defines the JSON-based HTTP protocol for communication between the Resonance Network node and an external QPoW miner service.
## Overview
The node delegates the mining task (finding a valid nonce) to an external service. The node provides the necessary parameters (header hash, difficulty, nonce range) and the external miner searches for a valid nonce according to the QPoW rules defined in the `qpow-math` crate. The miner returns the result, including the winning nonce, when found.
## Data Types
See the `resonance-miner-api` crate for the canonical Rust definitions of these structures.
- `job_id`: String (UUID recommended) - Unique identifier for a specific mining task, generated by the node.
- `mining_hash`: String (64 hex chars, no 0x) - The header hash for which to find a nonce.
- `difficulty`: String (u64 as string) - The target difficulty for the mining job.
- `nonce_start`: String (128 hex chars, no 0x) - The starting nonce value (inclusive) for the search range.
- `nonce_end`: String (128 hex chars, no 0x) - The ending nonce value (inclusive) for the search range.
- `status`: Enum (`ApiResponseStatus`) - Indicates the state or result of an API call.
- `message`: String (optional) - Provides details for `Error` status responses.
- `nonce`: String (Hex, no 0x) - Represents the `U512` value of the current or winning nonce.
- `work`: String (128 hex chars, no 0x) - Represents the winning nonce as `[u8; 64]`. This is the value the node needs for verification.
- `hash_count`: Number (u64) - Number of nonces checked by the miner for the job.
- `elapsed_time`: Number (f64) - Time in seconds the miner spent on the job.
## Endpoints
### 1. Submit Mining Job
- **Endpoint:** `POST /mine`
- **Description:** The node requests the external miner to start searching for a valid nonce.
- **Request Body (`MiningRequest`):**
```json
{
"job_id": "...",
"mining_hash": "...",
"difficulty": "...",
"nonce_start": "...",
"nonce_end": "..."
}
```
- **Response Body (`MiningResponse`):**
- Success (200 OK):
```json
{
"status": "accepted",
"job_id": "..."
}
```
- Error (400 Bad Request - Invalid Input / 409 Conflict - Duplicate Job ID):
```json
{
"status": "error",
"job_id": "...",
"message": "..." // e.g., "Job already exists", "Invalid mining_hash (...)"
}
```
### 2. Get Job Result
- **Endpoint:** `GET /result/{job_id}`
- **Description:** The node polls the external miner to check the status and retrieve the result.
- **Path Parameter:**
- `job_id`: String (UUID) - The ID of the job to query.
- **Response Body (`MiningResult`):**
- Job Completed (200 OK):
```json
{
"status": "completed",
"job_id": "...",
"nonce": "...", // U512 hex value of winning nonce
"work": "...", // [u8; 64] hex value of winning nonce
"hash_count": ..., // u64
"elapsed_time": ... // f64 seconds
}
```
- Job Still Running (200 OK):
```json
{
"status": "running",
"job_id": "...",
"nonce": "...", // Current nonce being checked (U512 hex)
"work": null,
"hash_count": ..., // u64
"elapsed_time": ... // f64 seconds
}
```
- Job Failed (e.g., nonce range exhausted) (200 OK):
```json
{
"status": "failed",
"job_id": "...",
"nonce": "...", // Final nonce checked (U512 hex)
"work": null,
"hash_count": ..., // u64
"elapsed_time": ... // f64 seconds
}
```
- Job Not Found (404 Not Found):
```json
{
"status": "not_found",
"job_id": "...",
"nonce": null,
"work": null,
"hash_count": 0,
"elapsed_time": 0.0
}
```
### 3. Cancel Mining Job
- **Endpoint:** `POST /cancel/{job_id}`
- **Description:** The node requests the external miner to stop working on a specific job.
- **Path Parameter:**
- `job_id`: String (UUID) - The ID of the job to cancel.
- **Request Body:** (Empty)
- **Response Body (`MiningResponse`):
- Success (200 OK):
```json
{
"status": "cancelled",
"job_id": "..."
}
```
- Job Not Found (404 Not Found):
```json
{
"status": "not_found",
"job_id": "..."
}
```
## Notes
- All hex values (`mining_hash`, `nonce_start`, `nonce_end`, `nonce`, `work`) should be sent **without** the `0x` prefix.
- The miner must implement the validation logic defined in `qpow_math::is_valid_nonce`.
- The node relies primarily on the `work` field in the `MiningResult` (when status is `completed`) for constructing the `QPoWSeal`.
# External Miner Protocol Specification
This document defines the JSON-based HTTP protocol for communication between the node and an external QPoW miner.
## Overview
The node delegates the mining task to an external service. The node provides the necessary parameters (mining hash, difficulty, and a nonce range) and the external miner searches for a valid nonce within that range. The miner returns the nonce and the resulting work hash when a solution is found.
## Data Types
- `job_id`: String (UUID recommended) - Identifier for a specific mining task.
- `mining_hash`: String (Hex-encoded, 32-byte hash, H256) - The hash derived from the block header data that the miner needs to solve.
- `difficulty`: String (Decimal representation of u64) - The target difficulty for the block.
- `nonce_start`: String (Hex-encoded, 64-byte value, U512) - The starting nonce value (inclusive).
- `nonce_end`: String (Hex-encoded, 64-byte value, U512) - The ending nonce value (inclusive).
- `nonce`: String (Hex-encoded, 64-byte value, U512) - The solution found by the miner.
- `work`: String (Hex-encoded, 32-byte hash, H256) - The hash resulting from the combination of `mining_hash` and `nonce`, meeting the difficulty requirement.
- `status`: String Enum - Indicates the state or result of an API call.
## Endpoints
### 1. Start Mining Job
- **Endpoint:** `POST /mine`
- **Description:** The node requests the external miner to start searching for a valid nonce within the specified range for the given parameters.
- **Request Body (application/json):**
```json
{
"job_id": "...", // String (UUID), generated by the node
"mining_hash": "...", // Hex String (H256)
"difficulty": "...", // String (u64 decimal)
"nonce_start": "...", // Hex String (U512 hex)
"nonce_end": "..." // Hex String (U512 hex)
}
```
- **Response Body (application/json):**
- Success (200 OK):
```json
{
"status": "accepted",
"job_id": "..." // String (UUID), confirming the job ID received
}
```
- Error (e.g., 400 Bad Request, 500 Internal Server Error):
```json
{
"status": "rejected",
"reason": "..." // String (Description of error)
}
```
### 2. Get Job Result
- **Endpoint:** `GET /result/{job_id}`
- **Description:** The node polls the external miner to check the status and retrieve the result of a previously submitted job.
- **Path Parameter:**
- `job_id`: String (UUID) - The ID of the job to query.
- **Response Body (application/json):**
- Solution Found (200 OK):
```json
{
"status": "found",
"job_id": "...", // String (UUID)
"nonce": "...", // Hex String (U512 hex)
"work": "CAFEBABE01.." // Hex String (H256 hex)
}
```
- Still Working (200 OK):
```json
{
"status": "working",
"job_id": "..." // String (UUID)
}
```
- Job Stale/Cancelled (200 OK): Indicates the job is no longer valid (e.g., the node requested cancellation or submitted work for a newer block).
```json
{
"status": "stale",
"job_id": "..." // String (UUID)
}
```
- Job Not Found (404 Not Found):
```json
{
"status": "not_found",
"job_id": "..." // String (UUID)
}
```
### 3. Cancel Mining Job
- **Endpoint:** `POST /cancel/{job_id}`
- **Description:** The node requests the external miner to stop working on a specific job. This is typically used when the node receives a new block or its mining parameters change, making the old job obsolete.
- **Path Parameter:**
- `job_id`: String (UUID) - The ID of the job to cancel.
- **Request Body:** (Empty)
- **Response Body (application/json):**
- Success (200 OK):
```json
{
"status": "cancelled",
"job_id": "..." // String (UUID)
}
```
- Job Not Found (404 Not Found):
```json
{
"status": "not_found",
"job_id": "..." // String (UUID)
}
```
## Notes
- The external miner should iterate from `nonce_start` up to and including `nonce_end` when searching for a valid nonce.
- The miner should return the `nonce` and the calculated `work` hash when a solution is found.
- The node uses the returned `nonce` and `work` (along with the fetched `difficulty`) to construct the `QPoWSeal` and submit it.
- The external miner should not need to know anything about the runtime or the code; it only needs to perform the nonce search and return the results.