Skip to content

Latest commit

 

History

History
124 lines (94 loc) · 4.87 KB

Miner.md

File metadata and controls

124 lines (94 loc) · 4.87 KB

Miner API

This document contains detailed descriptions of the miner's API routes. For an overview of the miner's API routes, see API.md#miner. For an overview of all API routes, see API.md

There may be functional API calls which are not documented. These are not guaranteed to be supported beyond the current release, and should not be used in production.

Overview

The miner provides endpoints for getting headers for work and submitting solved headers to the network. The miner also provides endpoints for controlling a basic CPU mining implementation.

Index

Route HTTP verb
/miner GET
/miner/start GET
/miner/stop GET
/miner/header GET
/miner/header POST

/miner [GET]

returns the status of the miner.

JSON Response
{
  // Number of mined blocks. This value is remembered after restarting.
  "blocksmined": 9001,

  // How fast the cpu is hashing, in hashes per second.
  "cpuhashrate": 1337,

  // true if the cpu miner is active.
  "cpumining": false,

  // Number of mined blocks that are stale, indicating that they are not
  // included in the current longest chain, likely because some other block at
  // the same height had its chain extended first.
  "staleblocksmined": 0,
}

/miner/start [GET]

starts a single threaded cpu miner. Does nothing if the cpu miner is already running.

Response

standard success or error response. See API.md#standard-responses.

/miner/stop [GET]

stops the cpu miner. Does nothing if the cpu miner is not running.

Response

standard success or error response. See API.md#standard-responses.

/miner/header [GET]

provides a block header that is ready to be grinded on for work.

Byte Response

For efficiency the header for work is returned as a raw byte encoding of the header, rather than encoded to JSON.

Blocks are mined by repeatedly changing the nonce of the header, hashing the header's bytes, and comparing the resulting hash to the target. The block with that nonce is valid if the hash is less than the target. If none of the 2^64 possible nonces result in a header with a hash less than the target, call /miner/header [GET] again to get a new block header with a different merkle root. The above process can then be repeated for the new block header.

The other fields can generally be ignored. The parent block ID field is the hash of the parent block's header. Modifying this field will result in an orphan block. The timestamp is the time at which the block was mined and is set by the Sia Daemon. Modifying this field can result in invalid block. The merkle root is the merkle root of a merkle tree consisting of the timestamp, the miner outputs (one leaf per payout), and the transactions (one leaf per transaction). Modifying this field will result in an invalid block.

Field Byte range within response Byte range within header
target [0-32)
header [32-112)
parent block ID [32-64) [0-32)
nonce [64-72) [32-40)
timestamp [72-80) [40-48)
merkle root [80-112) [48-80) 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (returned bytes)
tttttttttttttttttttttttttttttttt (target)
                                hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh (header)
                                pppppppppppppppppppppppppppppppp (parent block ID)
                                                                nnnnnnnn (nonce)
                                                                        ssssssss (timestamp)
                                                                                mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm (merkle root)

/miner/header [POST]

submits a header that has passed the POW.

Request Body Bytes

For efficiency headers are submitted as raw byte encodings of the header in the body of the request, rather than as a query string parameter or path parameter. The request body should contain only the 80 bytes of the encoded header. The encoding is the same encoding used in /miner/header [GET] endpoint. Refer to #byte-response for a detailed description of the byte encoding.