Mining protocol
How a miner talks to a node or a pool. Both speak the same JSON-RPC methods, getwork and submitwork, over HTTP; the pool adds a payee and a worker name. This is enough to write your own miner or mining proxy. The work itself is described in how TNet works.
getwork
{"method": "getwork", "params": ["<payee key hash>"], "id": 1}
The node builds a block template that pays the payee (and the development fund) and answers with:
| Field | Meaning |
|---|---|
height | height of the block being mined |
header | the 116-byte header, hex |
header_digest | the digest that inputs and tickets are derived from |
epoch_seed | seed of the epoch's weights; derive the weights once per epoch |
target | 256-bit target, big-endian hex; a ticket wins if its hash is at most this |
longpollid | identifies the current tip |
tnet | the work-function parameters: n, b, L, w, mult |
A pool answers with the share target in target, the real target in network_target, its share_bits and pool: true.
Mining an attempt
For each nonce, derive the input rows from header_digest and the nonce, push them through the eight layers with the epoch weights, and hash every 256-byte piece of every output row with the header digest, nonce, row and piece index. Any piece whose hash is at most target is a winning ticket (nonce, i, c, piece).
submitwork
{"method": "submitwork", "params": ["<header_digest>", nonce, i, c, "<piece hex>"], "id": 2}
The answer is {"accepted": true, "result": …} or {"accepted": false, "reason": "…"}. The node verifies the ticket hash against the target and then recomputes the row before accepting.
Pool extensions: a 6th parameter, the payee key hash, and a 7th, the worker name (up to 32 characters of A–Z a–z 0–9 . _ -). The pool credits the share to the payee and shows the worker on its statistics page.
Long polling
Pass the last longpollid as the second parameter of getwork:
{"method": "getwork", "params": ["<payee>", "<longpollid>"], "id": 3}
The call returns as soon as a new block arrives, or after at most 60 seconds with the current work. Nodes from 0.13.0 and pools from 0.14.0 support it; a client should fall back to polling once a second when the answer comes back immediately with the same id. Keep long-poll requests on their own connection with a timeout above 60 seconds; the pool allows 192 at once.
Practical rules
- Refresh work when the tip changes and at least every 60 seconds; jobs older than the tip are rejected (the pool accepts shares for the previous tip for 10 seconds).
- Derive the next epoch's weights before the epoch changes: epoch
eis seeded from the block 60 blocks before it begins. - Batch rows: single-row mining costs 42–51× more per ticket.
- Never submit a ticket for a tip you have left; count it as stale.
- Check your kernel against the test vectors before mining; nodes and pools reject every wrong piece.