Pool operator reference

How to fetch work from a KRNX node, hand it to kHeavyHash miners, take a share back and submit a network solution. Self-contained. This guide covers only the public mining interface of the KRNX main chain. A pool obtains the node-selected kHeavyHash pre-image through krnx_getWork and returns a nonce through krnx_submitWork. The pool does not need to identify how the template was produced: treat its fields as opaque and use them unchanged. The main-chain proof of work is kHeavyHash: two cSHAKE256 passes, a 64×64 matrix, and a little-endian result comparison. A miner that supports this algorithm can mine KRNX without changing its hashing implementation. Two rules break an integration if you do not account for them:

getWork()[10] always contains milliseconds: parse the hex as uint64 and pass it without any further unit conversion. Section 4.
Share difficulty and consensus difficulty are different scales, exactly 2^32 apart. Section 5.

1. What the node must provide

Your own KRNX node with HTTP-RPC and template production enabled:

krnxd --http --http.api eth,krnx,net,web3 --http.addr 127.0.0.1 --http.port 8545 \
      --mine --miner.threads 0 --miner.etherbase 0xYOUR_ADDRESS --miner.recommit 3s

Flag	Why
`--mine`	without it the node builds no pending block and `getWork` errors
`--miner.threads 0`	disables the node’s own CPU mining while templates keep being built
`--miner.etherbase`	the address the block reward is credited to
`--miner.recommit`	how often the template is rebuilt (3s by default)
`--miner.notify URL`	optional: the node POSTs new work to the pool itself

The reward goes to the node’s etherbase, not to the stratum login. The login is only an accounting label; payouts are the pool’s own business. Three RPC methods, nothing else:

Method	Returns
`krnx_getWork`	an array of 11 strings — the work
`krnx_submitWork(nonce, powHash, mixDigest)`	`true` / `false`
`krnx_submitHashrate(rate, id)`	`true` (optional, for the node’s stats)

All three are mirrored in the eth_ namespace (eth_getWork, eth_submitWork) — the names match stock krnxd, so existing ethash pool code only needs its hashing swapped out.

2. `krnx_getWork`

curl -sS -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"krnx_getWork","params":[]}' \
  http://127.0.0.1:8545 | jq -r '.result[0,2,3]'

0x7bbec5a103d39fcd618e0233e6b872f8b1824f4e4d326ae5a4ef35f7736b3f9f
0x000005f67467c79dc2c3a72af48c650090096beaedfae8c63e25a35f67d59763
0xe193

Eleven strings. A pool needs four of them:

Index	What it is	Needed
`[0]`	node-selected PRE_POW_HASH	yes
`[1]`	DAG seed hash — always zero, kHeavyHash has no DAG	no
`[2]`	exact target of the current work	yes
`[3]`	block number	yes (logs, staleness)
`[4]`	parent hash	no
`[5]`–`[8]`	gas limit, gas used, transaction count, uncle count	no
`[9]`	service RLP of the retained KRNX candidate; a standard integration does not use it	no
`[10]`	exact pre-image TIME as `uint64` milliseconds	yes

Work is new when [0] changes. Everything else in the header is already folded into that hash. If the node is not mining or is still syncing, the method returns an error. That is normal: wait, and do not close the stratum port.

Push instead of polling

With --miner.notify http://pool:1234/work, the node POSTs the selected JSON work array whenever the template changes. Polling krnx_getWork every 200–500 ms is a practical alternative. --miner.notify.full carries the KRNX header and does not implement this work-array contract, so use the ordinary array or polling.

3. The kHeavyHash pre-image

KRNX uses this fixed pre-image:

                 32 bytes              8 bytes       32 bytes        8 bytes
       ┌──────────────────────┬───────────────┬──────────────┬───────────────┐
       │   PRE_POW_HASH       │  TIME u64 LE  │  zero bytes  │ NONCE u64 LE  │
       └──────────────────────┴───────────────┴──────────────┴───────────────┘
        = krnx_getWork()[0]     = getWork()[10]  fixed 32       the miner's
                               (milliseconds)    zero bytes     search space

Then:

