CEF changes

2017-03-17 18:57:20 -05:00
parent f647c45712
commit 5eecff152c
127 changed files with 1106 additions and 2210 deletions
--- a/3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Miner.md
+++ b/3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Miner.md
@@ -0,0 +1,124 @@
+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.