UTXO快照实战：用utxo-dump解析chainstate链上状态

简介：一款面向比特币开发者与链上数据分析者的 Python 工具，用于从 Bitcoin Core 数据目录快速导出指定区块高度的 UTXO 快照。工具通过命令行参数接收 bitcoind 路径、数据目录与目标高度，支持 reindex 和 verbose 模式，覆盖主网与测试网场景；代码包含 chainstate 状态解析、脚本/公钥处理、b128 变长编码等模块，既可直接运行，也便于二次开发。压缩包共 13 个文件，以 8 个 Python 脚本为核心，涉及命令行入口、UTXO 解析、比特币脚本处理等职责，另有使用说明文档、依赖清单、CSV 辅助数据和 License 文件，整体仅 344KB，轻量紧凑。示例给出 2018 年不同高度（如 511346、506265）的导出命令，可帮助用户快速重现历史时点的 UTXO 集合，用于链上数据研究、钱包同步验证或教学实验等场景。目前已有 181 人学习，是一份小巧实用、值得参考的比特币工具类资源。

1. UTXO 快照不是数据目录备份：utxo-dump 读的是链上状态

做过系统快照（比如在 vbox 里给虚拟机打快照）的人，第一次接触 UTXO 快照时，很容易觉得它就是「把数据目录备份一份」。直到我对着用 utxo-dump 生成的快照文件做校验，才发现这个直觉错得离谱：节点数据目录里的 chainstate 表面上是一堆 LevelDB 文件，实际上里面混着 WAL 日志、未刷盘的内存写缓存，每条记录还被一层 XOR 混淆过，直接拷贝出来的东西既不一致、也没法拿去做分析。

utxo-dump 就是一个专门解决这个问题的实用程序。它直接以只读方式打开节点的 chainstate 数据库，把链上所有未花费交易输出（UTXO）完整读出来，整理成统一的文本或二进制格式落盘。落盘结果可以直接交给 Python 做余额分布统计、脚本类型分析和链上状态审计，不需要把节点重新拉起来。适合手里有一份同步好的 Bitcoin 系节点数据、想把 UTXO 集变成可分析数据集的开发者。下面从 chainstate 的存储结构讲起，落到编译、运行、解析和校验，最后给一份踩坑清单。

2. 快照的底层逻辑：chainstate 里究竟存了什么

2.1 链上状态的最小单位是「一笔未花费输出」

Bitcoin Core 的 chainstate 数据库不是按「地址 → 余额」组织的，而是按「币」组织的。一条 UTXO 记录的键是txid + vout，值是四个字段：

键的构造是 32 字节 txid 加一个 varint 编码的 vout 索引，键名前缀是 0x63（字符c），表示这是一条 coin 记录。数据库里还有B、H、F、R等元数据键，分别对应区块索引、高度映射、快照标志位和混淆密钥。其中R键最关键：节点为了防止磁盘数据被直接扒走，所有键值在读写前都会和一个 32 字节的随机密钥做 XOR。utxo-dump 要做的第一件事，就是读出这把密钥，把后续每一条记录还原成明文。

所以「把 chainstate 拷贝出来」这件事想简单了必然翻车：拷贝出来的值全是混淆过的，用strings看就是乱码；节点运行中时 LevelDB 的 WAL 和内存表里还压着没落盘的数据，拷贝出来的文件本身处于不一致状态。这就是为什么快照必须用工具按格式读，而不是用文件拷贝。

2.2 两种快照格式：给机器看的和给人看的

utxo-dump 一般支持两种输出。文本格式（--format text）每行一条 UTXO，五个字段用冒号分隔：

高度:txid:vout:金额(聪):scriptPubKey(hex)

典型的一行长这样：

800000:02944b5c8f5f16728c4e1f37781d70b60c9a0d8a7e1c3e2b9f0a1b2c3d4e5f60:0:546154:76a9148f6d4c8e9a3b5c2d1e0f4a6b7c8d9e0f1a2b3c4d88ac

二进制格式（--format raw）和节点 RPCdumptxoutset的输出兼容，文件头长这样：

每条记录依次是：txid（32 字节）→ vout（varint）→ height*2 + coinbase 标志（varint）→ 金额（8 字节小端）→ 脚本长度加内容（varint 加定长字节）。注意这里的 varint 不是普通大端数字，而是 CompactSize 编码，后面避坑章节会专门讲它的坑。

2.3 为什么「停节点拷贝」依然不等于快照