first = cSHAKE256(data, customization="ProofOfWorkHash") → 32 bytes.
matrix = generate(PRE_POW_HASH) — a 64×64 matrix of 4-bit values from xoshiro256++ seeded with the seal hash, regenerated until its rank (float64 Gaussian elimination, eps = 1e-9) reaches 64.
mixed[i] = first[i] XOR (product[2i]<<4 | product[2i+1]), where product[i] = (Σ matrix[i][j] * vector[j]) >> 10 and vector holds the nibbles of first.
final = cSHAKE256(mixed, customization="HeavyHash") → 32 bytes.
The PoW value is final read little-endian. A block is solved when that value is <= the target.

The matrix depends on the seal hash alone: compute it once per work package, then roll only the nonce.

Golden vector

Every implementation must reproduce exactly this:

PRE_POW_HASH  0x37a01e19f6d0f7bd2b95bb45f4d1a5da5cbccdca4c1652deb3a4116ad4d0a4f1
TIME          1784505600000
NONCE         0x123456789abcdef0
pow value     83ded1da88cb9ea8206453b798ce02e6414e43965c1a491f979edd98b4942663

The node pins the same vector in TestKHeavyHashPowValueGolden (consensus/kheavyhash/kheavyhash_test.go). Every example in section 10 is checked against it.

4. The timestamp: always milliseconds

work[10] always contains the exact uint64 TIME placed in the kHeavyHash pre-image, in milliseconds. KRNX Header.Time itself remains in seconds for the EVM, DAA, reward lockups, and every other chain rule, but a pool must not derive PoW time from the header or convert units itself. A miner parses [10] as a 64-bit integer and places it in the pre-image exactly as received. Multiplication, division, or storage in uint32 changes or truncates the pre-image, so the node rejects the resulting solutions. The rule is: send exactly the numeric value from work[10] without unit conversion.

Where to get it

Use only work[10], the hex-encoded numeric millisecond value:

"0x1a038152528"  ->  1787647305000

work[9] contains a second-based KRNX header.Time, but it is a different field with a different purpose. Do not compare it with [10] or use it to identify a work type. The standard three-parameter krnx_submitWork path requires no such classification.

Do not roll TIME

A pool must not roll TIME along with the nonce. work[0] and work[10] form one immutable job. Fetch a new template to obtain a new time.

5. Difficulty: two scales

Scale	Target	Used by
Network target	exact value for the current work	the node, `getWork()[2]`
Stratum	(2^224 − 1) / difficulty	miners, `mining.set_difficulty`

Stratum difficulty 1 is worth about 2^32 hashes. Hence:

difficulty_stratum = difficulty_consensus / 2^32
share_target       = (2^224 - 1) / share_difficulty
hashes_per_share   = share_difficulty * 2^32

Confusing the two is a factor of 2^32 in the books: either miner hashrate reads four billion times too low, or shares arrive in a flood the pool never sized for. For example, a network difficulty of 4.3·10^12 is 1000 on the miner scale, and a difficulty-125 share costs roughly 5.4·10^11 hashes. Rules that hold wherever the chain’s difficulty happens to sit:

Do not hard-code the starting difficulty — derive the band from the current network difficulty: start at netdiff/8, floor at netdiff/4096, ceiling at netdiff.
The ceiling is the netdiff derived from [2]: above it every share is already a network solution, and the pool goes blind to a miner that produces nothing.
A share that solves a block is always accepted, even when it misses the current vardiff bound.

Miner hashrate is estimated as usual: Σ (share_difficulty * 2^32) / elapsed.

6. KRNX Stratum interface

Example full exchange:

miner -> {"id":1,"method":"mining.subscribe","params":["GMiner/3.28"]}
pool  -> {"id":1,"result":[true,"EthereumStratum/1.0.0"],"error":null}
miner -> {"id":2,"method":"mining.authorize","params":["krnx.rig1","x"]}
pool  -> {"id":2,"result":true,"error":null}
pool  -> {"id":null,"jsonrpc":"2.0","method":"mining.set_extranonce","params":["0001",6]}
pool  -> {"id":null,"jsonrpc":"2.0","method":"mining.set_difficulty","params":[0.0000816]}
pool  -> {"id":1,"jsonrpc":"2.0","method":"mining.notify",
          "params":["1",[4581632339856567309,5783595065747121291,
                         6077351350858350511,17714875238603159769],1787647640000]}
miner -> {"id":3,"method":"mining.submit","params":["krnx.rig1","1","0001000000000527"]}
pool  -> {"id":3,"result":true,"error":null}

