Skip to content

Commit c596f52

Browse files
committed
quantus: add mining protocols and durable finalized payouts
Support native QUIC and LuckyPool TCP/TLS miners with Poseidon2 verification, shared accounting, and connection lifecycle handling. Add exact-unit PROP/SOLO settlement, ML-DSA signed payouts, durable retry recovery, and payment status reporting. Validate against quantus-node 1.0.1 and official quantus-miner 4.2.0: 128 finalized pool blocks, a 1.23 QTC transfer, and crash recovery without duplicate debit. Include reproducible setup, regression tests, and the development-chain E2E runner.
1 parent a441717 commit c596f52

44 files changed

Lines changed: 5178 additions & 54 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
.idea
22
config.json
33
*.log
4+
node_modules/

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ Bitcoin, a pluggable `engine.Engine` reuses everything except node interaction
4747
| `ergo` | Ergo (Autolykos2) | *(default)* | pure Go (powkit + REST) |
4848
| `beam` | Beam (BeamHash III) | *(default)* | pure Go; TLS-JSON client transport |
4949
| `alephium` | Alephium (Blake3) | *(default)* | pure Go; binary protocol, multi-chain |
50+
| `quantus` | Quantus (QTC / Poseidon2) | *(default)* | QUIC + LuckyPool TCP/TLS; fixed difficulty; finalized PROP/SOLO payouts |
5051
| `ethash` | Ethereum Classic … | `-tags ethash` | go-etchash + go-ethereum |
5152
| `randomx` | Monero (CryptoNote) | `-tags randomx` | cgo; prebuilt lib in go-randomx |
5253
| `kaspa` | Kaspa (kHeavyHash) | `-tags kaspa` | kaspad gRPC + consensus |
@@ -78,6 +79,10 @@ Copy `config.example.json` to `config.json`, edit the `daemons`, `poolAddress`,
7879
Engine coins add an `"engine"` field (e.g. `"engine": "ethash"`); GBT coins omit
7980
it (or use `"gbt"`). Per-engine example configs live under `engine/<name>/`.
8081

82+
For Quantus, see the [configuration and miner instructions](engine/quantus/README.md).
83+
It supports the official miner and SRBMiner-Multi through native QUIC and
84+
LuckyPool Quantus Stratum over TCP/TLS.
85+
8186
## Testing
8287

8388
- **Unit tests** (hermetic): `go test -short ./...`, and with every engine tag:

