prettydeath/coinjoin-tracer

# coinjoin-tracer **Bitcoin CoinJoin 取证 —— Whirlpool 与 Wasabi 检测、匿名性评分，以及基于公开链上数据的混币后去匿名化。**     `coinjoin-tracer` 接收一个 Bitcoin 交易 ID 或地址，并分析其 参与 **Samourai Whirlpool** 和 **Wasabi** (ZeroLink / WabiSabi) CoinJoin 的情况。它会对混币过程进行分类，对实际达成的匿名性进行评分，剖析 Whirlpool Tx0 的“有毒零钱”，并且——最实用的功能是——找出会破坏混币效果的**混币后合并**交易。它仅使用通过无需密钥的 mempool.space API 获取的**公开**数据，并且不会破坏任何加密体系。 ## 关于 CoinJoin 将等值的比特币集中在一起以混淆输入→输出的映射关系，但这种隐私非常脆弱：金额不等的零钱、地址重复使用，尤其是**随后将混币后的比特币一起花费**都会重新建立关联。`coinjoin-tracer` 能够检测出混币交易并准确暴露出这些错误。完整背景信息请参阅：[`ABOUT.md`](ABOUT.md)。 ## 目录 - [关于](#about) - [工作原理](#how-it-works) - [安装](#install) - [配置](#configure) - [用法](#usage) - [交易 — `tx`](#transactions--tx) - [地址 — `address`](#addresses--address) - [输出](#output) - [项目结构](#project-layout) - [方法论](#methodology) - [局限性](#limitations) - [法律与伦理](#legal--ethics) - [许可证](#license) ## 工作原理 Bitcoin CoinJoin 具有可识别的**结构指纹**： | 类型 | 指纹 | |------|-------------| | Whirlpool 混币 | 5 个输入，5 个输出，全部等于资金池面额 (0.001/0.01/0.05/0.5 BTC) | | Whirlpool Tx0 | 资金池面额的预混币输出 + 协调员费用 + 非面额的**有毒零钱** | | JoinMarket | 少量 (3–15) 等额输出 + 一组数量相近的零钱输出，无协调员费用 | | Wasabi 1.0 | 大规模轮次，包含大量完全相同的输出（基础约 0.1 BTC） | | Wasabi 2.0 | 大规模轮次，其输出大多为 WabiSabi 标准面额 | 一个极小值（dust floor）下限排除了 inscription / Runes 批量交易，这些交易同样包含大量等值输出，但金额极小。随后，该工具会衡量**匿名性**（单笔输出的匿名集、确定性关联、组合匿名比特），隔离出**有毒零钱**，并将**共同输入所有权**启发式算法应用于非 CoinJoin 花费，以检测**混币后合并**——即当混币后的比特币被合并使用，导致混币效果被抵消的情况。 完整说明请参阅：[`docs/METHODOLOGY.md`](docs/METHODOLOGY.md)。 ## 安装 ``` git clone https://github.com/prettydeath/coinjoin-tracer.git cd coinjoin-tracer python -m pip install -r requirements.txt # or: pip install -e . ``` 需要 Python 3.9+ 和 `requests`。无需 API 密钥（mempool.space 是免密钥的）。 ## 配置 配置是**可选的**——该工具开箱即用，可直接对接 mempool.space。如需使用自定义 endpoint 或 blockchair 密钥以获得更高的速率限制： ``` cp config/api.csv.example config/api.csv ``` ``` setting,value base_url,https://mempool.space/api blockchair_key, ``` 目标可以通过命令行传入，也可以通过带有 `value` 列的 CSV 文件传入（参见 `config/txids.csv.example`、`config/addresses.csv.example`）。 ## 用法 所有命令：`python -m coinjoin_tracer ...`（如果已安装，则为 `coinjoin-tracer `）。 ### 交易 — `tx` 对交易进行分类，对匿名性进行评分，并剖析 Whirlpool Tx0： ``` python -m coinjoin_tracer tx [ ...] --out-dir out/tx python -m coinjoin_tracer tx --txids-csv config/txids.csv --out-dir out/tx --trace-change ``` `--trace-change` 会向前追踪 Tx0 的有毒零钱一跳。 ### 地址 — `address` 分析地址的 CoinJoin 参与情况、钱包集群 (CIOH) 以及混币后合并事件： ``` python -m coinjoin_tracer address --out-dir out/addr python -m coinjoin_tracer address --addresses-csv config/addresses.csv --out-dir out/addr --max-txs 60 ``` `--shallow` 跳过输入来源查找（速度更快，但不进行合并检查）。 ### 寻找真实交易进行分析 `tools/find_coinjoins.py` 会扫描指定的区块范围，并列出它发现的 CoinJoin，这样您就可以将真实的 txid 提供给上述命令。它会在运行过程中将结果写入 CSV，并可以通过状态文件从中断的扫描处恢复继续。 ``` python tools/find_coinjoins.py --start-height 833000 --blocks 200 \ --limit 10 --out found_coinjoins.csv # 仅限 Whirlpool mixes： python tools/find_coinjoins.py --start-height 720000 --blocks 500 \ --types whirlpool_mix --out whirlpool.csv ``` ### 常用选项 | 标志 | 含义 | |------|---------| | `--out-dir` | 写入 CSV 报告文件的目录 | | `--api-csv` | 包含 `base_url` / `blockchair_key` 的可选 CSV | | `--max-txs` (address) | 每个地址扫描的最大交易数（默认为 40） | | `--trace-change` (tx) | 向前追踪 Whirlpool Tx0 的有毒零钱 | ## 输出 每个命令都会在控制台打印一份摘要，并在使用 `--out-dir` 时写入纯 **CSV** 文件。 **`tx`** → `detections.csv`, `entropy.csv`, `tx0_breakdown.csv`, `tx0_change_trace.csv` **`address`** → `participations.csv`, `post_mix_consolidations.csv`, `wallet_cluster_cioh.csv`, `address_summary.csv` 示例输出位于 [`examples/`](examples/)。 ## 项目结构 ``` coinjoin-tracer/ ├── coinjoin_tracer/ # Python package │ ├── constants.py # pool denoms, Wasabi params, labels │ ├── config.py # CSV loaders (optional API settings, targets) │ ├── api.py # keyless Bitcoin client (mempool.space + blockchair) │ ├── detect.py # CoinJoin type detection (Whirlpool/Wasabi) │ ├── entropy.py # anonymity-set & entropy metrics │ ├── tx0.py # Whirlpool Tx0 entry + toxic-change trace │ ├── cluster.py # CIOH clustering & post-mix consolidation │ ├── report.py # CSV report writers │ └── cli.py # argparse CLI (tx / address) ├── tools/find_coinjoins.py # scan a block range for real CoinJoins (resumable) ├── config/ # *.example CSVs (real files are git-ignored) ├── examples/ # sample CSV outputs + walkthrough ├── docs/METHODOLOGY.md # detection fingerprints, entropy, heuristics ├── ABOUT.md ├── requirements.txt ├── pyproject.toml └── LICENSE ``` ## 方法论 有关检测指纹、匿名性指标以及 CIOH / 合并启发式算法，请参阅 [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md)。 ## 局限性 - **检测是可靠的；关联则是概率性的。** 请辅证调查线索。 - **Wasabi 2.0** 避免了等额输出，因此其单笔输出的匿名性是一个较弱的信号；不过合并分析依然适用。 - **1 跳**有毒零钱追踪；更深的链需要多次运行。 - **协调员已停止服务**（Whirlpool 于 2024 年 4 月，Wasabi 于 2024 年 6 月）——分析主要基于历史数据，但每一笔交易都依然留在链上可供读取。 - **速率限制。** 公开浏览器会进行节流；大型地址最多扫描至 `--max-txs`。 ## 法律与伦理 仅用于基于**公开**区块链数据的合法合规、调查和学术目的。您有责任遵守所有适用法律以及任何数据提供商的服务条款。本工具不执行任何黑客操作，不利用任何漏洞，也不会泄露任何链上原本未公开的内容。 ## 许可证 [MIT](LICENSE)

标签：CoinJoin追踪, GitHub, Python, 区块链分析, 匿名溯源, 数据取证, 无后门, 比特币, 逆向工具