# Kachie DATUM 网关 [English instructions](KACHIE.md) 这是 Kachie 基于 iohzrd 网关提交 `7491a5099dd5d887a027c812f71de63e0d5986a3` 修改的版本，保留 MIT 许可证。 您的节点选择区块交易。Kachie 提供完整的 coinbase 奖励分配，验证份额， 并与传统模式矿池共享奖励。DATUM 手续费为 0%；传统模式 1.5% 手续费中的 0.5 个百分点用于 DATUM 额外奖励。 ## 从源码编译 Linux 已通过验证；原生 macOS 编译和挖矿验证仍待完成。不支持 FreeBSD： 网关可以在 FreeBSD 上编译，但其持久化证明存储需要原子的不覆盖重命名 （仅 Linux 或 macOS 提供），因此网关会拒绝在 FreeBSD 上启动 Kachie 挖矿。 Ubuntu 用户请安装 README.md 中列出的编译依赖以及 Python 3。 macOS 用户请安装 Apple Xcode Command Line Tools（`xcode-select --install`） 和 Homebrew，然后安装依赖： ```sh brew install cmake pkgconf curl jansson libsodium libmicrohttpd argp-standalone epoll-shim python ``` 在解压后的源码目录中，以普通用户身份编译： ```sh cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_API=OFF -DKACHIE_BUILD_TESTS=ON cmake --build build -j2 ctest --test-dir build --output-on-failure ``` ## 配置工具语言 配置工具使用命令行参数，不会启动交互式向导或启动网关。使用 `--language zh-CN` 或 `--lang zh-CN` 显示简体中文帮助、错误和完成提示： ```sh python3 kachie-setup.py --language zh-CN --help ``` 使用 `--language en` 选择英文。默认的 `--language auto` 按 `LC_ALL`、 `LC_MESSAGES`、`LANG` 的顺序，使用第一个非空的终端区域设置。 中文区域设置使用简体中文；其他、缺失或格式无效的区域设置使用英文。 `C` 和 `POSIX` 使用英文，不再采用较低优先级的设置。 语言选择不会更改参数名称、配置键、收款地址、网关身份或挖矿行为。 网关运行日志仍使用英文。 ## 连接节点和矿机 运行已启用 RPC 且完全同步的 Bitcoin (XBT) Knots 节点。 配置工具默认使用本地 RPC 地址 `http://127.0.0.1:8332`。 如果本地节点使用其他端口，请通过 `--rpc-url` 指定。 以运行节点的同一用户身份执行以下命令，将示例地址和路径替换为实际值： ```sh python3 kachie-setup.py --language zh-CN --address YOUR_XBT_ADDRESS --rpc-cookie "/absolute/path/to/.cookie" --listen YOUR_LAN_IP ./run-kachie.sh ``` macOS 节点使用标准数据目录时，可指定 `--rpc-cookie "$HOME/Library/Application Support/Bitcoin/.cookie"`。 如果使用自定义数据目录，请填写实际路径；含空格的路径必须加引号。 配置工具只记录 cookie 路径，不会读取该文件。网关连接节点时才会读取它。 Homebrew 提供 `python3`；启动脚本兼容 macOS 自带的 Bash 3.2。 矿机地址填写 `stratum+tcp://YOUR_LAN_IP:23334`，用户名填写 `address.worker`，密码填写 `x`。矿机名称支持字母、数字、`_` 和 `-`， 最多 100 个字符。请使用专用 XBT 收款钱包；网关不需要钱包私钥。 请使用小写的主网 `bc1...` v0/v1 地址，或主网 `1...`/`3...` 地址。 配置工具会在创建私有状态前校验网络、校验和、见证版本和程序长度。 配置工具会创建私有网关身份，并拒绝覆盖已有配置。重启时保留同一个 `private/gateway.identity`。升级、迁移或恢复前，请先停止网关，并将 `private/gateway.identity`、`private/gateway.json`、 `private/abw-spool/` 和 `private/candidates/` 作为一个不可分割的完整集合备份。 启动网关前必须恢复同一份完整集合；切勿混用不同备份或不同安装中的文件。 同一程序仅在矿池运营的可信传统模式内部网关角色下，才会把完整区块保存到 `private/candidates/`；Prime 不会通过外部 KPA1 连接发送完整 XOR 区块，因此 这个兼容归档目录会保持为空。 签名身份是受保护工作恢复的一部分。若替换或丢失该身份，Prime 会拒绝历史 签名收款授权；证明队列的身份校验也会安全失败，不会用新身份重放旧记录。 任何独立实现 KPA1 的网关也必须保留同一个 HELLO 签名身份，才能恢复历史工作。 原版 CONVOY、iohzrd 和 FlyTheElephant 未实现 KPA1/KAP5，不能不经修改地使用 Kachie 的受保护工作。 macOS 上请将私有状态保存在支持独占重命名和 `F_FULLFSYNC` 的本地 APFS 卷上，以便持久保存证明和交易体；只有可信内部网关 角色才会在这里保存完整区块归档。 矿机监听地址应设为您的局域网地址。节点 RPC 和网关控制台应保持私有访问。 ## 可选的本地控制台 本地控制台默认禁用。若需启用，请将上面的配置命令替换为 `ENABLE_API=ON`，然后编译并测试： ```sh cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_API=ON -DKACHIE_BUILD_TESTS=ON cmake --build build -j2 ctest --test-dir build --output-on-failure ``` 创建新配置时，加入 `--dashboard-port 7152`： ```sh python3 kachie-setup.py --language zh-CN --address YOUR_XBT_ADDRESS --rpc-cookie "/absolute/path/to/.cookie" --listen YOUR_LAN_IP --dashboard-port 7152 ``` 自行启动网关后，在同一台电脑的浏览器中打开 。 控制台会根据浏览器语言自动选择显示语言，也提供 English/简体中文选择器。 浏览器语言与配置工具的终端语言彼此独立。 配置工具将控制台固定绑定到 `127.0.0.1`，保持 `api.modify_conf=false`， 不会设置管理员密码或更改 CSRF 防护。端口可选择 1 至 65535 中未被占用的值； `0` 表示禁用。请勿将控制台或节点 RPC 暴露到公网。 已有配置的用户无需重新运行配置工具。使用以 `ENABLE_API=ON` 编译的网关， 手动将 `private/gateway.json` 中的 `api.listen_port` 改为 `7152`， 保留 `api.listen_addr` 为 `127.0.0.1`、`api.modify_conf` 为 `false`。 保留原有网关身份和其他设置，并在您自行安排的重启时应用更改。 配置工具不会重启网关。如果已经自行设置管理员密码，请保持原设置。 ## 矿机接入与容量 发行包默认允许 1,024 个矿机连接，同时防止单一来源占满全部连接位。 每个 IPv4 地址算一个来源；IPv4 映射的 IPv6 会归入同一个 IPv4 来源， 原生 IPv6 按 `/64` 网段归类，因此轮换接口地址不能绕过限制。默认每个来源 最多 512 个连接、每分钟 4,096 个新连接、瞬时突发 2,048 个连接，并为新来源 保留 256 个连接位。大型可信 NAT 可加入 `stratum.source_limit_exempt`， 使用逗号分隔 IPv4 `/32` 或 IPv6 `/64`；只应填写您控制的地址。 PROXY 协议默认禁用。若矿机通过可信的 L4 代理连接，请将 `stratum.trust_proxy` 设为可信跳数（1 至 8），并在 `stratum.proxy_trusted_sources` 中用 IPv4 `/32` 或 IPv6 `/64` 列出每个 代理来源。来自其他来源的 PROXY 标头会被拒绝。信任逐跳检查：只有当上一 个标头指明的来源是已列出的代理时，后续 PROXY 标头才会生效；否则网关保留 最后一个可信来源。旧配置若启用了 `trust_proxy`，升级前必须增加此允许列表。 未订阅的空闲连接在 15 秒后移除；订阅后仍未提交首个有效份额的连接在 300 秒后移除；最后一次有效份额之后 900 秒仍无新份额也会移除。这三个超时 必须为正数。旧配置若用 `0` 禁用超时，升级前必须改成有限值。 `max_clients_per_source` 必须小于 `max_clients`，并留出 `reserved_clients`。若小型安装把 `max_clients` 设为 256 或更低，也必须把 默认值为 256 的 `reserved_clients` 调低。 发行包默认配置 1,024 个连接；Kachie 的私有内部部署使用支持的 16,384 个连接 上限。按每台矿机每分钟两个份额计算，两者约为每秒 34 和 546 个证明。提高连接数 或目标份额率都会增加内存、磁盘和记账吞吐量需求；若有界矿机数组、队列和证明 索引超过内存预算，网关会拒绝配置。 每个受保护证明都会先开始写入私有 KAP5 磁盘队列，然后网关才可能向矿机报告 成功。正常情况下，证明向上游发送前已完成持久写入。Coinbase、交易体和消息 对象按内容寻址并去重。若同步调用在 250 毫秒内没有进展，当前接入线程会采用 一份不可变的完整区块体副本，并严格先发送区块体、后发送证明；不会为每个证明 新建线程，矿机成功响应仍须等待 KAP5 持久化完成。未解决证明/索引上限按已配置 连接数、每分钟目标份额数和 16 分钟保留窗口计算，下限为 65,536，硬上限为 4,194,304；16,384 连接的内部配置会预留 524,288 个身份。队列数据上限为 8 GiB，同时保留 1 GiB 文件系统空间。未解决证明绝不会 被淘汰。若容量、剩余空间、完整性或持久化失败，网关会停止下发新任务；除非 已知某一端持久拥有该份额，否则不会向矿机报告已接受。 下发任务前，网关还会为每个已配置的 Stratum 工作线程预留一个最大引用证明 （最多 64 个）。每个证明的精确逻辑上限为 66,888 字节；预留量同时计入文件 系统块取整、每个证明三个文件、全部 256 个分片目录及一个原子临时文件，物理 预留下限为 8 MiB。若硬上限无法覆盖所有已接纳线程，启动会失败。之后若字节或 inode 余量达到高水位，网关会停止下发任务和接收新连接，断开现有矿机套接字， 并等待已接纳的提交完成持久 KAP5 写入；与 Prime 的连接和持久重放仍保持运行。 仅可通过 `KACHIE_DATUM_ABW_SPOOL_MAX_PROOFS`、 `KACHIE_DATUM_ABW_SPOOL_MAX_BYTES` 和 `KACHIE_DATUM_ABW_SPOOL_FREE_RESERVE` 调整限制；低于启动预留量的设置会被拒绝。 磁盘 I/O 错误、无法读取文件系统容量或 inode 耗尽也会触发同一矿机排空流程。 重启或补充队列时，持久 KAP5 先发送紧凑证明，不会为每个证明展开或主动发送 KAT1。Prime 使用先前持久登记的区块体；若缺失，则在分类前统一发送经过认证且 精确绑定的 `0x15` 请求。该请求启用 20 秒无进展时限，以及从证明发送时刻起算的 5 分钟绝对上限。只有同一直接加密帧的单调字节进展，或经过认证且按顺序的批量 确认，才能重置无进展时限。区块体完整传输后，份额记账结果和所有权终态各自重新 获得独立的 30 秒时限。5 秒区块体时限只用于未持久化的 RAM 紧急先体后证路径。 任何超时都只触发重连并保留 KAP5；无关流量不能延长时限。Prime 对外部来源固定 的 2 秒披露周期保持不变，但区块体就绪后的终态不会等待下一周期。 在尚未收到精确终态对时，网关最多向上游发送 256 个受保护证明。Prime 固定 2 秒的外部披露周期使实时窗口为每秒 128 个证明。其余 KAP5 记录按确定顺序保留 在磁盘；分页的先证后体重放排空到低水位前，网关暂停新的受保护接入和任务发布， 因此新流量不能饿死旧证明。该窗口足以覆盖发行包默认的 1,024 连接。16,384 连接 的内部部署在突发时依赖持久积压门控，并使用可信来源的即时终态路径；紧凑重放、 持久写入和精确终态周转测试均要求超过每秒 600 个证明。 KAP5 会在重启后保留带类型的终态信息。加载器只为迁移读取旧 KAP4 记录；新记录 一律写成 KAP5。 ## XOR 防扣块挖矿 连接启用防扣块功能的 Kachie 矿池前，请升级网关。本版本要求 Kachie 的 DATUM v3 扩展，不会退回未保护模式或单独挖矿。只有收到分配、Prime 签名的 完整奖励方案，并且 Prime 已持久确认精确交易体后才会下发任务。您的节点仍 选择交易，所有 ASIC 类型仍使用完整 coinbase。手续费、奖励窗口和直接 coinbase 支付方式均保持不变。 登记前，网关会先把精确交易体持久写成按内容寻址的 `KAT1` 对象，并在收到确认、 下发任务和本地模板退役之前一直保留活动模板引用。每个未解决的 `KAP5` 证明还会 增加独立引用，因此活动任务退役后，迟到证明仍能恢复同一交易体。普通份额只携带 紧凑的交易体哈希，不会为每个份额复制约 4 MiB 的完整交易体。证明终态清理或本地 缓存压力都不能淘汰仍被引用的交易体；若新交易体与已配置的接入预留量无法同时装入 队列，网关会在任何矿机收到该任务前停止发布。 Prime 只向网关发送承诺，不会把分配密钥作为协议反馈返回，因此在 Prime 收到 普通份额前，网关无法判断其中哪些也能生成区块。被接受的 v2 区块公开后，其扩展 区块头会不可避免地公开已经停用的该代密钥。这些是挖矿分配密钥，不是钱包私钥。 Prime 会验证签名奖励方案和已登记的精确区块体，并仅在持久 记账后确认份额。奖励窗口为空时，使用 Prime 明确签名的“找到者获得”规则。 [协议与恢复详情（英文）](KACHIE-XOR.md)。 父区块变化、中奖区块关闭当前代，或有界负结果暴露预算耗尽时，活动分配会 变化。传统 Stratum 和外部 DATUM 都受此预算限制，因为公开链本身也会暴露 负结果。同一父区块轮换时，网关会在不主动断开 ASIC 的情况下发布新的小型 受保护任务封装；来自已停用封装的迟到证明仍可交付。常规 GBT 刷新复用一个 预先裁剪且不可变的交易体。同一父区块的受保护交易体绝不会被回收：网关会改用 32 个交易体环中的其他槽位；若所有槽位都受该父区块保护，则停止发布。后续不同 父区块可以覆盖旧环槽；到达该边界时，旧活动任务会以失败关闭。已经写入 KAP5 的 证明仍是自包含的；但若 ASIC 直到旧交易体离开这个有界环后才提交，网关将无法 重建该份工作。在仍保留交易体的范围内，代哈希索引和 65,536 个封装上限会在 覆盖任何已接纳封装前停止新任务发布。槽位重用后，旧任务仍由随机分配 ID 和 密钥哈希唯一绑定。恢复令牌及未解决的 `KAP5` 证明保存在私有磁盘队列中，重启后 仍可恢复丢失的最终确认。 当本地节点报告可能出现新链尖，或提交任务已确认属于旧父区块时，网关会取消 该证明的普通本地记账资格，但仍会持久保存并发送它。Prime 独立核验签名代和 已登记交易体。对外部 DATUM 身份，Prime 只返回普通的精确份额结果，以及与代、 原始哈希绑定的 `A7` 区块体所有权释放；不会发送候选标签、作为网关反馈的分配 密钥、完整区块 `0x98` 或候选专用 `A5`。若节点提交结果不确定，Prime 不发送终态，并冻结同一 父区块的新任务，直到获得精确结果或父区块离开；KAP5 在重连期间仍是权威副本。 外部 DATUM 不使用候选专用 `A4`/`A5` 会话；`A4` 仍是旧迁移命令，本网关在 强制保护模式下会拒绝它。常规链尖切换期间，网关会保持矿机连接，保存 TCP 或 解析缓冲区中已有的提交，然后通过同一连接发送新的干净任务。 请使用 `run-kachie.sh` 启动；它会配置私有证明队列和恢复状态。只有同时收到 Prime 的持久最终份额结果，以及精确 `A7` 代/原始哈希所有权释放后，证明才能 删除；两者可按任意顺序到达。经过测试的 `0x98`/`A5` 完整区块转发只保留给 矿池运营方认证的传统模式内部网关：Prime 先持久拥有并开始提交区块，再要求 内部网关通过本地节点冗余转发。外部 DATUM 身份不会收到这组消息。存储耗尽时 会停止新的受保护任务，绝不会静默丢弃未解决证明。 面向矿机的份额结果采用异步等待，时限为 150 秒，覆盖普通终态与重连路径。 精确缺失区块体恢复采用 20 秒无进展和 5 分钟绝对上限，因此可能合理地超过本地 等待时限；矿机收到 `upstream-pending` 后，KAP5 仍保持权威。若仍无法获得精确 结果，或 256 个本地等待位已满， 网关返回 `upstream-pending`，只取消本地 vardiff/统计记账，并继续 KAP5 重放； 不会把它计为拒绝份额。Stratum v1 没有标准“待定”响应，因此部分 ASIC 界面仍 可能显示为拒绝，即使 Prime 后续成功记账。 高速矿机的份额难度会受到上限限制，以保留至少十六个隐藏目标位，因此可能 更频繁地提交份额。如果矿池的最低难度也无法保留这些位，网关会记录警告， 矿池会在所有非 regtest 网络拒绝不安全工作。Prime 按服务器验证的工作量统计 唯一负结果；达到网络预期工作量的 1/256 时，会先持久停用该代再返回结果。 低于最低难度的探测会一次耗尽剩余预算。Prime 不会把 XOR 分配密钥作为网关 反馈直接返回，因此会显著提高选择性识别中奖份额的成本；但固定掩码的可观察 结果和公开链仍构成自适应判定接口，已接受区块的扩展区块头也会公开停用的该代密钥。 在本次审查的最优采样模型中，攻击者仍可用约 288 个实际接受证明换取一个 选择性记账证明；这是经济限制，不能保证扣块完全不可能。第一个已接受区块公开后， 恶意网关若已经保留同一父区块的第二个有效中奖证明，就能识别并广播该兄弟区块， 造成同高度竞争或孤块；其已签名 coinbase 不能把其他矿工的奖励改给自己。XOR 也 不能阻止丢弃全部或随机份额、停机、拒绝服务、陈旧链拒绝、主机失陷，或在任一端持久拥有新证明前 同时发生磁盘、网络和进程故障。 矿池地址：`stratum.kachiepool.com:28915` 矿池公钥： `4b7e6aad450d54b6607a431040281c968eed18c3638617cab5969a8fc3c45507a37e2034baf3b83f59c9725dbf3eeb78ab08edc198e4e5a924f4ee6d7e3fa167` Kachie 版本的内置默认值、`--example-conf` 输出、随附示例以及 `kachie-setup.py` 都会固定使用以上主机、端口和公钥。已有配置若明确指定其他 矿池，则不会被修改。 网关从不自动获取矿池公钥：只要设置了 `datum.pool_host`，`datum.pool_pubkey` 就必须恰好是 128 位十六进制字符。`--validate-config` 会在创建任何证明暂存目录之前 拒绝空的或格式错误的公钥，以及不是有效 Bitcoin 地址的 `mining.pool_address`。