epochbtc/satd

# satd **一个与 Bitcoin Core 兼容的 Rust 全节点实现。** `satd` 提供了核心节点，以及运营者通常会与之搭配使用的钱包服务端协议（Esplora REST, Electrum, BIP 157/158）。 *一个进程。一个 RocksDB。一个 systemd 单元。* ## 为什么选择 satd？ * **节点主权：** 旨在为经济节点运营者提供一个健壮的、内存安全的替代方案，以打破单一文化，增强网络的韧性。请阅读 [宣言](MANIFESTO.md)。 * **零共识分歧（双引擎）：** 包含一个完整的 Rust 共识规则实现，通过了 Bitcoin Core 的测试套件（甚至更多）。运营者可以选择运行纯 Rust 引擎、C++ `libbitcoinconsensus` 引擎，或同时运行两者进行双向影子验证，从而在数学上保证零分歧。 * **为运营者而生：** 消除了 `bitcoind` + `electrs` + `esplora` 多进程的令人头疼的问题。所有组件共享单一的链状态和单一的 RocksDB 实例。 ## 功能特性 ### 共识与网络 * **双共识引擎：** 一个完整的、独立编写的 Rust 共识引擎，通过了 Bitcoin Core 测试套件，并以 C++ `libbitcoinconsensus` 作为保守的后备方案。 * **群集式 IBD：** 类似 BitTorrent 的并行区块下载和投机性验证流水线，针对初始区块下载 进行了深度优化。 * **完整 P2P：** BIP 152 紧凑区块、封禁评分、addrv2、BIP 324 v2 传输（开发中）、Tor v3（硬编码的 `.onion` 种子节点）。 * **策略主权（内存池）：** 对节点中继的内容进行严格的一级控制。轻松过滤垃圾交易，拦截 `OP_RETURN` 数据，或通过暴露的命令行标志（`-datacarrier`, `-datacarriersize`, `-dustrelayfee`, `-limitancestorcount`, `-permitbaremultisig`）调整限制，而无需打补丁或使用分叉版本。 * **现代内存池：** 完整的 RBF / 选择性加入 BIP 125 以及 CPFP 祖先追踪。 ### 原生集成（无需附加边车服务） * **原生 TLS 支持：** 为 JSON-RPC、Electrum 和 Esplora 服务器提供直接的 TLS 支持，无需使用 Nginx/反向代理等边车服务。 * **AI 原生 MCP 服务器：** 一个可选的模型上下文协议 (`mcp`) 二进制文件，将节点数据和操作接口直接暴露给 AI 代理。 * **Electrum 协议：** 原生 TCP 服务器（v1.4.5），适用于 BlueWallet、Sparrow 和 Nunchuk 等钱包。 * **Esplora REST：** 在已实现的端点集上，与 blockstream.info / mempool.space 保持线路格式一致。 * **紧凑区块过滤器：** 原生 BIP 157/158 索引和 P2P 服务，适用于嵌入式 Neutrino 移动钱包（Zeus, Blixt, Mutiny）。 * **共享索引：** 与 `connect_block` 保持原子性的地址历史索引。一个数据库驱动一切。 ### 运维操作体验

查看 satd 终端 UI

 *`sat-tui` 界面提供实时可观测性，包括 IBD 位图、节点对等端统计和 JSON-RPC 浏览器。*

