Getwork

An RPC method used by a miner to get hashing work to try to solve.

Pseudocode

(Just ignore the midstate until you understand the internals of SHA256.)

calculate: hash = SHA256(SHA256(data))

If that meets the difficulty, you win (generated a block)!

If not, increment the [Nonce] that is a number stored in portion of the data that starts 640 bits in (bytes 76 to 79), and try again.

If the incremented portion overflows, get new work.

Extensions

When getting new work, miners should send a X-Mining-Extensions header with a space-delimited list of supported extensions:

noncerange

In addition to X-Mining-Extensions, the miner should also send X-Mining-Hashrate, with an integer value of expected hashrate measured in full hashes per second. The server may then add an additional field to the JSON response, "noncerange", which contains two 32-bit integers specifying the starting and final nonce the miner is allowed to scan. While both values are (as with the rest of the response) big endian, miners should iterate over the range in little endian (presently this is subject to revision). The miner should implement rollntime by starting from the first nonce every second.

Example:

"noncerange": "000000001fffffff"

reject-reason

NOTE: Clients should not need to advertise this feature in X-Mining-Extensions.

When a share is rejected, the server may include a X-Reject-Reason header indicating the reason why it was rejected. Values for this header are undefined.

rollntime

Iff the getwork response includes a "X-Roll-NTime" header, the miner may (within reason) change the ntime field in addition to the nonce. The server may send a value of "expire=<N>", where <N> is an integer number of seconds it is willing to accept the other headers for. Note that if the "X-Roll-NTime" header is NOT present in a work response, that work may NOT be rolled, even if earlier work from the same server allowed it. Also note that the headers of a share submission should not influence the behaviour of work-- specifically, if a share submit does not have the header, it should not disable rollntime for the current work (which did).

Due to network latency, Luke-Jr recommends the following design for miners:

1. getwork, record <duration of getwork request> and <time+getwork expire> , and begin mining on it
2. every second, update ntime and reset nonce to <first nonce>
3. when a share is found, submit it. record the duration of the submit request.
4. if a share submission fails due to a network error, save the share and retry it a second later the same as step 3; also immediately (regardless of how long the current work has been active) begin trying to get new work (which is treated the same as step 5+6 when done)
5. when current time is past <time@1+getwork expire> minus <duration of longest getwork/submit since we started this work> times 4, begin a request for new work
6. when new work arrives, discard old work and begin using the new work.