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