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 or share)!

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 (see also rollntime extension).

Extensions

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

hostlist

Original specification from Deepbit

The server may include a X-Host-List header with a list of available servers formatted in JSON as an array of objects with server details. "host" specifies the server's hostname or IP address, "port" specifies a TCP port, and "ttr" is "time to return". If you use server with non-zero ttr you should try to return to the server with 0 ttr after this number of minutes.

Example:

X-Host-List: [{"host":"server.tld","port":8332,"ttr":0},{"host":"backup.tld","port":8332,"ttr":20}]

This string says that "server.tld" is the main server. When you detect connection problems, you need to try the next server - "backup.tld" for 20 minutes and then try to switch back to "server.tld". If the main server is still offline you should continue to use "backup.tld" for another 20 minutes.

Failover workflow:

1. Choose the first working server while cycling from left to right
2. if "ttr" of the server is greater than zero, go to 1) after this amount of minutes.

longpoll

Original specification from Deepbit

If mining pool does supports Long Polling, it should include a X-Long-Polling header with a relative or absolute URI. The absolute URI may specify a different port than the original connection. Miner must start a request to long polling URI with GET method and same basic authorization as on main connection. This request is not answered by server until it wishes to expire current block data, and new data is ready. The answer is the same as getwork on the main connection. Upon receiving this answer, miner should drop current calculation in progress, discard it's result, and start working on received data and make a new request to a long polling URI. There is a 60 second limit before new work should be requested (the normal way) regardless of response from longpoll (though this may be overridden by the rollntime extension below).

noncerange

noncerange discussion forum thread

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) given in big endian, miners should iterate over the range in little endian (as already passed to SHA256). The miner should implement rollntime by starting from the first nonce in the range 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

rollntime expiration discussion forum thread

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.

switchto

Original specification from Deepbit

The server may include a X-Switch-To header containing a single JSON object formatted in the same fashon as items in the hostlist array extension. If this header is present, the miner should switch to the specified server for at least ttr minutes after finishing current "getwork" and submitting its results.

Example:

X-Switch-To: {"host":"temporary.tld","port":8332,"ttr":10}