# m2pool-mining-core

一个基于 Go 的轻量化挖矿池服务内核，包含 Job 生成/分发与 Stratum 矿工端接入两大模块：
- gbt：区块模板生成与同步（GetBlockTemplate/Job Producer），通过 ZMQ 向服务端发布新任务
- server：Stratum 挖矿服务（矿工接入、难度调整、提交校验、统计与缓存）

当前代码启用了 `sha3x` 币种实现（其他如 `nexa`、`monero` 的代码结构已准备但默认关闭/注释）。

---

## 功能特性
- Stratum 协议接入，支持 `mining.subscribe`、`mining.authorize`/`login`、`mining.submit`、`mining.ping/pong`
- 可配置的难度策略（含卡尔曼滤波驱动的 VarDiff 逻辑，按提交间隔动态调整）
- 任务分发与同步：gbt 通过 ZMQ 发布，server 订阅并向在线矿工广播
- 连接数/同 IP 限流、存活监测、超时与心跳处理
- Redis 用于在线状态与速率缓存，DB 持久化矿工/用户/池端统计
- 日志：zap + 日志轮转
- 内置 pprof 端口（从配置读取）

---

## 目录结构
```
cmd/
  gbt/gbt.go          # 区块模板生成/任务发布入口
  server/server.go    # 挖矿池服务入口（Stratum 服务）
internal/
  server/             # 矿工接入、会话、难度、任务处理
  gbt/                # GBT/任务管线，各币种对接
  db/                 # 数据库上下文与表结构
  cache/              # Redis 缓存读写
  stratum/            # Stratum 协议与消息结构
  utility/            # 工具、日志、ZMQ 初始化等
config/
  nexa/
    server/server.conf  # server 示例配置（按需拷贝/修改）
    gbt/gbt.conf        # gbt 示例配置（按需拷贝/修改）
    db/db.conf          # DB 配置（MySQL/SQLite）
```

---

## 环境依赖
- Go 1.23+（go.mod 声明 `toolchain go1.23.1`）
- Redis（作为状态/速率缓存）
- 数据库：MySQL 或 SQLite（按 `config/<coin>/db/db.conf` 配置）
- ZMQ（用于 gbt → server 的 Job 发布/订阅）
- 可选本地 C 库：目录 `internal/server/lib/` 下包含部分 `.so`/`.a`，用于特定算法；`sha3x` 默认主要为 Go 实现。建议在 Linux 环境下构建、运行；Windows 可能需要适配或禁用相关 C 扩展。

---

## 快速开始
1) 准备配置文件（以 `sha3x` 为例）
- 将以下文件拷贝到运行目录（项目根或二进制同目录）：
  - `config/nexa/server/server.conf` → `server.conf`
  - `config/nexa/gbt/gbt.conf` → `gbt.conf`
  - `config/nexa/db/db.conf` → `db.conf`
- 打开并修改以上配置以匹配你的 Redis、DB、ZMQ 与监听地址。例如：`server.conf` 中的 Stratum 监听端口、pprof 端口，`gbt.conf` 中的上游节点与发布地址。

2) 构建
```
# 在项目根目录执行
go build -o bin/server ./cmd/server
go build -o bin/gbt ./cmd/gbt
```

3) 运行
```
# 先启动 gbt（负责产生并发布 Job）
./bin/gbt

# 再启动 server（负责矿工接入与提交校验）
./bin/server
```
- 两个进程均会在工作目录读取同名配置：`gbt` 读取 `gbt.conf`，`server` 读取 `server.conf`。
- `server` 会根据配置启动一个 pprof HTTP 端口，便于性能分析。

4) 矿工连接
- 在矿工端配置你的 Stratum 地址，即 `server.conf` 中的 `Host.Listen`（例如：`stratum+tcp://<ip>:<port>`）。
- 账户名与 Miner 名按池的约定填写，对应鉴权在 `internal/stratum` 与 `internal/server/coin/*` 中处理。

---

## 配置说明（概览）
- server.conf（读取于工作目录）
  - Host.Listen：Stratum 监听地址，形如 `0.0.0.0:端口`
  - Redis：`Addr/Password/DB`
  - ZMQ：`Pub`（向外发布）、`Sub`（订阅 gbt 发布的 Job）
  - Diff：难度相关参数（起始、最小/最大、调整间隔、滤波模式等）
  - Zaplog/Logrotate：日志级别、输出与轮转策略
  - pprof 端口：由 `cmd/server` 中 `utility.GetCoin("server.conf")` 返回的第二个值决定
- gbt.conf（读取于工作目录）
  - 上游节点/RPC 或 gRPC/GRPC/Tari/Monero 等对接参数
  - ZMQ：对外发布 Job 的地址（需与 server 的 `Zmq.Sub` 对应）
- db.conf
  - MySQL 或 SQLite 连接信息（`internal/db` 负责加载与建表）

注意：项目内示例配置位于 `config/nexa/...`，请根据目标币种复制调整；`sha3x` 仅需要确保 ZMQ/Redis/DB 与监听端口正常。

---

## 运行时行为要点
- gbt → server：通过 ZMQ 发布/订阅通道传递新 Job，`server` 收到后同步标志并向矿工广播
- 存活与心跳：`server` 为连接设置超时、心跳（ping/pong），并清理无效连接
- 动态难度：根据提交间隔、方差与配置策略更新矿工难度
- 速率与统计：接受/拒绝、哈希率、区块、孤块等统计通过内存与 Redis/DB 维护
- 退出流程：`Stop()` 会清理连接、关闭 ZMQ、Redis、日志并回收内存结构

---

## 常见问题
- 端口不通：确认 `server.conf` 中监听端口开放（防火墙/安全组），ZMQ 地址能互通
- 配置找不到：`server` 与 `gbt` 均在工作目录读取 `*.conf`，请确保以正确的工作目录启动或将配置拷贝到同一目录
- 构建失败（Windows）：如遇 `.so/.a` 相关链接问题，建议在 Linux 构建或禁用/移除对应 C 扩展；`sha3x` 模块通常不依赖这些库
- Redis/DB 未就绪：请先启动并配置正确连接串；否则启动会失败或无法持久化统计

---

## 开发与调试
- 使用 pprof：根据 `server.conf` 暴露的地址访问 `http://<ip>:<pprof_port>/debug/pprof/`
- 日志：默认使用 zap，按 `Zaplog` 与 `Logrotate` 配置输出与轮转
- 关键位置：
  - `internal/server/server.go`：连接处理、心跳、难度调整、Job 处理主流程
  - `internal/gbt/*`：各币种 GBT 接入与 Job 生成
  - `internal/stratum/*`：协议与消息体

---

## 构建与运行示例（Windows PowerShell）
```
# 构建
$env:CGO_ENABLED=0
go build -o bin/server.exe ./cmd/server
go build -o bin/gbt.exe ./cmd/gbt

# 运行前将 *.conf 复制到当前目录
./bin/gbt.exe
./bin/server.exe
```

> 注：如需使用依赖本地 C 库的算法实现，建议在 Linux 环境构建并确保工具链与库依赖可用。

---

## 许可证
本项目未在仓库根目录明确声明许可证。如需开源发布，请在根目录新增 LICENSE 并注明授权条款。