kishore08-07/chain-analysis-engine

[](https://classroom.github.com/a/BKxF-kj7) # 第 3 周挑战：Sherlock 构建一个链分析引擎，将链分析启发式算法应用于来自真实区块数据的比特币交易数据集，构建一个 Web 可视化工具来展示和显示结果，并编写记录您发现的 Markdown 报告。 本挑战建立在交易解析器（挑战 1）和 PSBT 构建器（挑战 2）的基础之上。您现在需要在解析出的交易数据之上应用分析推理，以推断模式、识别实体并对交易行为进行分类。 本挑战在启发式算法上是刻意开放的。没有单一的“正确答案”——重要的是您的分析质量、方法的严谨性以及文档的清晰度。 ## 假设 / 范围 - 您**必须**解析原始区块文件（`blk*.dat`、`rev*.dat`、`xor.dat`）以提取交易及其前一个输出（prevout）数据，就像您在挑战 1 中所做的那样。 - 您**不需要**验证签名或执行脚本。 - 您**不需要**连接到节点或外部 API。 - 启发式算法是概率性的——请在 `APPROACH.md` 中记录您的置信度模型和局限性。 ## 交付物 您必须提交以下**所有**内容： 1. **CLI 链分析器** —— 对区块中的每笔交易应用启发式算法，并生成机器可读的 JSON 输出。 2. **Markdown 报告** —— 总结每个区块文件分析结果的人类可读报告。必须提交到 `out/` 目录。 3. **Web 可视化工具** —— 用于探索链分析结果的交互式 UI。 4. **APPROACH.md** —— 记录您的启发式算法、架构、权衡和参考文档。 5. **演示视频** —— Web UI 演示的屏幕录像，链接在 `demo.md` 中。 ## 必需的仓库接口 您的仓库必须包含以下脚本： ### `cli.sh` ``` ./cli.sh --block ``` - 读取区块数据文件并应用链分析启发式算法。 - 为每个区块文件写入输出（其中 `` 是 blk 文件名去掉扩展名后的部分，例如 `blk04330`）： - `out/.json` —— 机器可读的分析报告 - `out/.md` —— 人类可读的 Markdown 报告 - 单个 `blk*.dat` 文件可能包含**多个区块**。JSON 和 Markdown 输出都应涵盖该文件中的所有区块。 - 如果 `out/` 目录不存在，则必须创建它。 - 成功时退出代码为 `0`，出错时为 `1`。 - 错误必须以结构化 JSON 返回：`{ "ok": false, "error": { "code": "...", "message": "..." } }` ### `web.sh` - 启动 Web 可视化工具。 - 必须打印单行包含 URL 的信息（例如 `http://127.0.0.1:3000`）到标准输出。 - 必须保持运行直到被终止（CTRL+C / SIGTERM）。 - 如果设置了 `PORT`，则必须遵循该设置（默认为 `3000`）。 - 必须响应 `GET /api/health` → `200 { "ok": true }`。 ### `setup.sh` - 安装项目依赖。 - 解压区块固件测试文件（`fixtures/*.dat.gz`）。 - 在评分前运行一次。 ## JSON 输出模式 每个 `out/.json` 必须符合以下模式。由于单个 `blk*.dat` 文件可能包含多个区块，输出将每个区块的数据包装在一个 `blocks` 数组中，并附带文件级别的汇总摘要： ``` { "ok": true, "mode": "chain_analysis", "file": "blk04330.dat", "block_count": 2, "analysis_summary": { "total_transactions_analyzed": 4500, "heuristics_applied": ["cioh", "change_detection", "..."], "flagged_transactions": 120, "script_type_distribution": { "p2wpkh": 2100, "p2tr": 900, "p2sh": 300, "p2pkh": 150, "p2wsh": 60, "op_return": 40, "unknown": 10 }, "fee_rate_stats": { "min_sat_vb": 1.0, "max_sat_vb": 800.0, "median_sat_vb": 28.0, "mean_sat_vb": 45.2 } }, "blocks": [ { "block_hash": "", "block_height": 800000, "tx_count": 3000, "analysis_summary": { "total_transactions_analyzed": 3000, "heuristics_applied": ["cioh", "change_detection", "..."], "flagged_transactions": 80, "script_type_distribution": { "p2wpkh": 1200, "p2tr": 500, "p2sh": 200, "p2pkh": 80, "p2wsh": 30, "op_return": 20, "unknown": 5 }, "fee_rate_stats": { "min_sat_vb": 1.0, "max_sat_vb": 800.0, "median_sat_vb": 30.0, "mean_sat_vb": 50.1 } }, "transactions": [ { "txid": "", "heuristics": { "cioh": { "detected": true }, "change_detection": { "detected": true, "likely_change_index": 1, "method": "script_type_match", "confidence": "high" } }, "classification": "simple_payment" } ] } ] } ``` ### 字段要求 **顶层字段：** - `ok`：布尔值，成功时为 `true`。 - `mode`：字符串，始终为 `"chain_analysis"`。 - `file`：字符串，源区块文件名（例如 `"blk04330.dat"`）。 - `block_count`：整数，必须等于 `blocks` 数组的长度。 - `analysis_summary`：文件级别的汇总摘要（见下文）。 - `blocks`：每个区块分析结果的数组。 **文件级 `analysis_summary`：** - `total_transactions_analyzed`：整数，必须等于所有 `blocks[].tx_count` 的总和。 - `heuristics_applied`：应用的启发式算法 ID 数组。必须是所有每个区块的 `heuristics_applied` 的并集。必须包含至少 5 个不同的 ID，包括 `"cioh"` 和 `"change_detection"`。 - `flagged_transactions`：整数，必须等于所有 `blocks[].analysis_summary.flagged_transactions` 的总和。 - `fee_rate_stats`：对所有区块中所有非 Coinbase 交易计算出的费率统计信息。`min_sat_vb` ≤ `median_sat_vb` ≤ `max_sat_vb`，且均为非负数。 **每个区块的字段（`blocks[]` 中的每个元素）：** - `block_hash`：十六进制字符串（64 个字符），标准的反转十六进制显示约定。 - `block_height`：整数，从 Coinbase 的 BIP34 解码。 - `tx_count`：整数，区块中的交易总数。 - `analysis_summary`：每个区块的摘要，形状与文件级摘要相同。`total_transactions_analyzed` 必须等于 `tx_count`。`flagged_transactions` 必须与至少有一个 `detected: true` 启发式算法的交易的实际情况相符。 - `transactions`：每个交易分析结果的数组。**对于第一个区块**（`blocks[0]`）**是必需的**：评分器会验证该数组存在且其长度等于 `tx_count`。**对于后续区块是可选的** —— 您可以省略它或使用空数组以减小 JSON 大小并加快评分速度。 **每个交易的字段（`blocks[].transactions[]` 中的每个元素）：** - `txid`：十六进制字符串（64 个字符）。 - `heuristics`：将启发式算法 ID 映射到结果对象的对象。每个结果必须包含一个 `detected` 布尔值字段。 - `classification`：必须是 `"simple_payment"`、`"consolidation"`、`"coinjoin"`、`"self_transfer"`、`"batch_payment"`、`"unknown"` 其中之一。 ## Markdown 报告要求 对于每个区块文件，在 `out/.md`（例如 `out/blk04330.md`）生成一份 Markdown 报告。该报告应能在 GitHub 上直接渲染，并包含： - **文件概述：** 源文件名、区块数量、分析的总交易数。 - **汇总统计：** 费率分布、脚本类型细分、标记的交易数量（汇总文件中所有区块的数据）。 - **按区块划分的章节：** 针对文件中的每个区块： - 区块哈希、高度、时间戳、交易数量。 - 每个启发式算法的发现：触发了哪些启发式算法以及作用于多少笔交易。 - 值得注意的交易：突出显示被分类为 CoinJoin、合并或其他有趣模式的交易。 使用 Markdown 表格和标题来组织结构。报告大小必须至少为 1 KB（即不能为空或随意生成的内容）。 **重要提示：** Markdown 报告必须提交到 `out/` 目录中。评分器会检查已提交的报告是否存在且可重现（重新运行 `cli.sh` 应生成内容相似的报告）。 ## 启发式算法目录 您必须实现以下启发式算法中的**至少 5 种**。`cioh` 和 `change_detection` 启发式算法是**强制性要求**的。 | ID | Name | 描述 | |---|---|---| | `cioh` | Common Input Ownership (共同输入所有权) | 一个交易的所有输入可能属于同一个实体。这是链分析的基础假设：如果多个输入被一起花费，它们可能由同一个钱包控制。标记具有多个输入的交易。 | | `change_detection` | Change Detection (找零检测) | 识别交易中可能的找零输出。方法包括：脚本类型匹配（找零输出与输入脚本类型匹配）、整数金额分析（支付金额通常是整数）、输出排序启发式以及数值分析。报告可能的找零索引、使用的方法和置信度。 | | `address_reuse` | Address Reuse (地址重用) | 检测同一地址何时出现在同一笔交易的输入和输出中，或同一区块内的多笔交易中。地址重用会削弱隐私并将交易关联到同一实体。 | | `coinjoin` | CoinJoin Detection (CoinJoin 检测) | 识别 CoinJoin 交易：来自明显不同所有者的多个输入，以及旨在混淆交易图的等值输出。寻找对称的输出值和较高的输入数量。 | | `consolidation` | Consolidation Detection (合并检测) | 检测合并交易：将许多输入合并为 1-2 个输出，通常具有相同的脚本类型。这些交易减少了 UTXO 集的大小，是常见的钱包维护操作。 | | `self_transfer` | Self-Transfer Detection (自转账检测) | 识别所有输入和输出似乎属于同一实体的交易。所有输出都与输入脚本类型模式匹配，并且交易没有明显的“支付”组成部分。 | | `peeling_chain` | Peeling Chain Detection (剥离链检测) | 检测剥离链模式：一个大的输入被拆分为一个小的输出（支付）和一个大的输出（找零），随后的大输出在接下来的交易中按照相同的模式被花费。 | | `op_return` | OP_RETURN Analysis (OP_RETURN 分析) | 检测 OP_RETURN 输出并按协议（Omni、OpenTimestamps 等）对嵌入的数据进行分类。追踪区块内的使用模式。 | | `round_number_payment` | Round Number Payment (整数金额支付) | 识别值为整数 BTC 金额（例如 0.1 BTC、0.01 BTC、1 BTC）的输出。整数金额的输出更有可能是支付；非整数金额的输出更有可能是找零。 | ## APPROACH.md 要求 您必须在仓库根目录中包含一个 `APPROACH.md` 文件，记录以下内容： 1. **已实现的启发式算法** —— 针对每种启发式算法： - 它检测什么 - 您如何检测/计算它 - 您的置信度模型（您如何评估可靠性） - 已知局限性（误报、漏报、边缘情况） 2. **架构概述** —— 您的代码是如何组织的，使用了哪些语言/框架，数据如何从原始区块文件流向 JSON + Markdown 输出。 3. **权衡和设计决策** —— 准确性与性能、简单性与覆盖率，以及任何其他重大选择。 4. **参考文献** —— 您使用的 BIPs、论文、博客文章或文档。 该文件大小必须至少为 500 字节。 ## Web 可视化工具要求 您的 Web 应用必须： - 提供区块链分析结果的交互式视图。 - 允许用户探索单个交易及其启发式算法结果。 - 可视化模式：突出显示 CoinJoins、合并、标记的交易。 - 显示区块级统计数据：费率分布、脚本类型细分。 - 响应 `GET /api/health` → `200 { "ok": true }`。 推荐功能（非严格要求，但强烈建议）： - 颜色编码的交易分类。 - 按启发式算法或分类进行交互式过滤。 - 显示输入/输出关系的可视化交易图。 - 点击展开每个交易的启发式算法结果的详细信息。 ## 已提交的输出 与挑战 1 和 2 不同，您**必须将 `out/` 目录提交**到您的仓库。此目录应包含： - 固件测试中每个区块文件对应的 `out/.json`（例如 `out/blk04330.json`）。 - 固件测试中每个区块文件对应的 `out/.md`（例如 `out/blk04330.md`）。 评分器将验证这些文件是否存在且可重现。 ## 演示视频 在仓库根目录的 `demo.md` 中包含您的演示视频链接。该文件应仅包含链接。 - **上传位置：** YouTube、Loom 或 Google Drive。该链接必须可供评估者查看，无需请求访问权限（公开或不公开均可；不接受“请求访问”的链接）。 - **录制内容：** 您的 **Web UI** 演示的屏幕录像（无需代码演示；不要花时间滚动浏览源文件）。 - **演示内容：** 使用您的 UI 分析提供的固件测试中的至少一个区块，并演示链分析结果。 - **讲解方式：** 像与非技术人员交谈一样进行讲解，他们希望了解链分析能揭示有关比特币交易的什么信息。 - **您的演示必须涵盖的主题（使用 UI）：** - 什么是链分析以及它对比特币隐私为何重要 - 共同输入所有权启发式算法 (CIOH) —— 它的假设以及揭示了什么 - 找零检测 —— 您的工具如何识别可能的找零输出 - 您实现的至少另一种启发式及其发现了什么 - 交易分类 —— 您的工具如何对交易进行分类 - 区块级统计 —— 费率、脚本类型分布、标记的交易数量 - 来自区块数据的一笔特定的有趣交易，以及您的分析揭示了关于它的什么信息 - **硬性限制：** 视频长度必须严格**少于 2 分钟**。 ## 验收标准 - `cli.sh --block` 在所有提供的区块固件上成功运行 - CLI JSON 输出符合所需的模式（所有字段都存在，类型正确，枚举值有效） - `block_count` 与 `blocks` 数组的长度匹配 - 文件级汇总摘要与每个区块的摘要一致 - 每个区块至少应用了 5 个启发式算法，包括 `cioh` 和 `change_detection` - 第一个区块存在 `transactions` 数组且正确（长度 == `tx_count`） - `flagged_transactions` 数量一致（每个区块的值有效，文件级总和匹配） - 费率统计数据一致（min ≤ median ≤ max，且均为非负数） - Markdown 报告存在于 `out/` 目录中对应于每个区块文件，并且可重现 - `APPROACH.md` 存在并记录了至少 5 种启发式算法 - Web 应用通过 `web.sh` 启动并响应 `GET /api/health` → `200 { "ok": true }` - 演示视频链接包含在 `demo.md` 中 - 错误以结构化 JSON 返回，带有非空的 `error.code` 和 `error.message` ## 评估标准 评估分两个阶段进行： ### 阶段 1：自动评估（截止日期前） - **模式验证：** 检查 JSON 输出是否包含必填字段、类型是否正确以及值是否有效。 - **启发式覆盖率：** 至少应用了 5 种启发式算法，`cioh` 和 `change_detection` 为强制要求。 - **交易验证：** 仅验证第一个区块的 `transactions` 数组（类型检查 + 长度 == tx_count）。后续区块可以省略。 - **一致性检查：** `flagged_transactions` 有效（0 ≤ n ≤ tx_count），费率统计顺序正确，文件级汇总与每个区块的数据匹配。 - **报告可重现性：** 已提交的 Markdown 报告存在，并且重新运行 `cli.sh` 会生成相似的报告。 - **文档：** `APPROACH.md` 存在且内容充实（>500 字节），并涵盖至少 5 种启发式算法。`demo.md` 包含有效的视频链接。 - **Web 健康检查：** `web.sh` 必须启动并响应 `GET /api/health`。 ### 阶段 2：手动评估（截止日期后） - **启发式质量：** 启发式算法是否合理？它们是否产生了有意义的结果？置信度水平是否合适？ - **报告质量：** Markdown 报告中发现的清晰度、完整性和呈现方式。 - **Web UI 质量：** 交互性、视觉设计以及展示分析结果的效果。 - **APPROACH.md 质量：** 解释的深度、对局限性的认识、参考文献的质量。 - **演示视频：** 对必需主题的涵盖程度、解释的清晰度、对 2 分钟时间限制的遵守情况。 - **代码质量：** 可读性、结构以及对抽象的适当使用。 ## 抄袭政策 - 所有提交的代码必须是您自己的原创作品。您可以使用 AI 编程助手（例如 GitHub Copilot、ChatGPT、Claude）作为工具，但您必须理解并能够解释您提交的每一部分内容。 - 严禁从其他参与者（当前或往期学员）的提交中复制代码。 - 鼓励使用开源库和参考公共文档（BIPs、论文、博客文章等）—— 这是研究，而不是抄袭。 - 提交的作品将与其他参与者进行相似度检查。如果两个或更多的提交作品在遵循规范之外共享基本相同的逻辑或结构，所有涉及的提交可能会被取消资格。 - 如果您不确定某事是否算作抄袭，请在提交前询问。

标签：CIOH, CMS安全, CoinJoin, JavaScript, JSON报告, Markdown报告, Python, Web仪表板, 交易解析, 加密货币取证, 区块链分析, 区块链安全, 匿名性分析, 启发式分析, 实体行为识别, 实时处理, 数据可视化, 数据聚类, 无后门, 比特币, 逆向工具, 链上分析, 隐私泄露检测, 零钱地址检测