Stratum protocol | Tenrai Docs

tenrai-mining-v1 is the stratum protocol of Tenrai. tenrai-mining-v2 carries the same session in binary frames over TLS. It borrows framing and channels from Stratum V2 but is not Stratum V2 and does not work with Stratum V2 software. The two protocols are TCC-0007 and TCC-0008 of the conventions.

V1 transport

Item	Value
Framing	TCP, one JSON message per line, `\n` or `\r\n`, at most 16 KiB a line
TLS	Optional. TLS 1.3 with the X25519MLKEM768 key exchange only, ALPN `tenrai-mining/1`
URL schemes	`stratum+tls://host:port`; `stratum+tcp://host:port` only on the same machine, the Tenrai miner refuses it for any other host

Text

request        {"id": <number or string>, "method": "…", "params": […]}
response       {"id": …, "result": <value>, "error": null}
error          {"id": …, "result": null, "error": [code, "message", null]}
notification   {"id": null, "method": "…", "params": …}

A miner ignores notifications it does not know and extra fields in known ones. A server answers unknown methods with code 20 and keeps the connection.

V1 session

Text

miner → server   mining.subscribe [agent, tag]
server → miner   {"protocol": "tenrai-mining-v1", "nonce_prefix": "<hex, at most 8 bytes>", "pool_address": "<address>"}
miner → server   mining.authorize [login, password]
server → miner   true
server → miner   mining.set_target [share target]
server → miner   mining.notify {job_id, header, target, share_target, registration_height, network, clean}
miner → server   mining.submit [worker, job_id, nonce]
server → miner   true, or an error

Only pools send pool_address.

Field	Meaning
`tag`	Up to 20 characters shown in explorers: letters, digits, spaces and `. _ - / : + @ # ( ) !`, no space at either end; empty for none
`login`	`<address>` or `<address>.<worker>`. Every block pays the address, except on a pool
`pool_address`	A pool's blocks pay this address and the pool credits the login address
`password`	The server's password; `d=<n>` or `<password>,d=<n>` asks for a fixed share difficulty
`header`	The 312-byte work header in hex, nonce all zero
`target`, `share_target`	32-byte big-endian targets in hex. The share target is never harder than `target`
`registration_height`	Finalized height of the work's anchor plus one
`network`	`mainnet`, `testnet`, `testnet100` or `development`

Work header

Offset	Bytes	Field
0	48	Chain ID
48	2	Header version, big-endian
50	1	Algorithm, `0x02` for TenQ
51	48	Work reference (anchor)
99	48	Parents root
147	48	Payload root
195	4	Payload length, big-endian
199	8	Payload mass, big-endian
207	41	Reward lock of the payout address
248	32	Nonce
280	32	Extranonce: tag length, tag, then bytes the server chose

Hashing

Item	Value
Preimage	ASCII `TRAI_POW_V1` followed by the header, 323 bytes. The nonce sits at bytes 259 to 290
Nonce	Its last `len(nonce_prefix)` bytes are the prefix from `mining.subscribe`; every other byte is the miner's
Epoch	`(registration_height - 1) / 34560`, rounded down
Profile	`0x54454E10`, the 2 GiB dataset, on mainnet and the testnets; `0x54454E01` on development
Hash	TenQ, seeded with the header's chain ID
Share	Value ≤ `share_target`, compared as unsigned 256-bit big-endian numbers
Block	Value ≤ `target`; the server submits it to the node
Difficulty	`D` stands for the target `floor(2^256 / D) - 1`. Difficulty 1 accepts every hash

Error codes

Code	Meaning	Miner reaction
20	Unsupported request
21	Stale job	Count as stale
22	Duplicate share
23	Above the share target
24	Unauthorized. A wrong password also closes the connection	Session ends
25	Rate limited
26	Malformed
27	No address of the server's network in the login	Session ends
28	Tag not allowed	Session ends
29	Banned for a while	Session ends, next server

V2 transport

Item	Value
Connection	TCP with TLS 1.3, X25519MLKEM768 only, ALPN `tenrai-mining/2`. There is no unencrypted V2
URL scheme	`stratum2+tls://host:port`
Frame	Extension type `u16`, message type `u8`, payload length `u24`, payload
Extension type	`0`; the top bit is set on channel messages, whose payload starts with the channel ID
Payload	At most 16 KiB
Numbers	Little-endian `u16`, `u32`, `u64`
`bool`	One byte, `0` or `1`
`str`	`u8` length and UTF-8, at most 255 bytes
`bytes`	`u8` length and bytes; `bytes64k` has a `u16` length
`[n]`	Exactly `n` bytes. Targets are big-endian numbers as in V1

A server closes the connection on a malformed or unknown message, a message out of order, or a frame over the limit. A miner ignores message types it does not know.

V2 messages

Type	Name	Direction	Fields
`0x00`	SetupConnection	miner → server	`agent str`, `tag str`
`0x01`	SetupConnection.Success	server → miner	`nonce_prefix bytes` (at most 8), `pool_address str` (empty unless a pool)
`0x02`	SetupConnection.Error	server → miner	`code u16`, `message str`
`0x04`	Reconnect	server → miner	`host str` (empty: same host), `port u16` (`0`: same port)
`0x10`	OpenChannel	miner → server	`request_id u32`, `login str`, `password str`
`0x11`	OpenChannel.Success	server → miner	`request_id u32`, `channel_id u32`
`0x12`	OpenChannel.Error	server → miner	`request_id u32`, `code u16`, `message str`
`0x15`	NewJob	server → miner, channel	`channel_id u32`, `job_id [48]`, `header bytes64k`, `share_target [32]`, `target [32]`, `registration_height u64`, `network str`, `clean bool`
`0x1a`	SubmitShare	miner → server, channel	`channel_id u32`, `sequence_number u32`, `job_id [48]`, `nonce [32]`
`0x1c`	SubmitShares.Success	server → miner, channel	`channel_id u32`, `last_sequence_number u32`, `accepted u32`
`0x1d`	SubmitShares.Error	server → miner, channel	`channel_id u32`, `sequence_number u32`, `code u16`, `message str`
`0x21`	SetTarget	server → miner, channel	`channel_id u32`, `share_target [32]`

V2 session

Step	V1 equivalent
SetupConnection first, once. The answer carries the nonce prefix and a pool's address	`mining.subscribe`
OpenChannel; one channel per connection	`mining.authorize`
SetTarget and NewJob	`mining.set_target`, `mining.notify`
SubmitShare with a sequence number that grows by one per share	`mining.submit`
SubmitShares.Success accepts every unanswered share up to `last_sequence_number`; SubmitShares.Error rejects one	`true` or an error
Reconnect before the server stops. A miner follows it to the same host only

Fields, hashing, targets and codes are those of V1.