hashhog/ouroboros

# ouroboros 用 Python 和 Rust 编写的比特币全节点。 ## 快速启动 ### Docker ``` docker build -t ouroboros . docker run -v ouroboros-data:/data -p 48350:48350 -p 48340:48340 ouroboros ``` ### 从源码编译 ``` ./setup.sh source .venv/bin/activate # 同步区块链 ouroboros --network testnet4 sync # 启动节点 ouroboros --network testnet4 start --rpc-port=48350 --p2p-port=48340 # 检查状态 ouroboros status ``` ## 功能特性 - 全区块与交易验证（SegWit P2WPKH/P2WSH、Taproot、BIP65/66/68 时间锁、签名操作计数） - 脚本解释器（所有标准操作码、P2PKH、P2SH、P2WPKH、P2WSH、P2TR、NULLFAIL、MINIMALIF、WITNESS_PUBKEYTYPE、见证 cleanstack、FindAndDelete、OP_CODESEPARATOR） - 优先头部同步（完整 PoW 验证） - Rust 加速同步引擎（PyO3 绑定）的区块下载 - 内存池（祖先/后代限制，25 笔交易，101KB） - 完整的 RBF（BIP-125）支持 mempoolfullrbf - TRUC（v3 交易）策略与临时尘埃 - 数据包中继与 CPFP（BIP-331 P2P 消息：sendpackages、getpkgtxns、pkgtxns、ancpkginfo） - BIP-339 WTXIDRELAY 与 BIP-155 SENDADDRV2 协商 - BIP-155 ADDRv2（Tor v3、I2P、CJDNS 地址） - BIP-324 v2 加密传输 - 日食攻击缓解（分桶地址管理、/16 网络组多样性、锚点连接、探测连接） - 过期提示检测与对等节点驱逐（ConsiderEviction、额外出站连接） - 交易微批处理（Poisson 时间调度的中继以提升隐私） - 预握手对等节点过滤（协议版本检查、超时） - 紧凑区块（BIP-152） - 基于 Minisketch 的 Erlay 协调 - PSBT（BIP-174/370，创建、签名、合并、最终化、Taproot 字段） - 输出描述符（BIP380-386：pk、pkh、wpkh、tr、sh、wsh、multi、sortedmulti、combo、addr、raw） - Miniscript（BIP-379：解析、类型检查、编译为 Script、见证大小分析） - 签名验证缓存（LRU，在重组时清除） - 费用估算（确认目标、分桶跟踪） - 区块模板构造（getblocktemplate 遵循 SegWit 规则） - REST 接口供区块浏览器使用（区块、交易、头部、UTXO、内存池、链信息） - ZMQ 通知（hashblock、hashtx、rawblock、rawtx、sequence） - Tor SOCKS5 代理支持 - 区块修剪（pruneblockchain RPC） - 链管理（invalidateblock、reconsiderblock RPC） - 回归测试模式（generatetoaddress、generateblock RPC） - 多钱包支持（createwallet、loadwallet、unloadwallet） - 钱包加密（encryptwallet、walletpassphrase、walletlock、walletpassphrasechange） ## 配置 ### CLI 参数 全局选项（在命令之前）： | 参数 | 默认值 | 描述 | |------|---------|-------------| | `--data-dir DIR` | `~/.ouroboros` | 数据目录（环境变量：`OUROBOROS_DATADIR`） | | `--config FILE` | `$datadir/ouroboros.conf` | 配置文件路径 | | `--network NET` | `mainnet` | 网络：mainnet、testnet、testnet3、testnet4、regtest、signet | | `--debug` | off | 启用调试日志（同时设置 `OUROBOROS_VERBOSE=1`） | | `--log-json` | off | 输出结构化 JSON 日志行 | `start` 命令选项： | 参数 | 默认值 | 描述 | |------|---------|-------------| | `--rpc-port PORT` | `8332` | RPC 服务器端口 | | `--p2p-port PORT` | `8333` | P2P 网络端口 | | `--listen/--nolisten` | listen | 接受入站 P2P 连接 | | `--connect ADDR` | none | 连接到指定对等节点（可重复） | | `--force` | off | 跳过同步检查提示 | `sync` 命令选项： | 参数 | 默认值 | 描述 | |------|---------|-------------| | `--reset` | off | 在同步前清除链状态 | | `--limit N` | none | 仅同步前 N 个区块 | ### 命令 | 命令 | 描述 | |---------|-------------| | `sync` | 同步区块链（初始区块下载） | | `start` | 启动比特币节点 | | `status` | 显示节点状态 | | `getbalance` | 获取地址余额 | | `import-utxo` | 从 HDOG 文件导入 UTXO 快照 | | `import-blocks` | 从帧二进制文件或标准输入导入区块 | ### 配置文件 `ouroboros.conf` 位于数据目录（键值格式，可选 `[section]` 标题）： ``` network=testnet4 rpcport=48350 rpcuser=myuser rpcpassword=mypass p2pport=48340 maxconnections=125 listen=1 rest=1 proxy=127.0.0.1:9050 zmqpubhashblock=tcp://127.0.0.1:28332 zmqpubhashtx=tcp://127.0.0.1:28333 i2psam=127.0.0.1:7656 torcontrol=127.0.0.1:9051 [testnet4] rpcport=48350 ``` 环境变量 `OUROBOROS_` 会覆盖配置文件中的值。 ## RPC API 通过 FastAPI 提供与 Bitcoin Core 兼容的 JSON-RPC，支持批量请求和速率限制。 | 类别 | 方法 | |----------|---------| | 区块链 | `getblockchaininfo`, `getblock`, `getblockhash`, `getblockheader`, `getblockcount`, `getbestblockhash`, `getchaintips`, `getchaintxstats`, `getdifficulty`, `gettxout`, `gettxoutsetinfo`, `getblockfilter`, `verifychain` | | 交易 | `getrawtransaction`, `sendrawtransaction`, `decoderawtransaction`, `decodescript`, `createrawtransaction`, `signrawtransactionwithkey`, `testmempoolaccept`, `submitpackage`, `gettxoutproof`, `verifytxoutproof` | | 内存池 | `getmempoolinfo`, `getrawmempool`, `getmempoolancestors`, `getmempooldescendants`, `prioritisetransaction` | | 挖矿 | `getblocktemplate`, `submitblock`, `submitblockbatch`, `getmininginfo`, `getnetworkhashps`, `generatetoaddress`, `generateblock` | | 网络 | `getpeerinfo`, `getnetworkinfo`, `getconnectioncount`, `addnode`, `disconnectnode`, `setban`, `listbanned`, `clearbanned`, `getnettotals` | | 钱包 | `createwallet`, `loadwallet`, `unloadwallet`, `listwallets`, `listwalletdir`, `getnewaddress`, `getrawchangeaddress`, `getbalance`, `sendtoaddress`, `listunspent`, `listtransactions`, `gettransaction`, `getwalletinfo`, `getaddressinfo`, `keypoolrefill`, `sethdseed`, `importprivkey`, `dumpprivkey`, `backupwallet`, `bumpfee` | | 钱包安全 | `encryptwallet`, `walletpassphrase`, `walletlock`, `walletpassphrasechange` | | 描述符 | `getdescriptorinfo`, `deriveaddresses`, `importdescriptors`, `listdescriptors` | | PSBT | `createpsbt`, `decodepsbt`, `combinepsbt`, `finalizepsbt` | | 工具 | `validateaddress`, `estimatesmartfee` | | 链管理 | `invalidateblock`, `reconsiderblock`, `pruneblockchain` | | 控制 | `help`, `stop`, `uptime`, `getrpcinfo`, `getindexinfo` | 当配置中设置 `rest=1` 时，REST 接口可用，接口包含区块、交易、头部、UTXO、内存池和链信息端点。 ## 监控 内置 Prometheus 指标导出器（需要 `prometheus_client` 包）。默认在 9332 端口启动 HTTP 服务器。 导出的指标包括： - `ouroboros_height` — 当前链尖高度 - `ouroboros_chain_difficulty` — 当前链难度 - `ouroboros_peers_connected` — 已连接对等节点数量 - `ouroboros_mempool_size` / `ouroboros_mempool_tx_count` — 内存池统计 - `ouroboros_utxo_cache_size` / `ouroboros_utxo_cache_hit_rate` — UTXO 缓存性能 - `ouroboros_blocks_received` / `ouroboros_tx_received` — 累计计数器 - `ouroboros_rpc_requests` / `ouroboros_rpc_duration` — RPC 服务器指标 - `ouroboros_stale_tip_detected` / `ouroboros_peer_evictions` — 健康指标 ## 架构 ouroboros 采用混合的 Python/Rust 架构。性能关键型的区块同步引擎、链验证和 UTXO 集管理由 Rust 实现，并通过 PyO3 绑定暴露给 Python（使用 maturin 构建）。这允许 Rust 层以原生速度处理计算密集型的初始区块下载，而 Python 提供应用逻辑、RPC 服务器、内存池和通过 asyncio 事件循环的 P2P 网络。 Python 层使用 FastAPI 提供 JSON-RPC 接口，自动进行请求验证和异步请求处理。点击（Click）库组织 CLI 子命令（sync、start、status），Rich 提供带进度条和状态表的格式化终端输出。配置遵循 Bitcoin Core 约定，使用支持 `[section]` 标题的 `ouroboros.conf` 文件，并可通过环境变量覆盖。 P2P 网络层在 Python asyncio 上运行，管理对等连接、协议握手和消息分发。日食攻击缓解措施包括基于 /16 网络组的分桶地址管理、重启恢复用的锚点连接，以及探测新地址的探测连接。过期提示检测遵循 Bitcoin Core 的 ConsiderEviction 逻辑，当链尖落后时打开额外出站连接。 内存池强制执行祖先和后代限制（25 笔交易、101KB 聚合虚拟大小），并支持完整的 RBF 和 TRUC（v3）策略，用于拓扑受限的交易。数据包中继实现 BIP-331，在数据包边界上进行子节点支付费用评估。Prometheus 指标模块提供可选的观测性，包括链高度、对等数量和 UTXO 缓存性能的计数器，以及 RPC 延迟的直方图。 ## 性能架构 ouroboros 将工作分离为两层，以最小化初始区块下载期间的 Python 开销： ### 初始区块下载（IBD） **Rust 高速路径（ferrous-utils/sync）** - 区块与交易存储 — 基于 RocksDB 的 UTXO 集与区块索引，通过 `PyBlockchainDB` - 密码学原语 — SHA-NI 加速的双 SHA256、secp256k1 ECDSA/Schnorr，通过 libsecp256k1 并行 Schnorr 验证 - 批量 UTXO 查询 — `get_utxo_batch()` 一次性获取交易所有输入，替代 N 次独立调用并减少 GIL 再获取开销 - 脚本标志、难度重试、检查点与假设有效逻辑 **Python 协调层** - asyncio 事件循环驱动 FastAPI（RPC）、P2P 对等套接字与内存池 - `block_sync._drain_block_buffer` 通过 `asyncio.to_thread` 运行 `validate_block` 和 `connect_block_from_bytes`，使事件循环在区块连接期间保持空闲以服务入站 RPC 请求 - 每连接一个区块后执行 `await asyncio.sleep(0)` 让调度器在验证开始前派发挂起的协程 - `RPCServer._get_deployment_state_cached` 按链高度缓存 BIP9 部署状态，使 `getblockchaininfo` 从不调用 Rust FFI，消除验证线程池的 GIL 争用 - `size_on_disk` 最多每 30 秒重新计算一次，避免重复文件系统遍历 **性能分析方案** ``` # 将 py-spy 附加到正在运行的节点（非侵入式，无需代码更改） sudo py-spy record -o /tmp/ouroboros-prof.svg -d 60 -p $(pgrep -f 'ouroboros.cli') # 50 次调用 RPC 延迟探测 python3 tests/rpc_latency_probe.py --port 8359 --cookie ~/.ouroboros/.cookie --calls 50 # 在进程中用 yappi 进行性能分析（添加到 cli.py 启动项） import yappi; yappi.start(builtins=True) # ... 运行工作负载 ... yappi.stop(); yappi.get_func_stats().print_all() ``` **实测 IBD 延迟**（getblockchaininfo，50 次调用，主网 IBD ~495k）： | 日期 | 优化 | p50 | p95 | 最大 | |------------|-----------------------------|-------|---------|---------| | 2026-04-10 | 基准（async.to_thread） | 4998ms | 10010ms | 10010ms | | 2026-04-10 | +sleep(0) 产出 + 尖端缓存 | 1ms | 1635ms | 1635ms | | 2026-04-11 | +部署缓存 + 批量 UTXO | 1ms | <100ms | <400ms | ## 许可证 MIT

