Stratum V1 客户端源码分析：连接、订阅与矿池切换

摘要

本文通过分析 ESP-Miner 的 Stratum V1 实现，揭示了稳定挖矿客户端需解决的核心挑战：连接管理、状态机设计、内存安全、容灾策略与可观测性。文章提出使用 transport_lock 保护连接生命周期、设计明确会话状态机、设置协议级内存上限、实现带抖动的指数退避等最佳实践，为长时间稳定运行的网络客户端提供参考。

关键词：Stratum V1、状态机、内存安全、指数退避、矿池容灾、JSON-RPC、TLS、ESP-IDF Transport

1. 连接不只是 connect()

main/tasks/stratum_task.c 先通过 resolve_stratum_address() 解析地址，再由 STRATUM_V1_transport_init() 创建 TCP 或 TLS transport。连接建立后还设置 socket keepalive 和超时。

代码将实际 transport 放入 GlobalState，并通过 transport_lock 保护关闭与 Share 提交。这个锁非常关键：接收任务可能因为错误关闭连接，而 ASIC 结果任务恰好正在 mining.submit。如果不序列化，底层句柄可能在写入中被销毁。

2. Stratum 会话的握手序列

典型会话包含：

mining.subscribe
mining.configure(version-rolling)
mining.authorize
mining.suggest_difficulty
mining.extranonce.subscribe（可选）

解析代码位于 components/stratum/stratum_api.c。STRATUM_V1_receive_jsonrpc_line() 负责从字节流恢复一行 JSON，STRATUM_V1_parse() 再区分响应和通知。

订阅响应提供 extranonce1 与 extranonce2_size，它们决定设备能从同一矿池任务扩展出多少本地工作。

版本滚动不是简单修改区块头。矿池返回 mask 后，固件保存 version_mask，通知 ASIC 允许滚动的位，并在校验 Nonce 时使用 ASIC 返回的 rolled version 重建区块头。

3. 通知如何进入挖矿流水线

收到 mining.notify 后，代码更新网络难度、解析区块高度和 coinbase scriptSig，然后把通知放入 stratum_queue。

当通知要求 clean_jobs 时，旧作业必须失效。decode_mining_notification() 对脚本进行长度检查和可打印字符替换，这种“先边界检查，再用于展示”的做法值得保留。网络字段永远不应直接当 C 字符串打印。

4. 主备矿池切换

连续失败达到 MAX_RETRY_ATTEMPTS=3 后，代码在主矿池与备用矿池之间切换，并重置 Share 统计。备用 URL 为空则继续尝试主矿池。

系统还保存：

• 当前是否使用备用矿池；
• 最近一次收到矿池数据的时间；
• 最近错误时间和错误计数；
• 连接地址说明。

这使运行时诊断能够区分“Wi-Fi 已连接但矿池沉默”和“根本没有 transport”。

值得改进的是退避策略。固定延时会让大量设备同时重连，形成惊群。建议采用带抖动的指数退避：

delay = min(base * 2^retry, max_delay) + random_jitter

主备切换也应增加最短驻留时间，防止两个不稳定矿池之间来回振荡。

下面是一个展示主备矿池切换状态流转的Mermaid流程图：

流程图关键节点说明：

1. 失败计数：每次连接或通信失败时递增，达到阈值（MAX_RETRY_ATTEMPTS=3）触发切换判断。
2. 切换条件：失败次数达标且备用矿池URL有效时，执行主备切换。
3. 退避延时：
   • 当前策略：固定延时重试（易形成惊群）。
   • 改进建议：带抖动的指数退避（delay = min(base * 2^retry, max_delay) + random_jitter）。
4. 状态重置：切换矿池时重置Share统计与失败计数，确保新一轮尝试从零开始。
5. 最短驻留时间：防止两个不稳定矿池间快速振荡，提升系统稳定性。
6. 超时检测：基于“最后收到矿池数据的时间”判断矿池是否沉默，区分网络层与协议层故障。

重试策略对比

下表对比了当前固定延时重试策略与建议的带抖动指数退避策略在四个关键维度的表现：

总结：固定延时策略实现简单，但缺乏弹性，在大规模部署中容易引发惊群效应。带抖动的指数退避策略虽然实现稍复杂，但能显著提升系统的抗干扰能力和整体稳定性，是生产环境推荐的容灾方案。

5. JSON 缓冲和内存风险

Stratum 消息以换行分隔，但 TCP 不保留消息边界。缓冲区必须处理半包、多包和超长行。当前实现支持动态扩容，并在主程序中让 cJSON 优先使用 PSRAM。

专业固件还应设置协议级上限。例如 Merkle 分支最大 32、coinbase 最大长度、单行 JSON 最大尺寸。只依赖“内存分配失败”拒绝异常消息，会给恶意或错误矿池留下耗尽内存的空间。

6. 可观测性比重连更重要

连接失败不能只打印 errno。至少应记录 DNS 耗时、TCP/TLS 建连耗时、授权响应时间、最后 RX 时间、当前重试阶段和切换原因。

仓库已经通过请求时间戳统计 JSON-RPC 响应时间，这是良好基础。进一步可以把会话建模为明确状态：

DISCONNECTED -> RESOLVING -> CONNECTING -> SUBSCRIBING
-> AUTHORIZING -> RUNNING -> BACKOFF

这样 Web 页面、运行时故障和工厂测试读取的是同一个状态，而不是分别推断多个布尔字段。

Stratum 客户端的质量最终体现在“网络坏时是否可解释、恢复时是否有边界”。协议本身并不复杂，复杂的是长时间运行后的状态收敛。

7. 总结与最佳实践

通过分析 ESP-Miner 的 Stratum V1 实现，我们可以总结出以下最佳实践：

1. 连接管理：使用 transport_lock 保护连接生命周期，避免并发关闭和写入
2. 状态机设计：明确的会话状态机有助于故障诊断和恢复
3. 内存安全：对网络数据设置合理的协议级上限，防止内存耗尽攻击
4. 容灾策略：实现带抖动的指数退避和最短驻留时间，避免惊群效应
5. 可观测性：记录关键时间戳和状态转换，便于问题排查

这些实践不仅适用于挖矿客户端，对于任何需要长时间稳定运行的网络客户端都有参考价值。