Message	Rule
`mining.subscribe`	reply exactly `[true,"EthereumStratum/1.0.0"]`; `params[0]` is the user agent and decides the job format
`mining.authorize`	reply `true`; the `user.worker` login is an accounting label
`mining.set_extranonce`	`[hex prefix, how many nonce bytes the miner keeps]`
`mining.set_difficulty`	`[float]` on the scale from section 5
`mining.notify`	`[jobId, [4×uint64], timestamp]`
`mining.submit`	`[worker, jobId, nonce hex]`, answered with `true` or a stratum error

Two job formats

Ordinary: the seal hash read as four little-endian uint64s:

words[i] = LE_uint64(seal_hash[i*8 : i*8+8])

The miner reassembles the same 32 bytes from them. The third parameter is the timestamp (section 4). Big job (BzMiner, IceRiver, Goldshell and several ASIC stacks): instead of the array and the time, a single 80-character hex string — the first 40 bytes of the pre-image:

hex(seal_hash) + hex(timestamp as u64 LE)

Which format to use is decided by a regex on the mining.subscribe user agent.

Extra nonce

The prefix occupies the high bytes of the 64-bit nonce; the miner rolls the rest. Two prefix bytes give 65536 connections and 48 bits of search space each. Never hand out more than three: an ASIC exhausts what is left in a fraction of a second. On submit a miner sends either all eight bytes (0x0001000000000527) or only its own part (000000000527). When fewer than 16 - len(prefix) hex characters arrive, the pool prepends the prefix itself.

7. Submitting a block

curl -sS -H 'Content-Type: application/json' --data '{
  "jsonrpc":"2.0","id":2,"method":"krnx_submitWork","params":[
    "0x0001000000000527",
    "0x7bbec5a103d39fcd618e0233e6b872f8b1824f4e4d326ae5a4ef35f7736b3f9f",
    "0x0000000000000000000000000000000000000000000000000000000000000000"
  ]}' http://127.0.0.1:8545

Parameter	Rule
`nonce`	8 bytes, big-endian hex — precisely the 64-bit number the miner hashed
`powHash`	`getWork()[0]` of the work the nonce was found against, byte for byte
`mixDigest`	always 32 zero bytes. kHeavyHash has no mix; a non-zero one is rejected by consensus

The answer is true when the node accepts the solution for processing, or false. A successful response alone does not mean that the KRNX height has already changed. false means one of:

the node no longer holds work with that powHash — a stale;
the PoW misses the target — the pool and the node disagree on the pre-image, most often the timestamp;
the block is too old relative to the current height.

The method has a legacy fourth-parameter variant that changes the header’s Extra. It is outside the universal public contract: some node-selected templates are immutable, so an external pool should always use the ordinary three-parameter call. Do not tie the submission to the miner’s socket: a miner may drop the connection right after solving, and the block still has to go out. Ask for fresh work immediately after a submit — the template is spent either way.

8. Splitting work across connections

The universal method is to partition the 64-bit nonce space. The pool assigns a unique high-byte prefix through mining.set_extranonce, and the miner scans the remaining low bits. Connections may share one PRE_POW_HASH while searching disjoint nonce sets. A two-byte prefix provides 65,536 independent 48-bit spaces. Keep the assigned prefix with the connection, reconstruct the full 64-bit nonce on mining.submit, and send it through the ordinary three-parameter krnx_submitWork call. This works for every job selected by the node. The public RPC does not currently guarantee a distinct PRE_POW_HASH per connection; that requires node-side issuance of derived jobs.

9. What you may and may not change

Free:

What	Bounds
nonce	all 64 bits, minus the extra-nonce prefix bytes
share difficulty	your own vardiff, see section 5
job format	ordinary or big job, per user agent

Not allowed:

What	Result
multiplying or dividing the timestamp by 1000	every solution rejected
rolling the timestamp	a different seal hash, i.e. work the node never issued
a non-zero `mixDigest`	`errInvalidMixDigest`
changing fields from `[9]` or passing a fourth submit parameter	the template may be immutable and the solution will be rejected
altering `powHash` on submit	”Work submitted but none pending”
share difficulty above the block difficulty	every share is a block, miner stats go blind

10. Code examples

Complete working clients (fetch work → decode the timestamp → compute difficulty → scan nonces → submit a block) live in docs/examples/kheavyhash-pool/. All of them are checked against the golden vector from section 3 and run against a live node.

