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.