有人会问：那我先停节点，再整个目录复制，行不行？文件系统层面是一致的，但还有三个现实问题。第一，chainstate 是 LevelDB，光复制目录而不带上数据库版本信息，换一台机器、换一个节点版本未必打得开。第二，拷贝出来的每个值仍然是 XOR 混淆过的，分析脚本没法直接用。第三，拷贝没有给你一个区块高度锚点，你根本不知道这份数据对应链上哪个位置，后续做审计没法对齐。

常见做法是二选一：用节点自带 RPCdumptxoutset，或者用 utxo-dump 这类工具直读。前者输出二进制快照，适合拿去loadtxoutset做 assumeutxo 加速同步；后者输出文本格式，适合做链上数据分析和审计。如果你的目标是后者，utxo-dump 更顺手，它不要求节点在线，输出也更好对接 Python 生态。

3. 用 utxo-dump 生成一份快照：编译、参数与输出解读

3.1 环境准备：先确认 chainstate 是「干净」的

动手之前先确认两件事。第一，手上有同步完成的节点数据，主网默认在~/.bitcoin/chainstate，测试网在~/.bitcoin/testnet3/chainstate或testnet4/chainstate；第二，节点处于停止状态，或者你复制了一份 chainstate 作为输入。utxo-dump 是直接以只读方式打开 LevelDB 的，节点运行中虽然也能读，但读到的是遍历那一瞬间的数据库状态，高度和余额之间未必对得上。

我把节点数据单独放一个目录，快照输入输出分开，避免把 chainstate 和快照文件混在一起。资源包里带了构建脚本，依赖主要是g++、make和 LevelDB 开发头文件，Debian/Ubuntu 上常见做法是用apt install libleveldb-dev装依赖。

3.2 编译与运行：五个参数一次讲透

cd utxo-dump make -j4 ./utxo-dump \ --chain ~/.bitcoin/chainstate \ --output /tmp/utxo_snapshot.txt \ --height 0 \ --format text \ --progress 1000000

make -j4是并行编译，核数多可以调大。运行命令里五个参数的作用：

--height 0是我最常用的写法，直接取区块索引里记录的最佳高度。如果你要的是某个历史高度的状态，就得确保节点已经用-stopatheight之类的方式停在那个高度，否则 chainstate 里根本没有历史状态可选，这个后面避坑章节会展开。

跑完之后重点核对三样东西：日志里打印的 UTXO 总数、文件的实际行数、以及最后一行的区块高度。行数和总数对不上，说明输出被中断过，这种文件不要用。

3.3 输出解读：一行记录里的五个字段

用tail看输出文件，以刚才那行为例：

800000:02944b5c8f5f16728c4e1f37781d70b60c9a0d8a7e1c3e2b9f0a1b2c3d4e5f60:0:546154:76a9148f6d4c8e9a3b5c2d1e0f4a6b7c8d9e0f1a2b3c4d88ac

从左到右：800000是这笔输出所在的区块高度；02944b...是 64 位十六进制的交易哈希；0是 vout 索引；546154是金额，单位是聪，换算成 BTC 要除以 10^8；最后一段76a914...88ac是锁定脚本的十六进制，这里的76 a9 14开头和88 ac结尾是标准 P2PKH 锁定脚本的特征。字段之间用冒号分隔，行尾是\n，解析时按行切分最稳妥。

提示：文本格式为了可读性牺牲了体积，一个主网全量快照可能有数 GB。追求加载速度或磁盘占用，用--format raw更合适。

4. Python 解析快照：生成器、哈希校验与脚本类型统计

4.1 最小解析器：把快照变成可迭代对象

拿到文本快照后，最常见的需求是「按条件过滤 + 统计」。我不建议一次性read()把几 GB 的文件全部装进内存，那样很快会 OOM。正确做法是写成生成器，逐行处理，内存占用恒定：

def parse_snapshot(path: str): """逐行解析 utxo-dump 文本快照，产出 (height, txid, vout, amount, script)""" with open(path, "r", encoding="utf-8") as f: for line in f: line = line.rstrip("\n") if not line: continue height, txid, vout, amount, script = line.split(":") yield int(height), txid, int(vout), int(amount), bytes.fromhex(script)

逻辑说明：每行拆成五个字段，bytes.fromhex把脚本还原成字节串，后续判断脚本类型直接取首字节。这里的性能细节是只做rstrip("\n")而不是strip()，因为冒号分隔的字段本身不会有多余空白，strip()会复制字符串，行数上亿时这个开销不可忽略。

