Skip to content

Commit dbfed90

Browse files
committed
Merge payment into master: Quantus mining and payouts
2 parents 71eb50d + 9ed9098 commit dbfed90

44 files changed

Lines changed: 5213 additions & 59 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: 40 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ A standalone, high-performance Stratum mining-pool server written in Go.
55
It started as a pool for **Bitcoin Core (`bitcoind`) variants** — any coin whose
66
proof-of-work is a hash of the standard 80-byte block header — and now also ships
77
**pluggable mining engines** for coins with entirely different mining models
8-
(Ethash, RandomX, KawPow, kHeavyHash, Equihash, Autolykos2, BeamHash III, Blake3).
8+
(Ethash, RandomX, KawPow, kHeavyHash, Equihash, Autolykos2, BeamHash III, Blake3,
9+
Poseidon2).
910

1011
> Docs: [Tutorial](TUTORIAL.md) · [Pluggable engines](docs/PLUGGABLE_ENGINES.md) ·
1112
> [End-to-end testing](docs/E2E.md)
@@ -33,7 +34,7 @@ Built-in algorithms: `sha256`, `sha256d`, `scrypt`, `x11`, `keccak`, `groestl`,
3334
`algorithm.RegisterHash` — see the [tutorial](TUTORIAL_zh.md). Ready-to-use coin
3435
templates live in [`coins/`](coins/).
3536

36-
### Pluggable engines (opt-in via build tags)
37+
### Pluggable engines
3738

3839
For coins whose block structure, PoW verification and Stratum dialect differ from
3940
Bitcoin, a pluggable `engine.Engine` reuses everything except node interaction
@@ -47,6 +48,7 @@ Bitcoin, a pluggable `engine.Engine` reuses everything except node interaction
4748
| `ergo` | Ergo (Autolykos2) | *(default)* | pure Go (powkit + REST) |
4849
| `beam` | Beam (BeamHash III) | *(default)* | pure Go; TLS-JSON client transport |
4950
| `alephium` | Alephium (Blake3) | *(default)* | pure Go; binary protocol, multi-chain |
51+
| `quantus` | Quantus (QTC / Poseidon2) | *(default)* | QUIC + LuckyPool TCP/TLS; fixed difficulty; finalized PROP/SOLO payouts |
5052
| `ethash` | Ethereum Classic … | `-tags ethash` | go-etchash + go-ethereum |
5153
| `randomx` | Monero (CryptoNote) | `-tags randomx` | cgo; prebuilt lib in go-randomx |
5254
| `kaspa` | Kaspa (kHeavyHash) | `-tags kaspa` | kaspad gRPC + consensus |
@@ -72,24 +74,56 @@ Copy `config.example.json` to `config.json`, edit the `daemons`, `poolAddress`,
7274
`ports` and `storage` (Redis) sections, then:
7375

7476
```bash
75-
./not-only-mining-pool -c config.json
77+
./nomp -c config.json
7678
```
7779

7880
Engine coins add an `"engine"` field (e.g. `"engine": "ethash"`); GBT coins omit
7981
it (or use `"gbt"`). Per-engine example configs live under `engine/<name>/`.
8082

83+
For Quantus, see the [configuration and miner instructions](engine/quantus/README.md).
84+
It supports the official miner and SRBMiner-Multi through native QUIC and
85+
LuckyPool Quantus Stratum over TCP/TLS.
86+
87+
### Quantus mining and payments
88+
89+
Start with [`config.quantus.example.json`](engine/quantus/config.quantus.example.json).
90+
Configure the node's miner endpoint, authentication token and certificate pin,
91+
the pool's TLS certificate, and Redis. Mining is included in the default Go build;
92+
ports use fixed integer share difficulty.
93+
94+
Optional **PROP/SOLO payments** settle finalized mining rewards in exact base
95+
units (1 QTC = 10^12 units). Signed transactions are persisted before broadcast,
96+
and finalized receipts prevent duplicate debits after a restart. `GET /payments`
97+
exposes balances, pending transaction hashes and finalized receipts.
98+
99+
Payments require the [signing bridge setup](engine/quantus/README.md#自动支付)
100+
(Node.js 20+, Rust and the official Quantus signing library), a dedicated funded
101+
hot wallet, and Redis with `appendonly yes` and `appendfsync always`.
102+
Wormhole mining rewards must still be collected with the official Quantus CLI;
103+
automatic wormhole collection and Quantus PPS/PPLNS are not implemented.
104+
81105
## Testing
82106

83107
- **Unit tests** (hermetic): `go test -short ./...`, and with every engine tag:
84108
`CGO_ENABLED=1 go test -short -tags "neoscrypt ethash randomx kaspa kawpow" ./...`
85109
- **End-to-end** (real nodes, regtest/simnet): a reproducible Docker suite mines a
86110
real block for every coin. All 10 coins pass in CI. See
87111
[docs/E2E.md](docs/E2E.md).
112+
- **Quantus development-chain E2E** (separate local runner): tested with
113+
quantus-node 1.0.1 and the official quantus-miner 4.2.0 CPU engine. The run
114+
confirmed **128 pool blocks**, paid **1.23 QTC**, and recovered an unconfirmed
115+
transaction after a pool crash without a duplicate debit. See the
116+
[validation report](docs/QUANTUS_E2E.md). SRBMiner GPU binaries and production
117+
throughput have not been tested.
88118

89119
```bash
90120
docker build -t nomp-e2e -f scripts/e2e/Dockerfile .
91121
docker run --rm nomp-e2e # every coin
92122
docker run --rm nomp-e2e BTC XMR # a subset
123+
124+
# Quantus, after installing its signing bridge and node/miner binaries
125+
python3 scripts/e2e/quantus.py \
126+
--node /path/to/quantus-node --miner /path/to/quantus-miner
93127
```
94128

95129
## Continuous integration
@@ -111,10 +145,11 @@ every push and PR:
111145
| Pluggable engines (architecture + status) | [docs/PLUGGABLE_ENGINES.md](docs/PLUGGABLE_ENGINES.md) | [docs/PLUGGABLE_ENGINES_zh.md](docs/PLUGGABLE_ENGINES_zh.md) |
112146
| End-to-end testing | [docs/E2E.md](docs/E2E.md) | [docs/E2E_zh.md](docs/E2E_zh.md) |
113147

148+
Quantus: [setup and payment configuration](engine/quantus/README.md) ·
149+
[development-chain test report](docs/QUANTUS_E2E.md).
150+
114151
## TODO
115152

116-
- Engine-mode share persistence to Redis (block submission already works; this is
117-
for stats/payments — see the TODO in `stratum/engine.go`)
118153
- More algorithms
119154
- Web front-end
120155

‎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)