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