4.2 校验哈希：快照有没有被写坏，一算便知

文本快照的完整性校验，一般是对规范化后的文件内容做两次 SHA256，再把摘要反序输出，和生成方提供的哈希比对。规范化指的是行尾统一\n、字段顺序固定、金额用整数聪，任何一处不一致算出来的哈希都不同。我一般用分段读取，避免把文件整体载入内存：

import hashlib def snapshot_hash(path: str) -> str: """对快照内容做双重 SHA256，返回反序 hex""" first = hashlib.sha256() with open(path, "rb") as f: for chunk in iter(lambda: f.read(1024 * 1024), b""): first.update(chunk) second = hashlib.sha256(first.digest()).digest() return second[::-1].hex()

逻辑说明：双层哈希（先对整个文件内容做一次 SHA256，再对摘要做一次）是比特币系工具最常用的哈希手法；[::-1]反序是因为节点显示哈希时习惯用小端序。比对时两边必须用同一个规范化规则，我的习惯是「谁生成快照，谁就把规范写进旁边的 META 文件」，不要假设对方默认和你一样。

4.3 统计脚本：脚本类型和余额分布一次跑出来

有了生成器，统计就很简单了。下面这段按脚本前缀分类，输出 P2PKH / P2SH / P2WPKH / P2TR 的数量和金额合计：

from collections import Counter def analyze(path: str): counts = Counter() amounts = Counter() total = 0 for height, txid, vout, amount, script in parse_snapshot(path): total += 1 if script.startswith(b"\x76\xa9"): # 76 a9 14 <20字节> 88 ac kind = "P2PKH" elif script.startswith(b"\xa9"): # a9 14 <20字节> 87 kind = "P2SH" elif script[:2] == b"\x00\x14": # 00 14 <20字节> kind = "P2WPKH" elif script[:2] == b"\x51\x20": # 51 20 <32字节> kind = "P2TR" else: kind = f"other({script[0]:02x})" counts[kind] += 1 amounts[kind] += amount for kind in counts: sats = amounts[kind] print(f"{kind:<12} 数量={counts[kind]:>12} 金额={sats / 1e8:>14.8f} BTC") print(f"总计 {total} 条 UTXO")

参数说明：script[:2]取前两个字节判断类型，P2WPKH 是00 14开头（隔离见证版本 0 + 20 字节哈希），P2TR 是51 20开头（版本 1 + 32 字节哈希）。注意script.startswith(b"\x76\xa9")比只判断script[0] == 0x76更稳，可以过滤掉极少数以76 a9开头的自定义脚本。

5. 避坑清单：快照 UTXO 的五个常见翻车现场

5.1 节点还在跑，dump 出来的余额和高度对不上

现象：utxo-dump 跑完，日志显示处理到高度 800123，但用第 4 章的脚本统计总余额，和区块浏览器给出的该高度数据差了几十上百个币。

原因：节点运行中，chainstate 每时每刻都在被写。utxo-dump 以只读方式打开 LevelDB，读到的是遍历那一瞬间的数据库状态，先读的键和后读的键可能分属不同的数据库写入版本，行数对得上、余额对不上。

解决：先停节点再 dump；或者等节点完全退出后用cp -r复制一份 chainstate，把--chain指向副本。想完全不停节点，就用 RPCdumptxoutset，它拿的是节点内部锁，一致性有保证。

5.2 解析出来的脚本全是乱码：忘了 XOR 混淆

现象：脚本字段不是76a914...这种正常样子，而是毫无规律的字节；或者所有金额都大得离谱。

原因：chainstate LevelDB 里的值全部经过 XOR 混淆，密钥存在R键下。utxo-dump 会自动处理这一步，但如果输入路径指错了（比如指到没挂载完整的旧目录），或者你拿自己写的脚本直接去读 LevelDB，就会拿到混淆前的原始字节。

解决：确认--chain指向的目录和节点版本匹配。如果自己实现 LevelDB 读取逻辑，第一步永远是读R键拿到 32 字节密钥，然后对每个键值做 XOR。在怀疑「节点版本太新、格式改了」之前，先验证混淆这一步。

5.3 varint 解析错位：脚本类型统计全歪

现象：第 4 章的统计脚本跑出来，P2SH 占比异常高，或者出现大量other(00)。

原因：快照里凡是长度、数量字段，用的都是 CompactSize varint 编码。规则是：值小于 0xfd 用 1 字节；0xfd 开头后面跟 2 字节；0xfe 开头跟 4 字节；0xff 开头跟 8 字节。如果固定按 1 字节读长度，遇到超过 252 字节的长脚本就会错位，后面的字段全部读歪。