Language	Directory	Scan rate (M1, single thread)
Go	`go/`	≈ 265 kH/s
Node.js	`node/`	≈ 52 kH/s
Rust	`rust/`	≈ 580 kH/s (release)
Python	`python/`	≈ 4 kH/s

Python and Node.js are fast enough to validate an integration, not to hash for real. Below is the core of each implementation: building the pre-image and both cSHAKE256 passes.

10.1 Go

// PowValue hashes PRE_POW_HASH || TIME || 32 zero bytes || NONCE and reads the
// result little-endian, exactly like the node.
func PowValue(matrix *Matrix, prePowHash [32]byte, timestamp, nonce uint64) *big.Int {
	var pre [80]byte
	copy(pre[:32], prePowHash[:])
	binary.LittleEndian.PutUint64(pre[32:40], timestamp)
	binary.LittleEndian.PutUint64(pre[72:80], nonce)

	first := cshake256("ProofOfWorkHash", pre[:])
	final := matrix.heavyHash(first)
	for i, j := 0, len(final)-1; i < j; i, j = i+1, j-1 {
		final[i], final[j] = final[j], final[i]
	}
	return new(big.Int).SetBytes(final[:])
}

func cshake256(domain string, data []byte) [32]byte {
	hasher := sha3.NewCShake256(nil, []byte(domain)) // golang.org/x/crypto/sha3
	hasher.Write(data)
	var out [32]byte
	hasher.Read(out[:])
	return out
}

Targets and scales:

var stratumDiffOneTarget = new(big.Int).Sub(new(big.Int).Lsh(big.NewInt(1), 224), big.NewInt(1))

// the share target for a stratum difficulty
func difficultyToTarget(difficulty float64) *big.Int {
	target, _ := new(big.Float).Quo(new(big.Float).SetInt(stratumDiffOneTarget), big.NewFloat(difficulty)).Int(nil)
	return target
}

// network difficulty on the miner scale: 2^256/D against (2^224-1) is D/2^32
func stratumDifficulty(blockTarget *big.Int) float64 {
	value, _ := new(big.Float).Quo(new(big.Float).SetInt(stratumDiffOneTarget), new(big.Float).SetInt(blockTarget)).Float64()
	return value
}

Inside the node the algorithm is already exported, so a Go pool living in this repository does not reimplement it:

job := kheavyhash.NewKHeavyHashJob(sealHash)        // the matrix, computed once
value := job.PowValue(powTimestampMs, nonce)        // work[10], pre-image plus both passes
target := kheavyhash.KHeavyHashTarget(difficulty)   // 2^256/difficulty

10.2 Node.js

const { cshake256 } = require('js-sha3');

// PRE_POW_HASH || TIME || 32 zero bytes || NONCE -> pow value as a BigInt
function powValue(matrix, prePowHash, timestamp, nonce) {
  const pre = new Uint8Array(80);
  pre.set(prePowHash, 0);
  new DataView(pre.buffer).setBigUint64(32, BigInt(timestamp), true); // LE
  new DataView(pre.buffer).setBigUint64(72, BigInt(nonce), true);     // LE

  const first = cshake('ProofOfWorkHash', pre);
  const final = heavyHash(matrix, first);

  let value = 0n; // little-endian reading
  for (let i = 31; i >= 0; i--) value = (value << 8n) | BigInt(final[i]);
  return value;
}

function cshake(domain, data) {
  return Uint8Array.from(Buffer.from(cshake256(data, 256, '', domain), 'hex'));
}

10.3 Rust

Own implementation on the sha3 crate:

use sha3::digest::{ExtendableOutput, Update, XofReader};
use sha3::{CShake256, CShake256Core};

/// PRE_POW_HASH || TIME || 32 zero bytes || NONCE, returned big-endian.
pub fn pow_value(matrix: &Matrix, pre_pow_hash: &[u8; 32], timestamp: u64, nonce: u64) -> [u8; 32] {
    let mut pre = [0u8; 80];
    pre[..32].copy_from_slice(pre_pow_hash);
    pre[32..40].copy_from_slice(&timestamp.to_le_bytes());
    pre[72..80].copy_from_slice(&nonce.to_le_bytes());

    let first = cshake256(b"ProofOfWorkHash", &pre);
    let mut value = matrix.heavy_hash(first);
    value.reverse(); // the node reads little-endian; reversed, it compares as a number
    value
}

