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