Mining endpoints

The Chainweb node mining API is disabled by default. You must enable and configure the mining API in the node configuration file before you can use any of the mining endpoints.

Use GET https://{baseURL}/mining/work to request a new block header to work on.

Use the following parameters to specify the miner information.

Requests to GET https://{baseURL}/minig/work return the following response codes:

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

If the request is successful, the response returns application/octet-stream content with the following:

If you have enabled mining, you can send a request for work like this:

The request body should contain parameters similar to the following:

If the request is successful, the response is an octet stream with:

Work bytes - (ChainBytes4 + TargetBytes32 + HeaderBytes286)

This is the minimum information required to perform proof-of-work validation. No knowledge of Chainweb internals is necessary. For information about the encoding of work bytes, see Binary encoding.

Use POST https://{basseURL}/mining/solved to submit a solution for a new block.

The request body should be application/octet-stream content with the solved proof-of-work work header bytes.

The solved proof-of-work binary string of 286 bytes should consist of the original work received from the /mining/work endpoint with updated nonce value such that it satisfies the proof-of-work puzzle. The nonce is defined in the last 8 bytes of the work header bytes.

The proof-of-work hash of a valid block is computed using blake2s. It must not be larger than the proof-of-work target for the current block. The target was received along with the work header bytes from the /mining/work endpoint. For arithmetic comparisons, the hash-target and the proof-of-work hash are interpreted as an unsigned 256-bit integral number in little endian encoding.

Miners can also update the creation time. However, the value must be strictly larger than the creation time of the parent block and must not be in the future.

Requests to POST https://{baseURL}/mining/solved return the following response codes:

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

If you have enabled mining, you can submit a proof-of-work solution like this:

The request body should be 286 bytes from the original work received from the /mining/work endpoint with updated the nonce. If the request is successful, you'll see the 204 No Content response returned.

Use GET https://{baseURL}/mining/updates to receive notifications from a server when new mining work becomes available.

This server-sent event stream is terminated by the server in regular intervals. It's the responsibility of the miner to periodically request a new stream.

The request body should be application/octet-stream content with the first four bytes—the chain identifier bytes—received from a call to the /mining/work endpoint. With this request body, Node only informs the miner of a new cut when the chain identified by the first four bytes has updated.

Requests to GET https://{baseURL}/mining/updates return the following response code:

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

If the request is successful, the response returns text/event-stream content with the following:

If you have enabled mining, you can request notification for chain updates like this:

The request body should be application/octet-stream content with the first four chain identifier bytes from a work header.

The server-send events look like this: