Skip to content

Commit 71eb50d

Browse files
authored
Merge pull request #4 from mining-pool/payment
Payment feature
2 parents 3a17dd8 + a441717 commit 71eb50d

37 files changed

Lines changed: 2944 additions & 181 deletions

‎.github/workflows/ci.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,21 @@ jobs:
6767
run: docker build -t nomp-e2e -f scripts/e2e/Dockerfile .
6868
- name: run e2e suite (all coins)
6969
run: docker run --rm nomp-e2e
70+
71+
# Isolated engine-payout leg for a Zcash-family coin (Flux/ZelHash). Split from
72+
# the main e2e job because fluxd needs ~775MB of zk params; keeping it separate
73+
# means the main suite stays lean. Proves the equihash engine drives a live
74+
# fluxd and the engine pool pays through the shared processor.
75+
e2e-flux:
76+
runs-on: ubuntu-latest
77+
timeout-minutes: 60
78+
steps:
79+
- uses: actions/checkout@v4
80+
- name: free disk space
81+
run: |
82+
sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/lib/android /usr/local/.ghcup /opt/hostedtoolcache/CodeQL
83+
df -h /
84+
- name: build flux e2e image
85+
run: docker build -t nomp-e2e-flux -f scripts/e2e/Dockerfile.flux .
86+
- name: run flux payout leg
87+
run: docker run --rm nomp-e2e-flux

‎TUTORIAL.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,48 @@ Most GPU algorithms only have C implementations. Put the C source under
109109
from an `init()` behind a build tag, and build with `CGO_ENABLED=1 go build -tags
110110
<algo> ./cmd/nomp`. `neoscrypt` (`github.com/sparkspay/go-neoscrypt`) is a worked example.
111111

112+
## Payments (configurable reward scheme, fork-configurable)
113+
114+
Set `disablePayment: false` and add a `payment` block to pay miners automatically.
115+
When a share solves a block the current round is sealed; once the block's coinbase
116+
reaches maturity its reward is attributed to miners per the selected `payMode` and
117+
paid via `sendmany`. Balances below `minPayment` carry over.
118+
119+
```json
120+
"disablePayment": false,
121+
"payment": {
122+
"interval": 600, // seconds between payout runs
123+
"minPayment": 0.05, // min coin owed before a miner is paid (else carried over)
124+
"daemon": 0, // index into daemons[] used for wallet RPC
125+
"payMode": "prop", // "prop" | "pplns" | "solo" | "pps"
126+
"pplnsWindow": 0, // pplns look-back as total share difficulty; 0 = the block's round
127+
"ppsRate": 0, // pps price per share difficulty unit (coin); required for pps
128+
"magnitude": 0, // base units per coin (1e8); 0 = auto-detect
129+
"minConfirmations": 100, // coinbase maturity before a reward is paid
130+
"addressCheckMethod": "getaddressinfo", // or "validateaddress" on older forks
131+
"sendManyDummy": "", // leading sendmany arg (Bitcoin Core wants "")
132+
"omitSendManyDummy": false // true if the fork's sendmany drops the leading arg
133+
}
134+
```
135+
136+
**`payMode`** selects the reward scheme:
137+
- **`prop`** (default) — split the block reward proportionally to the shares of
138+
the round that found it.
139+
- **`pplns`** — split proportionally to the last `pplnsWindow` difficulty of
140+
shares across rounds (a sliding window; resists pool-hopping). `pplnsWindow: 0`
141+
falls back to the block's own round.
142+
- **`solo`** — the miner who found the block takes the whole reward.
143+
- **`pps`** — pay a fixed `ppsRate` per share difficulty **immediately** (each run
144+
credits shares since a cursor and pays); found blocks refill the pool wallet
145+
instead of being distributed, so the **pool** carries the luck variance.
146+
147+
The remaining knobs let one binary pay out across bitcoind-family **forks** whose
148+
wallet RPC differs: coinbase maturity (`minConfirmations`), coin precision
149+
(`magnitude`), the address-ownership check (`addressCheckMethod`), and the
150+
`sendmany` shape (`sendManyDummy` / `omitSendManyDummy`). The payout wallet must
151+
own `poolAddress` (verified at startup). Miners are paid to their worker name, so
152+
they connect with their wallet address as the username.
153+
112154
## Add a category-C coin (an engine)
113155

114156
Category-C coins are already supported by pluggable engines — you don't write one,

‎TUTORIAL_zh.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,41 @@ go build ./cmd/nomp
136136

137137
---
138138

139+
## 3.5 付款(可配置奖励方案,可配置支持各币 fork)
140+
141+
设 `disablePayment: false` 并加 `payment` 配置块即可自动给矿工付款。share 打出块时封存当前轮,
142+
待该块 coinbase 成熟后按 `payMode` 选定的方案分账、经 `sendmany` 发出;不足 `minPayment` 的余额结转下轮。
143+
144+
```json
145+
"disablePayment": false,
146+
"payment": {
147+
"interval": 600, // 每轮付款间隔(秒)
148+
"minPayment": 0.05, // 达到多少币才付(否则结转)
149+
"daemon": 0, // 用 daemons[] 中第几个做钱包 RPC
150+
"payMode": "prop", // "prop" | "pplns" | "solo" | "pps"
151+
"pplnsWindow": 0, // pplns 回看窗口(按 share 总难度);0 = 用该块所在轮
152+
"ppsRate": 0, // pps 每单位 share 难度的定价(币);pps 模式必填
153+
"magnitude": 0, // 每币的最小单位数(1e8);0 = 自动探测
154+
"minConfirmations": 100, // coinbase 成熟确认数(付款前需达到)
155+
"addressCheckMethod": "getaddressinfo", // 老 fork 用 "validateaddress"
156+
"sendManyDummy": "", // sendmany 的首个 dummy 参数(Bitcoin Core 用 "")
157+
"omitSendManyDummy": false // 若 fork 的 sendmany 去掉了首参则设 true
158+
}
159+
```
160+
161+
**`payMode`** 选奖励方案:
162+
- **`prop`**(默认)——按**出块那一轮**各矿工的 share 比例分;
163+
- **`pplns`**——按跨轮的**最近 `pplnsWindow` 难度**的 share 滑动窗口比例分(抗跳池);`pplnsWindow: 0` 退化为该块所在轮;
164+
- **`solo`**——打出块的矿工独得全部奖励;
165+
- **`pps`**——按 `ppsRate` 对每个 share **即时**计费发放(每轮把游标之后的新 share 记账并发款),出块奖励用于回补矿池钱包、不再分账,**由矿池承担运气方差**。
166+
167+
其余开关让**一份二进制**适配各 bitcoind 系 fork 的钱包差异:成熟确认数
168+
(`minConfirmations`)、币精度(`magnitude`)、地址归属校验方法(`addressCheckMethod`)、
169+
`sendmany` 形态(`sendManyDummy` / `omitSendManyDummy`)。付款钱包必须拥有 `poolAddress`
170+
(启动时校验);矿工按其 worker 名收款,故矿工连接时用户名填钱包地址。
171+
172+
---
173+
139174
## 4. 新增一个头哈希算法(A→B 类)
140175

141176
算法系统已重构为**可插拔注册表**(`algorithm/algorithm.go`)。你有两种方式加算法。

‎algorithm/lyra2_vector_test.go‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
package algorithm
2+
3+
import (
4+
"encoding/binary"
5+
"encoding/hex"
6+
"math/big"
7+
"testing"
8+
9+
"github.com/mining-pool/not-only-mining-pool/utils"
10+
)
11+
12+
// TestLyra2Rev2AgainstRealMonacoinBlock verifies the pool's Lyra2REv2 against a
13+
// real accepted Monacoin block (2500000): its PoW hash MUST be <= the block
14+
// target. If not, the library disagrees with monacoind.
15+
func TestLyra2Rev2AgainstRealMonacoinBlock(t *testing.T) {
16+
const (
17+
version = uint32(536870912)
18+
prevDisplay = "20f986555ce18dc5c5de9a69faf6d646026d7ba8da30350e2a93ae1912bbe690"
19+
merkleDisplay = "4dabf61d902f3ca4b22f227287b693914f6287957485b39d68379fdd9d01a241"
20+
ntime = uint32(1637217290)
21+
bits = uint32(0x1a067960)
22+
nonce = uint32(3183243202)
23+
)
24+
prev, _ := hex.DecodeString(prevDisplay)
25+
merkle, _ := hex.DecodeString(merkleDisplay)
26+
27+
hdr := make([]byte, 0, 80)
28+
var b [4]byte
29+
binary.LittleEndian.PutUint32(b[:], version)
30+
hdr = append(hdr, b[:]...)
31+
hdr = append(hdr, utils.ReverseBytes(prev)...)
32+
hdr = append(hdr, utils.ReverseBytes(merkle)...)
33+
binary.LittleEndian.PutUint32(b[:], ntime)
34+
hdr = append(hdr, b[:]...)
35+
binary.LittleEndian.PutUint32(b[:], bits)
36+
hdr = append(hdr, b[:]...)
37+
binary.LittleEndian.PutUint32(b[:], nonce)
38+
hdr = append(hdr, b[:]...)
39+
if len(hdr) != 80 {
40+
t.Fatalf("header len %d", len(hdr))
41+
}
42+
43+
pow := Lyra2Rev2Hash(hdr)
44+
powBig := new(big.Int).SetBytes(utils.ReverseBytes(pow))
45+
46+
exp := bits >> 24
47+
target := new(big.Int).Lsh(big.NewInt(int64(bits&0xffffff)), uint(8*(exp-3)))
48+
49+
t.Logf("pow(reversed) = %x", utils.ReverseBytes(pow))
50+
t.Logf("pow(as-is) = %x", pow)
51+
t.Logf("target = %064x", target)
52+
if powBig.Cmp(target) > 0 {
53+
t.Errorf("POW > target — bitgoin/lyra2rev2 does NOT match monacoind (a real accepted block fails PoW)")
54+
}
55+
}

‎config.example.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,20 @@
6161
"host": "0.0.0.0",
6262
"port": 20000
6363
},
64+
"disablePayment": false,
65+
"payment": {
66+
"interval": 600,
67+
"minPayment": 0.05,
68+
"daemon": 0,
69+
"payMode": "prop",
70+
"pplnsWindow": 0,
71+
"ppsRate": 0,
72+
"magnitude": 0,
73+
"minConfirmations": 100,
74+
"addressCheckMethod": "getaddressinfo",
75+
"sendManyDummy": "",
76+
"omitSendManyDummy": false
77+
},
6478
"storage": {
6579
"network": "tcp",
6680
"host": "127.0.0.1",

‎config/daemon.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ type DaemonOptions struct {
1919
}
2020

2121
func (d *DaemonOptions) String() string {
22-
return d.User + ":" + d.Password + "@" + d.Host + strconv.FormatInt(int64(d.Port), 10)
22+
return d.User + "@" + d.Host + ":" + strconv.FormatInt(int64(d.Port), 10)
2323
}
2424

2525
func (d *DaemonOptions) URL() string {

‎config/options.go‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,14 @@ type Options struct {
2222
EmitInvalidBlockHashes bool `json:"emitInvalidBlockHashes"`
2323
TCPProxyProtocol bool `json:"tcpProxyProtocol"` // http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
2424

25-
API *APIOptions `json:"api"`
26-
Banning *BanningOptions `json:"banning"`
27-
Ports map[int]*PortOptions `json:"ports"`
28-
Daemons []*DaemonOptions `json:"daemons"`
29-
P2P *P2POptions `json:"p2p"`
30-
Storage *RedisOptions `json:"storage"`
31-
Algorithm *AlgorithmOptions `json:"algorithm"`
25+
API *APIOptions `json:"api"`
26+
Banning *BanningOptions `json:"banning"`
27+
Ports map[int]*PortOptions `json:"ports"`
28+
Daemons []*DaemonOptions `json:"daemons"`
29+
P2P *P2POptions `json:"p2p"`
30+
Storage *RedisOptions `json:"storage"`
31+
Algorithm *AlgorithmOptions `json:"algorithm"`
32+
PaymentOptions *PaymentOptions `json:"payment"`
3233
}
3334

3435
func (o *Options) TotalFeePercent() float64 {

‎config/payment.go‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,76 @@ func (r *Recipient) GetScript() []byte {
3737

3838
return r.script
3939
}
40+
41+
type PaymentOptions struct {
42+
Interval int64 `json:"interval"` // seconds between payout runs (default 600)
43+
MinPayment float64 `json:"minPayment"` // minimum coin owed before a miner is paid
44+
45+
Daemon int `json:"daemon"` // index into daemons[] used for wallet RPC (default 0)
46+
47+
// PayMode selects how miners are rewarded:
48+
// "prop" (default) proportional to that block's round shares
49+
// "pplns" proportional to the last-N-difficulty window of shares
50+
// "solo" the miner who found the block takes the whole reward
51+
// "pps" pay a fixed rate per share immediately; found blocks
52+
// just refill the pool wallet (the pool bears variance)
53+
PayMode string `json:"payMode"`
54+
// PPLNSWindow is the pplns look-back as a total share difficulty; <=0 falls
55+
// back to the block's own round (so pplns degrades to prop).
56+
PPLNSWindow float64 `json:"pplnsWindow"`
57+
// PPSRate is the pps price paid per unit of share difficulty (in coin). It
58+
// must be set (>0) when payMode is "pps".
59+
PPSRate float64 `json:"ppsRate"`
60+
61+
// --- coin-fork configurability ---
62+
63+
// Magnitude is the number of base units (satoshis) in one coin, e.g. 1e8 for
64+
// Bitcoin. 0 auto-detects from the wallet's getbalance precision.
65+
Magnitude float64 `json:"magnitude"`
66+
67+
// MinConfirmations is coinbase maturity: a found block's reward is only paid
68+
// once its generation transaction has at least this many confirmations
69+
// (default 100; some forks use 30/40/240).
70+
MinConfirmations int64 `json:"minConfirmations"`
71+
72+
// AddressCheckMethod is the wallet RPC used to verify the pool owns its
73+
// payout address: "getaddressinfo" (Bitcoin Core 0.18+, default) or
74+
// "validateaddress" (older cores / forks that kept it).
75+
AddressCheckMethod string `json:"addressCheckMethod"`
76+
77+
// SendManyDummy is the leading dummy/account argument to sendmany. Bitcoin
78+
// Core requires it and keeps it as "" (the default).
79+
SendManyDummy string `json:"sendManyDummy"`
80+
// OmitSendManyDummy drops the leading argument entirely for forks whose
81+
// sendmany takes only the {address:amount} map.
82+
OmitSendManyDummy bool `json:"omitSendManyDummy"`
83+
}
84+
85+
// WithDefaults returns a copy with unset fork knobs filled with the Bitcoin
86+
// Core defaults, so a minimal config still works on mainstream forks.
87+
func (o *PaymentOptions) WithDefaults() *PaymentOptions {
88+
c := *o
89+
if c.Interval <= 0 {
90+
c.Interval = 600
91+
}
92+
if c.MinConfirmations <= 0 {
93+
c.MinConfirmations = 100
94+
}
95+
if c.AddressCheckMethod == "" {
96+
c.AddressCheckMethod = "getaddressinfo"
97+
}
98+
if c.PayMode == "" {
99+
c.PayMode = PayModeProp
100+
}
101+
c.PayMode = strings.ToLower(c.PayMode)
102+
// SendManyDummy defaults to "" (its zero value), which is what Bitcoin Core wants.
103+
return &c
104+
}
105+
106+
// Reward schemes selectable via PayMode.
107+
const (
108+
PayModeProp = "prop"
109+
PayModePPLNS = "pplns"
110+
PayModeSolo = "solo"
111+
PayModePPS = "pps"
112+
)

‎daemons/getbalance.go‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
11
package daemons
22

3+
import (
4+
"encoding/json"
5+
"fmt"
6+
)
7+
38
type GetBalance float64
9+
10+
func BytesToGetBalance(b []byte) (GetBalance, error) {
11+
var getBalance GetBalance
12+
err := json.Unmarshal(b, &getBalance)
13+
if err != nil {
14+
return 0.0, fmt.Errorf("unmashal getBalance response %s failed with error %s", b, err)
15+
}
16+
17+
return getBalance, nil
18+
}

‎daemons/getblocktemplate.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,9 @@ func (dm *DaemonManager) GetBlockTemplate() (getBlockTemplate *GetBlockTemplate,
100100
instance, result, _ := dm.Cmd("getblocktemplate",
101101
[]interface{}{map[string]interface{}{"capabilities": []string{"coinbasetxn", "workid", "coinbase/append"}, "rules": rules}},
102102
)
103+
if err != nil {
104+
return nil, err
105+
}
103106

104107
if result.Error != nil {
105108
return nil, errors.New(fmt.Sprint("getblocktemplate call failed for daemon instance ", instance, " with error ", result.Error))

0 commit comments

Comments
 (0)