fn cshake256(domain: &[u8], data: &[u8]) -> [u8; 32] {
    let mut hasher = CShake256::from_core(CShake256Core::new(domain));
    hasher.update(data);
    let mut out = [0u8; 32];
    hasher.finalize_xof().read(&mut out);
    out
}

10.4 Python

from Crypto.Hash import cSHAKE256   # pip install pycryptodome

def cshake256(domain: bytes, data: bytes) -> bytes:
    return cSHAKE256.new(data=data, custom=domain).read(32)

def pow_value(mat, pre_pow_hash: bytes, timestamp: int, nonce: int) -> int:
    """PRE_POW_HASH || TIME || 32 zero bytes || NONCE, read little-endian."""
    pre = pre_pow_hash + timestamp.to_bytes(8, "little") + bytes(32) + nonce.to_bytes(8, "little")
    first = cshake256(b"ProofOfWorkHash", pre)
    final = heavy_hash(mat, first)
    return int.from_bytes(final, "little")

Checking a whole work package:

work = call(rpc, "krnx_getWork")
seal_hash = bytes.fromhex(work[0][2:])
block_target = int(work[2], 16)
timestamp = int(work[10], 16)                   # exact uint64 milliseconds
network_diff = ((1 << 224) - 1) / block_target  # block difficulty on the miner scale
matrix = generate_matrix(seal_hash)
value = pow_value(matrix, seal_hash, timestamp, nonce)
solved = value <= block_target

11. Direct integration checklist

krnx_getWork answers, and [0] changes when the template does.
Your hasher reproduces the golden vector from section 3.
The timestamp comes from [10] as uint64 milliseconds without conversion.
mining.notify ships the seal hash such that a miner rebuilds exactly [0] from the four words.
Difficulty is set on the (2^224−1)/diff scale and below the block difficulty.
A share that solves a block is accepted even if it misses the vardiff bound.
krnx_submitWork returns true; the pool does not infer a new height from this response and tracks the next powHash separately.
The node’s rejection rate is near zero. If it is not, see section 12.

12. Diagnostics

Symptom	Cause
The node rejects every solution while shares keep coming	the pre-image diverged: `[10]` was converted, came from another work package, or the implementation misses the golden vector
`krnx_getWork` returns an error	the node runs without `--mine`, without an etherbase, or is still syncing
A miner connects and stays silent	share difficulty above the block difficulty (section 5) — every find leaves as a block
Many `false` answers from `krnx_submitWork` on valid shares	the template moved on: slow polling, or the miner works on stale jobs
”Work submitted but none pending” in the node log	the `powHash` on submit is not the one from the work package
The node logs `errInvalidMixDigest`	a non-zero `mixDigest` was submitted
Reported hashrate is orders of magnitude off	shares counted on the consensus scale instead of the stratum one (the gap is exactly 2^32)

Node

Mining

Build

Pool operator reference

1. What the node must provide

2. `krnx_getWork`

Push instead of polling

3. The kHeavyHash pre-image

Golden vector

4. The timestamp: always milliseconds

Where to get it

Do not roll TIME

5. Difficulty: two scales

6. KRNX Stratum interface

Two job formats

Extra nonce

7. Submitting a block

8. Splitting work across connections

9. What you may and may not change

10. Code examples

10.1 Go

10.2 Node.js

10.3 Rust

10.4 Python

11. Direct integration checklist

12. Diagnostics

​1. What the node must provide

​2. krnx_getWork

​Push instead of polling

​3. The kHeavyHash pre-image

​Golden vector

​4. The timestamp: always milliseconds

​Where to get it

​Do not roll TIME

​5. Difficulty: two scales

​6. KRNX Stratum interface

​Two job formats

​Extra nonce

​7. Submitting a block

​8. Splitting work across connections

​9. What you may and may not change

​10. Code examples

​10.1 Go

​10.2 Node.js

​10.3 Rust

​10.4 Python

​11. Direct integration checklist

​12. Diagnostics

1. What the node must provide

2. `krnx_getWork`

Push instead of polling

3. The kHeavyHash pre-image

Golden vector

4. The timestamp: always milliseconds

Where to get it

Do not roll TIME

5. Difficulty: two scales

6. KRNX Stratum interface

Two job formats

Extra nonce

7. Submitting a block

8. Splitting work across connections

9. What you may and may not change

10. Code examples

10.1 Go

10.2 Node.js

10.3 Rust

10.4 Python

11. Direct integration checklist

12. Diagnostics