解决：自己解析二进制快照时，写一个read_compact_size函数，按上面四条分支读取。验证方法很直接：先解出第一条记录的 scriptPubKey，和一个已知地址或交易对一下；或者用文本格式在同一高度交叉验证。

5.4 哈希对不上：不是文件坏了，是两边规范不一致

现象：生成方提供的校验哈希，和本地snapshot_hash()算出来的永远不一致。

原因：最常见的三个差异是行尾（\nvs\r\n）、金额单位（聪 vs BTC）、脚本 hex 大小写。任何一处不一致，SHA256 结果就完全不同，而且这种错误没有任何提示，只能靠排除法定位。

解决：约定统一规范：文本快照一律\n结尾、金额用整数聪、hex 用小写，并把规范写进快照旁的 META 文件。校验前先做一次行尾和大小写的归一化，再算哈希。

5.5 磁盘写满留残卷：第二次跑总在同一个地方挂

现象：dump 到一半磁盘满了，进程退出；清掉空间再跑，新文件还是很快报错，或者解析时文件尾部全是半截数据。

原因：工具直接把内容往目标文件写，中途挂了就留一个残缺文件。第二次运行还在写同一路径时，残留状态会干扰新任务；即使换了路径，解析脚本也没法分辨文件是否完整，照样拿残缺数据往下算。

解决：工具支持临时文件的话，强烈建议--output指到.tmp后缀路径，跑完用mv原子改名。跑完第一步永远是比对「头部声明的 UTXO 总数」和「实际行数」，对不上直接删了重来，不要抱着侥幸心理继续分析。

6. 进阶：把快照变成可查询数据集的流式处理技巧

6.1 流式过滤：不要为了查一个条件加载整个快照

def filter_by_script_prefix(path: str, prefix: bytes): """按脚本前缀过滤，例如只留 P2TR: prefix=b'\x51\x20'""" for height, txid, vout, amount, script in parse_snapshot(path): if script.startswith(prefix): yield height, txid, vout, amount, script

逻辑说明：生成器链式处理，内存占用恒定为单条记录大小。我一般在外层再套一个进度回调，每处理 500 万条打一行日志，长任务跑起来心里有数。parse_snapshot是生成器，filter_by_script_prefix也是生成器，两层都不会把数据一次性加载进内存。

6.2 大批量分析：先导入 SQLite 再做聚合

如果要做多条件聚合（按高度段 + 脚本类型 + 金额区间组合查询），Python 里的Counter就不够用了。我的习惯是把快照导入 SQLite，用 SQL 做聚合，导入同样走流式：

import sqlite3 def import_to_sqlite(path: str, db_path: str): con = sqlite3.connect(db_path) con.execute("CREATE TABLE IF NOT EXISTS utxo (height INTEGER, txid TEXT, vout INTEGER, amount INTEGER, script BLOB)") con.execute("BEGIN") batch = [] for height, txid, vout, amount, script in parse_snapshot(path): batch.append((height, txid, vout, amount, sqlite3.Binary(script))) if len(batch) >= 100_000: con.executemany("INSERT INTO utxo VALUES (?, ?, ?, ?, ?)", batch) batch.clear() if batch: con.executemany("INSERT INTO utxo VALUES (?, ?, ?, ?, ?)", batch) con.commit() con.execute("CREATE INDEX idx_utxo_height ON utxo(height)") con.commit() con.close()

参数说明：BEGIN显式开启事务，10 万条一批提交，比逐条自动提交快两个数量级；最后按height建索引，后续「查某个高度段的余额分布」就是索引扫描。脚本存 BLOB 而不是 hex 文本，查询时在 SQL 里用substr(script, 1, 2)判断类型，性能比 Python 侧过滤高得多。

这份资源里通常带编译好的工具、示例快照和一个能直接跑的 Python 解析脚本，下载后按第 3 章的流程对着跑一遍，十分钟内应该能出第一份统计结果。从那以后，我每次跑 utxo-dump 都强制走一遍五步流程：停节点 → 确认高度 → dump 到临时文件 → 核验总数和哈希 → rename。中间任何一步失败就从头来，绝不抱着「数据差不多能用」的心态往下走——UTXO 快照这种一次几 GB 的东西，错了不是重跑一遍那么简单，而是你后面所有分析结论全部作废。希望这套流程和上面的解析脚本能帮到你。

本文还有配套的精品资源，点击获取