125 lines
4.9 KiB
Markdown
125 lines
4.9 KiB
Markdown
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](/doc/API.md#miner). For
|
|
an overview of all API routes, see [API.md](/doc/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](#miner-get) | GET |
|
|
| [/miner/start](#minerstart-get) | GET |
|
|
| [/miner/stop](#minerstop-get) | GET |
|
|
| [/miner/header](#minerheader-get) | GET |
|
|
| [/miner/header](#minerheader-post) | POST |
|
|
|
|
#### /miner [GET]
|
|
|
|
returns the status of the miner.
|
|
|
|
###### JSON Response
|
|
```javascript
|
|
{
|
|
// 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](/doc/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](/doc/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](#byte-response) for a detailed description of the byte
|
|
encoding.
|