* **原生 TUI (`sat-tui`):** 一个基于 Ratatui 的美观终端界面，用于实时 IBD 位图可视化、节点对等端统计和节点可观测性。 * **指标与可观测性：** 原生 Prometheus `/metrics`、`/healthz` 以及 JSON 结构化日志。 * **核心兼容性：** 接受标准的 `bitcoin.conf` 和 CLI 标志（`-prune`, `-txindex`, `-assumeutxo`）。使用标准的 `.cookie` 认证。 * **内存池流：** `subscribemempool` JSON-RPC WS 订阅，提供明确的驱逐/替换原因。 * **事件总线：** 用于链和内存池事件的 gRPC + ZMQ 发布器 (`satd-events`)。 * **重组日志：** 持久化的重组日志，带有可选的 webhook。 *（请参阅 [CORE_DIFFERENCES.md](CORE_DIFFERENCES.md) 获取有意偏离项和明确排除在外的功能（如传统钱包）的完整清单。）* ## 入门指南 ### 构建 需要 Rust（稳定版，2024 版本）、C/C++ 编译器以及 clang/LLVM 库（用于 `rocksdb-sys` 的 bindgen）。 ``` ./configure # detect dependencies, generate .cargo/config.toml cargo build ``` **仅限共识的构建**（不包含 BIP 158 编解码器、Esplora 处理程序、Electrum 协议代码）： ``` cargo build -p satd --no-default-features ``` **通过 Nix 进行可重现构建**（跨主机具有确定性；工具链固定在 `rust-toolchain.toml` 中）： ``` nix build .#satd # produces ./result/bin/{satd, sat-cli} ``` *完整说明请参见 `docs/PACKAGING.md` 中的“Reproducible build via Nix”章节。* ### 运行 ``` # Regtest — 快速本地节点 cargo run --bin satd -- --regtest # Mainnet — 默认开启 Esplora 和地址索引 cargo run --bin satd -- --datadir=/path/to/datadir # 添加 Electrum 服务器（环回；通过 Tor 暴露） cargo run --bin satd -- --electrum=1 # 为 embedded-Neutrino 钱包添加 BIP 157/158 P2P 服务 cargo run --bin satd -- --blockfilterindex=basic --peerblockfilters=1 ``` ### 查询与停止 ``` cargo run --bin sat-cli -- --regtest getblockchaininfo cargo run --bin sat-cli -- --regtest getindexinfo cargo run --bin sat-cli -- --regtest getserverstatus cargo run --bin sat-cli -- --regtest stop ``` ## 配置 默认接受与 Bitcoin Core 兼容的标志（`-regtest`, `-datadir`, `-rpcport`, `-prune`, `-txindex`, `-assumeutxo` 等）以及 `bitcoin.conf` 文件格式作为配置接口。 内置的 `--profile=` 可以从 `archival`、`pruned-home`、`mining`、`regtest-dev` 和 `signet-watchtower` 中进行选择。CLI 标志会覆盖 profile 值；`getconfig` / `sat-cli node config` 会显示合并后的最终有效配置。 身份验证默认使用 cookie 文件，或者使用 `--rpcuser` / `--rpcpassword`。Esplora 监听器默认为**未经身份验证的本地回环**；若要暴露给非本地回环地址，请设置 `--esploraauth=cookie` 或 `--esploraauth=userpass`。 *完整的标志矩阵和调优说明请参见 `OPERATOR_ERGONOMICS.md`。* ## 仓库布局 ``` satd/ Daemon binary — config, lifecycle, wiring sat-cli/ CLI client — Bitcoin-Core-compatible RPC client sat-tui/ Ratatui-based ops TUI node/ Core library (chain, storage, mempool, P2P, RPC, validation) node-index/ Address-history index over the shared RocksDB node-filter-index/ BIP 158 compact-block-filter index esplora-handlers/ Native Esplora-compatible REST electrum-proto/ Native Electrum protocol server (vendored from electrs) events/ Event-bus sinks (gRPC + ZMQ) mcp/ MCP tools over the ops-surface RPCs consensus/ Rust script-verifier shadow block-analyzer/ Standalone tool for offline block analysis docs/ API + integration docs ``` ## 文档 | 文件 | 用途 | |---|---| | [`MANIFESTO.md`](MANIFESTO.md) | 节点主权、单一文化风险以及保守的 BIP 策略。 | | `CORE_DIFFERENCES.md` | 有意偏离 Bitcoin Core 的行为目录：原生接口、排除项和行为默认值。 | | `OPERATOR_ERGONOMICS.md` | 面向运维的标志矩阵、调优以及所有内置接口。 | | `STABILITY_POLICY.md` | 分级稳定性契约；废弃策略；金丝雀 CI。 | | `ECOSYSTEM.md` | 移动端 / 打包策略；为什么选择原生 + 共享链状态。 | | `docs/PACKAGING.md` | 面向下游打包者的权威参考。 | | `docs/TUI.md` | `sat-tui` 参考：视图、面板、各个字段、快捷键。 | | `docs/api/esplora.md` | Esplora REST 端点参考 + 线路格式注意事项。 | | `docs/E2E_TESTING.md` | 端到端测试套件：如何运行、超时旋钮、抖动门控工作流。 | ## 许可证 MIT — 完整文本请见 [`LICENSE`](LICENSE)。 *来自 `romanz/electrs` (MIT) 的供应代码已在 `electrum-proto/vendor/electrs.MIT` 中注明，并保留了原始的 LICENSE 文本。*

标签：BIP 152, BIP 157/158, DNS解析, Electrum, Esplora, Google搜索, Mempool, P2P网络, Python工具, RocksDB, Rust, Swarm-Style IBD, Web3, 便携式工具, 全节点, 共识引擎, 内存安全, 加密货币, 区块链, 去中心化, 可视化界面, 后端开发, 底层编程, 开源项目, 数字货币, 比特币, 系统编程, 网络同步, 网络安全, 网络流量审计, 自定义请求头, 防御绕过, 隐私保护