Mining integration

Tenrai mining has two interfaces. Miners speak stratum to a bridge or a pool. Bridges and pools get their work from a node's mining listener.

Writing mining software

Your miner needs to speak tenrai-mining-v1, JSON lines over TCP or TLS, or its binary form tenrai-mining-v2. The stratum reference has every message and field.

1. Subscribe with your agent name and an optional tag. The answer gives a nonce prefix, and a pool also names its address.
2. Authorize with <address>.<worker>.
3. Take jobs from mining.notify: a 312-byte header with a zeroed nonce, the block target and the share target.
4. Search: fill the nonce, keeping the server's prefix in its last bytes, and hash TRAI_POW_V1 plus the header with TenQ.
5. Submit a nonce whose value is at or below the share target.

TenQ is specified by its reference implementation in the node repository, crates/tenq, with test vectors and the GPU kernels the Tenrai miner uses. Start by reproducing the vectors.

Building a bridge or a pool

The reference pool and the stratum bridge are open source and the best place to start. Both take their work from the node's mining listener at http://127.0.0.1:28702:

The listener accepts only the same machine, so the bridge or pool runs next to its node.

A template keeps its transactions for 5 seconds and stays valid until its registration_window_end. The body does not depend on the reward lock: one template can serve many miners, each with its own header. A body must not be used for a second block.

Templates take transactions by fee rate. Among transactions at the same rate a node first takes those submitted to it, then those other nodes relayed. A relayed one counts like its own once it is one cut interval older than the oldest of the node's own that still waits. The node draws at random within each group, so blocks mined on different nodes at the same time rarely carry the same transaction, also while transactions queue.

Shares

Check every share against your own copy of the job, so a miner only ever sends a nonce. Verifying a share costs one TenQ hash; in full mode that needs the 2 GiB dataset on the server. Bound the checks per connection and overall, as the reference pool does, so junk shares cannot exhaust the CPU.

Rewards and payouts

• A pool's blocks pay the pool address. Read what each block earned from the node: GET /v1/blocks/{id} shows reward.state and the amounts, and every cut_finalized event lists the rewards the cut paid.
• A block's reward is final once it is paid. Finalized cuts never change, so there is no maturity period and no orphan handling after that point.
• A block that is not registered before its anchor's window closes earns nothing. Count it as expired.
• Pay miners through the wallet daemon with a request ID per payout, so a repeated call never pays twice.
• Block rewards arrive as many small outputs. Let the daemon compound them.

Mining from a web page

The bridge and the pool can offer tenrai-mining-v1 over WebSocket, one JSON-RPC line per text message:

The listener is plain; put a TLS proxy in front for pages served over HTTPS. tenrai-tenq-wasm from the node repository hashes on the CPU and prepares the tables for a WebGPU backend.

Miner tags

A miner may send a tag of up to 20 characters with mining.subscribe. The server writes it into the extranonce of the blocks it builds for that miner, and explorers show it. A pool can replace it with its own name. Allowed are letters, digits, spaces and . _ - / : + @ # ( ) !.