标签：addr, ADDRv2, BIP-125, BIP-152, BIP-155, BIP-174, BIP-324, BIP-331, BIP-339, BIP-370, BIP-379, BIP380, BIP381, BIP65, BIP66, BIP68, CJDNS, combo, CPFP, Docker, Eclipse攻击, Erlay, I2P, LRU, Miniscript, Minisketch, multi, P2P, P2P消息, P2WPKH, P2WSH, pk, pkh, Poisson 定时中继, PSBT, PyO3, Python, raw, Rust, SegWit, sh, sortedmulti, Taproot, Taproot字段, Tor, tr, TRUC, v3交易, wpkh, wsh, WTXID中继, 交易 trickling, 便携式工具, 全中继, 全节点, 内存池, 创建, 加密传输, 加密货币, 包中继, 区块下载, 区块链, 协议版本检查, 去中心化, 可替换花费, 可视化界面, 后代限制, 地址管理, 块模板, 多样性, 头优先同步, 安全防御评估, 尘埃, 工作量证明, 探测节点, 无后门, 时间锁, 最终化, 桶计数跟踪, 比特币, 确认目标, 祖先限制, 签名操作计数, 签名验证缓存, 类型检查, 紧凑区块, 组合, 编译, 网络流量审计, 脚本解释器, 见证大小分析, 解析, 计算机取证, 费用估计, 超时, 输出描述符, 过期间探测, 逆向工具, 重组, 锚点, 隐私, 预握手过滤