github.com/Synthesix/Sia@v1.3.3-0.20180413141344-f863baeed3ca/doc/api/Miner.md (about) 1 Miner API 2 ========= 3 4 This document contains detailed descriptions of the miner's API routes. For an 5 overview of the miner's API routes, see [API.md#miner](/doc/API.md#miner). For 6 an overview of all API routes, see [API.md](/doc/API.md) 7 8 There may be functional API calls which are not documented. These are not 9 guaranteed to be supported beyond the current release, and should not be used 10 in production. 11 12 Overview 13 -------- 14 15 The miner provides endpoints for getting headers for work and submitting solved 16 headers to the network. The miner also provides endpoints for controlling a 17 basic CPU mining implementation. 18 19 Index 20 ----- 21 22 | Route | HTTP verb | 23 | ---------------------------------- | --------- | 24 | [/miner](#miner-get) | GET | 25 | [/miner/start](#minerstart-get) | GET | 26 | [/miner/stop](#minerstop-get) | GET | 27 | [/miner/header](#minerheader-get) | GET | 28 | [/miner/header](#minerheader-post) | POST | 29 30 #### /miner [GET] 31 32 returns the status of the miner. 33 34 ###### JSON Response 35 ```javascript 36 { 37 // Number of mined blocks. This value is remembered after restarting. 38 "blocksmined": 9001, 39 40 // How fast the cpu is hashing, in hashes per second. 41 "cpuhashrate": 1337, 42 43 // true if the cpu miner is active. 44 "cpumining": false, 45 46 // Number of mined blocks that are stale, indicating that they are not 47 // included in the current longest chain, likely because some other block at 48 // the same height had its chain extended first. 49 "staleblocksmined": 0, 50 } 51 ``` 52 53 #### /miner/start [GET] 54 55 starts a single threaded cpu miner. Does nothing if the cpu miner is already 56 running. 57 58 ###### Response 59 standard success or error response. See 60 [API.md#standard-responses](/doc/API.md#standard-responses). 61 62 #### /miner/stop [GET] 63 64 stops the cpu miner. Does nothing if the cpu miner is not running. 65 66 ###### Response 67 standard success or error response. See 68 [API.md#standard-responses](/doc/API.md#standard-responses). 69 70 #### /miner/header [GET] 71 72 provides a block header that is ready to be grinded on for work. 73 74 ###### Byte Response 75 76 For efficiency the header for work is returned as a raw byte encoding of the 77 header, rather than encoded to JSON. 78 79 Blocks are mined by repeatedly changing the nonce of the header, hashing the 80 header's bytes, and comparing the resulting hash to the target. The block with 81 that nonce is valid if the hash is less than the target. If none of the 2^64 82 possible nonces result in a header with a hash less than the target, call 83 `/miner/header [GET]` again to get a new block header with a different merkle 84 root. The above process can then be repeated for the new block header. 85 86 The other fields can generally be ignored. The parent block ID field is the 87 hash of the parent block's header. Modifying this field will result in an 88 orphan block. The timestamp is the time at which the block was mined and is set 89 by the Sia Daemon. Modifying this field can result in invalid block. The merkle 90 root is the merkle root of a merkle tree consisting of the timestamp, the miner 91 outputs (one leaf per payout), and the transactions (one leaf per transaction). 92 Modifying this field will result in an invalid block. 93 94 | Field | Byte range within response | Byte range within header | 95 | --------------- | -------------------------- | ------------------------ | 96 | target | [0-32) | | 97 | header | [32-112) | | 98 | parent block ID | [32-64) | [0-32) | 99 | nonce | [64-72) | [32-40) | 100 | timestamp | [72-80) | [40-48) | 101 | merkle root | [80-112) | [48-80) | 102 103 ``` 104 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (returned bytes) 105 tttttttttttttttttttttttttttttttt (target) 106 hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh (header) 107 pppppppppppppppppppppppppppppppp (parent block ID) 108 nnnnnnnn (nonce) 109 ssssssss (timestamp) 110 mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm (merkle root) 111 ``` 112 113 #### /miner/header [POST] 114 115 submits a header that has passed the POW. 116 117 ###### Request Body Bytes 118 119 For efficiency headers are submitted as raw byte encodings of the header in the 120 body of the request, rather than as a query string parameter or path parameter. 121 The request body should contain only the 80 bytes of the encoded header. The 122 encoding is the same encoding used in `/miner/header [GET]` endpoint. Refer to 123 [#byte-response](#byte-response) for a detailed description of the byte 124 encoding.