‎api/server.go‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,20 @@ func (s *Server) RegisterFunc(path string, fn func(http.ResponseWriter, *http.Re
6666
s.availablePaths = append(s.availablePaths, path)
6767
}
6868

69+
// RegisterPaymentStatus allows non-Bitcoin engines to expose exact-unit balances
70+
// and finalized receipts without serializing wallet configuration or signed bytes.
71+
func (s *Server) RegisterPaymentStatus(status func() (interface{}, error)) {
72+
s.RegisterFunc("/payments", func(w http.ResponseWriter, r *http.Request) {
73+
v, err := status()
74+
if err != nil {
75+
http.Error(w, "payment status unavailable", http.StatusServiceUnavailable)
76+
return
77+
}
78+
w.Header().Set("Content-Type", "application/json")
79+
_ = json.NewEncoder(w).Encode(v)
80+
})
81+
}
82+
6983
func (s *Server) Serve() {
7084
addr := s.apiConf.Addr()
7185
log.Warn("API server listening on ", addr)

‎cmd/nomp/engines_quantus.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
package main
2+
3+
import _ "github.com/mining-pool/not-only-mining-pool/engine/quantus"

‎config/options.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ type Options struct {
1111
// Engine selects the mining-model engine. Empty or "gbt" (default) is the
1212
// built-in Bitcoin getblocktemplate flow. Other values (e.g. "ethash") name
1313
// a pluggable engine.Engine — see docs/PLUGGABLE_ENGINES_zh.md.
14-
Engine string `json:"engine"`
14+
Engine string `json:"engine"`
15+
Quantus *QuantusOptions `json:"quantus,omitempty"`
1516

1617
PoolAddress *Recipient `json:"poolAddress"`
1718
RewardRecipients []*Recipient `json:"rewardRecipients"`

‎config/quantus.go‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
package config
2+
3+
// QuantusOptions describes the node's external-miner endpoint (UDP/QUIC).
4+
// Pool-facing miner certificates are configured with ports.<port>.tls.
5+
type QuantusOptions struct {
6+
NodeAddress string `json:"nodeAddress"`
7+
AuthTokenFile string `json:"authTokenFile"`
8+
TLSCertSHA256File string `json:"tlsCertSHA256File"`
9+
Payments *QuantusPaymentOptions `json:"payments,omitempty"`
10+
}
11+
12+
// Amounts are decimal strings in base units (1 QTC = 10^12 base units).
13+
// The signing wallet must be dedicated to this pool and funded separately from
14+
// the node's wormhole mining-reward address.
15+
type QuantusPaymentOptions struct {
16+
RPCURL string `json:"rpcUrl"`
17+
GenesisHash string `json:"genesisHash"`
18+
RewardAddress string `json:"rewardAddress"`
19+
WalletScript string `json:"walletScript"`
20+
SeedFile string `json:"seedFile"`
21+
MinPaymentUnits string `json:"minPaymentUnits"`
22+
ReserveUnits string `json:"reserveUnits"`
23+
}

‎config/stratum.go‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
package config
22

33
type PortOptions struct {
4-
Diff float64 `json:"diff"`
5-
VarDiff *VarDiffOptions `json:"varDiff"`
6-
TLS *TLSServerOptions `json:"tls"`
4+
// Protocol selects a Quantus miner transport: "quic" (default) or "stratum".
5+
Protocol string `json:"protocol,omitempty"`
6+
Diff float64 `json:"diff"`
7+
VarDiff *VarDiffOptions `json:"varDiff"`
8+
TLS *TLSServerOptions `json:"tls"`
79
}

‎docs/PLUGGABLE_ENGINES.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,17 @@ as the reference implementation.
4848

4949
## Engine status
5050

51+
### Quantus — QTC (`engine/quantus/`, default build)
52+
53+
Native QUIC (`quantus-miner/2`) connects to the node with token authentication
54+
and certificate pinning. Miner ports select QUIC or LuckyPool Quantus Stratum
55+
over TCP/TLS, supporting the official miner and SRBMiner-Multi concurrently.
56+
Pure Go Poseidon2 verifies 512-bit nonces and strict U512 targets. The per-port
57+
dialects reuse shared clients and accounting, with per-session Stratum nonce
58+
prefixes. Uses fixed integer share difficulty. PROP/SOLO payouts use finalized
59+
chain events and an independently funded signing wallet. See
60+
[setup, protocol and validation limits](../engine/quantus/README.md).
61+
5162
Every engine below is **end-to-end validated on a real node** in CI — see
5263
[E2E.md](E2E.md). "Pure Go" engines are in the default build; heavy ones are behind
5364
build tags so the default binary stays lean.

‎docs/PLUGGABLE_ENGINES_zh.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -383,3 +383,16 @@ PoW 用 powkit BeamHash III 校验 40 字节头(input‖nonce)+104 字节解,*
383383
出块 blockBlob = `nonce24‖headerBlob‖txsBlob` 经 `SubmitBlock(0x00)` 回传。
384384
- 多链:`JobParamsForDifficulty` 一次返回全部链 job 的数组,`OnSubmit` 按 jobId 定位链。
385385
- 待实机:alephium-node miner API + 支持 ALPH 的矿机;矿机侧 notify 字段顺序需与目标矿机对齐。
386+
387+
## 15. Quantus(QTC / Poseidon2)
388+
389+
默认构建包含 `engine: "quantus"`。节点端使用 `quantus-miner/2` QUIC
390+
协议;矿池校验节点证书指纹,以节点令牌完成握手。矿工端可同时开启
391+
QUIC 与 LuckyPool Quantus TCP/TLS 端口,支持官方矿工及 SRBMiner-Multi。
392+
纯 Go PoW 校验已通过官方 5 组测试向量,原生矿工消息经适配器复用共享
393+
客户端和 share 记账。每次 share 提交后续发任务,节点断线后清理旧任务并重连。
394+
395+
各端口使用固定整数难度,Stratum 任务保留每个会话的 nonce 前缀。
396+
支持 PROP / SOLO 自动支付,使用最终确认事件和独立签名钱包;
397+
成功发送 seal 后仍需等待链上确认。完整配置、矿工命令和验证范围见
398+
[Quantus 接入说明](../engine/quantus/README.md)。

‎docs/QUANTUS_E2E.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Quantus end-to-end validation
2+
3+
Validated on 2026-09-12, macOS ARM64, using an isolated local development chain.
4+
No mainnet funds or external mining pool were used.
5+
6+
| Component | Version |
7+
|---|---|
8+
| quantus-node | 1.0.1, `f1176cea6a6` |
9+
| Official quantus-miner | 4.2.0, four CPU workers |
10+
| Quantus signing library | 0.3.0, source `539e3474e14d0dd5c2039c95e77e996e9d12bf93` |
11+
| Accounting | Redis AOF, `appendfsync always` |
12+
13+
The reproducible run confirmed **128 pool blocks**. A previously unendowed
14+
recipient received **1,230,000,000,000 base units (1.23 QTC)**, exactly matching
15+
the finalized payment ledger.
16+
17+
Payment transaction:
18+
`0xe55ba877fe7fa764530c513235af1781d8473812d2178a5658e49b14077da819`
19+
20+
The transaction was included at block **114**. The test killed the pool with a
21+
persisted, unconfirmed signed payment and restarted it against the same Redis.
22+
It recovered the same transaction, observed finalized `ExtrinsicSuccess`, and
23+
debited the balance exactly once. Repeated scans did not create another receipt.
24+
This transaction exists only on the temporary development chain.
25+
26+
Other checks covered real TCP login/share submission, invalid address rejection,
27+
duplicate and malformed nonce rejection, the official miner's QUIC transport,
28+
Poseidon2 block verification, finalized reward attribution, an ML-DSA signed
29+
`utility.batchAll` transfer, and payment API redaction.
30+
31+
Run after [installing the signing bridge](../engine/quantus/README.md#自动支付):
32+
33+
```sh
34+
python3 scripts/e2e/quantus.py \
35+
--node /path/to/quantus-node \
36+
--miner /path/to/quantus-miner
37+
```
38+
39+
The script writes logs and `result.json` to a new temporary directory and stops
40+
only the processes it starts. Each run uses different ports and block hashes.
41+
42+
SRBMiner GPU binaries, production throughput, and wormhole reward collection
43+
were not exercised. The payout wallet was funded by the development genesis;
44+
production reward collection requires the official CLI and its ZK/indexer services.

0 commit comments

Comments
 (0)