miner/EXTERNAL_MINER_PROTOCOL.md

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):

  {
    "job_id": "...",
    "mining_hash": "...",
    "difficulty": "...",
    "nonce_start": "...",
    "nonce_end": "..."
  }
  

• Response Body (MiningResponse):
  • Success (200 OK):

    {
      "status": "accepted",
      "job_id": "..."
    }
    

  • Error (400 Bad Request - Invalid Input / 409 Conflict - Duplicate Job ID):

    {
      "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):

    {
      "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):

    {
      "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):

    {
      "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):

    {
      "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):

    {
      "status": "cancelled",
      "job_id": "..."
    }
    

  • Job Not Found (404 Not Found):

    {
      "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):

  {
    "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):

    {
      "status": "accepted",
      "job_id": "..." // String (UUID), confirming the job ID received
    }
    

  • Error (e.g., 400 Bad Request, 500 Internal Server Error):

    {
      "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):

    {
      "status": "found",
      "job_id": "...", // String (UUID)
      "nonce": "...", // Hex String (U512 hex)
      "work": "CAFEBABE01.."   // Hex String (H256 hex)
    }
    

  • Still Working (200 OK):

    {
      "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).

    {
      "status": "stale",
      "job_id": "..." // String (UUID)
    }
    

  • Job Not Found (404 Not Found):

    {
      "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):

    {
      "status": "cancelled",
      "job_id": "..." // String (UUID)
    }
    

  • Job Not Found (404 Not Found):

    {
      "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.