storagebirddrop/jackdawsentry-graph

# Jackdaw Sentry 图 支持通过 Lightning / Nostr： `npub1p0jkd532p3c0za2s7fugq0tx30xm2e4v03n6udkqze6ercyf5fesgsy9fv@npub.cash` Jackdaw Sentry Graph 是一个自托管、开源的区块链调查工具，旨在让资金追踪无需昂贵的行业 API 即可实现。 大多数专业追踪工具需要 Chainalysis、Elliptic 或类似订阅服务。此项目面向其他所有人：试图追踪资金的受害者和黑客、想了解资金去向的好奇新手，以及资源不足但需要可靠工具而无需企业级价格的调查人员。 摄取服务是这一可访问性的核心——它使用免费层级的 RPC 端点重新构建追踪路径，使得图结构即使在无法访问行业数据馈送时也能扩展。 在可能的情况下，公开演示将在线提供。但需要注意的是，共享实例上的性能始终有限——对于严肃调查工作，强烈建议在本机或自托管环境中运行。自托管路径是该项目的首要目标，而非事后的考虑。 此工具专门设计用于处理以下难点： - 追踪智能合约（EVM DEX 交换、聚合器跳转、桥接合约） - 跨链流动：资产在不同网络间桥接时的追踪 - 在同一会话中对 Bitcoin 进行 UTXO 级别追踪，同时追踪账户模型链 当前诚实的限制： - **Liquid**：仅标记链上挂入和撤出事件，但不继续在 Liquid 网络内追踪 - **Lightning**：标记通道开启和关闭事件，但通道内路由不可追踪 ## 重要免责声明 本项目是一个生产就绪的独立调查工具，处于持续开发中。图结构是调查的起点，而非最终结论。结果绝不应被视为绝对事实——地址标签可能不完整，启发式规则可能误判，底层数据依赖于已编入索引的内容。 使用此工具构建画面并生成线索，然后通过阅读实际的区块链数据来验证你发现的内容。此项目的部分目标是鼓励用户了解区块链和智能合约如何工作，并能直接读取——而不是产生一个直接给出答案的黑盒。你越了解底层数据，就越能判断图结构在告诉你什么。 OFAC 制裁名单和已知地址情报正在逐步整合。当某个地址匹配制裁条目或已知实体时，会在图中突出显示；但没有标记并不表示该地址是干净的。 ## 仓库姿态 这是所有新图产品工作的规范主目录。 - 在此处优先构建图功能。 - 将私有仓库 `jackdawsentry` 视为临时集成宿主， 只要它仍在内部服务该图。 - 不要让图的所有权回流到私有仓库。 ### 边界规则 如果图代码依赖于仅存在于私有仓库中的内容，需有意识地解决： 1. 如果是图所拥有的内容，将其移入此仓库； 2. 如果两个仓库确实需要，复制一个最小化的图安全原语； 3. 仅在行为真正属于 专有/平台特定时保留一个薄层的私有适配器。 本仓库有意比私有 Jackdaw Sentry 平台更专注。 ## 范围 - 图会话创建与恢复 - 后端拥有的会话恢复发现与工作区自动保存 - 通过 `ExpansionResponse v2` 进行图扩展 - 桥接跳转状态轮询与基于调用数据的终点解码 - 在扩展遇到空边界时按需地址摄取 - React 调查图 UI - 以图为核心的后端/运行时、合约与测试 **支持的扩展目标：** Bitcoin、Litecoin、Bitcoin Cash、Dogecoin、Lightning Network、Ethereum、BSC、Polygon、Arbitrum、Base、Avalanche、Optimism、Starknet、Injective、Solana、Tron。 **已实现但尚未接入 TraceCompiler 扩展调度：** XRP、Cosmos、Sui。它们的链编译器已存在于仓库中，但图扩展目前返回空结果，直到它们被注册。 **画布上的节点类型：** `address`、`entity`、`utxo`、`swap_event`、`atomic_swap`、`bridge_hop`、`btc_sidechain_peg`、`lightning_channel_open`、`lightning_channel_close`、`solana_instruction`、`cluster_summary`、`service`。 ## 活动图合约 - 非 Bitcoin 地址节点可使用基于检查器的资产范围控制，支持“所有资产”/“特定资产”模式 - 检查器扩展与预览使用当前选定的资产范围；`所有资产` 不发出 `asset_selectors` - 快速 `Prev` / `Next` 重用该节点存储的资产管理范围 - `特定资产` 支持确定性的多资产 `asset_selectors`；未勾选任何资产时，扩展/预览将被禁用，直到至少选择一个资产 - 手动导出/导入和后端会话恢复保留每个节点的资产管理范围 - 后端自动保存会持久化更新的工作区快照，包括 `nodeAssetScopes` - 在 `409` 冲突时，工作区快照版本陈旧会自动暂停并给出诚实提示，而不是静默覆盖更新的保存状态 - 冲突提示提供“加载保存版本”和“保存我的版本” - 自动保存在任一恢复操作成功前保持暂停 - 边缘选择性追踪以 `tx_hash` 优先，且仅在存在安全链内资产身份时最多添加一个 `asset_selector` - EVM、Solana 与 Tron 的资产特定过滤需要链内身份，不会按符号猜测 - 边缘选择性追踪不继承检查器多选 - Bitcoin 不参与资产管理器路径 - `value_fiat` 是规范的活动路径边字段；`fiat_value_usd` 仅作兼容性支持 - 动画桥接边跟随后端 `bridge_source` / `bridge_dest` - 检查器 **过滤与预览** 面板预览扩展而不应用；调查员在提交前查看并选择候选边 - `time_from` / `time_to` 日期范围被扩展 API 接受，并应用于 Bitcoin、EVM 与 Solana 链编译器 - 候选选择仅将选中的边及其可达节点应用到画布 ## 代码库结构 - `src/api/graph_app.py` — 独立的 FastAPI 图运行时入口点 - `src/api/routers/graph.py` — 图会话、扩展、搜索、追踪与状态端点 - `src/api/routers/auth.py` — JWT 认证端点 - `src/trace_compiler/` — 图扩展合约与链感知编译逻辑 - `chains/` — 每条链的处理程序：Bitcoin、EVM、Solana、Cosmos、Sui、Tron、XRP - `bridges/` — 桥接跳转编译与基于调用数据的目的地解码 - `calldata/` — EVM 与 Solana 指令解码器（ABI、Anchor 鉴别器、启发式扫描器） - `ingest/` — 按需实时抓取触发器与链特定抓取器 - `services/` — 地址曝光与服务分类 - `attribution/` — 实体增强 - `src/collectors/` — 每条链的实时区块链数据收集器（带 RPC 抽象层、回填与地址摄取工作器） - `src/tracing/` — 桥接协议注册、跨链桥接追踪器、桥接日志解码器 - `src/services/` — 制裁筛查、价格预言机、合约信息、实体增强 - `frontend/app/` — React 19 + TypeScript 调查图（Zustand、XYFlow、ELK 布局） ## 快速启动 ``` cp .env.example .env docker compose -f docker-compose.graph.yml up -d --build ``` 浏览： ``` http://localhost:8081/ ``` API 文档默认禁用。仅在明确需要在可信环境中使用时，设置 `EXPOSE_API_DOCS=true`。 图 API 服务在 compose 启动期间从仓库 `.env` 加载其模式标志，因此类似 `DEBUG=release` 的环境 shell 值不会意外覆盖独立的图运行时。 受信任的 compose 路径会在 `docker compose ... up --build` 期间将审核后的前端资源打包到 `graph-nginx` 镜像中，因此不再依赖被忽略的本地 `frontend/app/dist` 残留。 ## 发布与演练记录 将面向产品的稳定材料保留在稳定的文档位置： - 发布摘要位于 `docs/releases/` - 演练模板、活动运行与归档证据位于 `docs/drills/` 当前公开发布摘要位于 `docs/releases/2026-03-public-release.md`。 不要为未来的演练创建新的根级 `PHASE*`、`WAVE_*`、`FINAL_*` 或临时交接文件。请改为新建演练文件夹： ``` python scripts/dev/init_drill_run.py my-drill-slug ``` 该脚手架会在 `docs/dills/runs/` 下创建一个带日期的运行目录，包含独立的 `records/` 与 `artifacts/` 文件夹，使仓库根目录保持整洁，并让证据链路可追溯。 独立的本地图堆栈默认仅为图结构： - 不启动实时采集器/回填工作器 - `AUTO_BACKFILL_RAW_EVENT_STORE` 保持 `false`，除非你选择切换运行时 - `Prev` / `Next` 仅扩展已存在于本地事件存储/图数据集中的活动 ### 可选摄取运行时 当你需要实时采集器加上原始事件存储回填时，运行摄取侧车覆盖： ``` docker compose \ -f docker-compose.graph.yml \ -f docker-compose.graph.ingest.yml \ up -d --build ``` 该侧车启动一个独立的 `graph-ingest` 服务。请求服务的 `graph-api` 保持精简，而侧车负责： - 区块链采集器 - 原始事件存储的双向写入 - 回填到 `raw_transactions` / `raw_token_transfers` 摄取侧车使用独立的 env 标志，以便在基础 `.env` 保持请求服务图 API 仅请求模式时仍可默认进行实时摄取： - `GRAPH_INGEST_DUAL_WRITE_RAW_EVENT_STORE` - `GRAPH_INGEST_AUTO_BACKFILL_RAW_EVENT_STORE` - `GRAPH_INGEST_BACKFILL_INTERVAL_SECONDS` - `GRAPH_INGEST_BACKFILL_BLOCK_BATCH_SIZE` - `GRAPH_INGEST_BACKFILL_CHAINS_PER_CYCLE` - `GRAPH_INGEST_BACKFILL_BLOCK_TIMEOUT_SECONDS` 你可以通过认证状态端点检查是否正在观察摄取侧车： ``` GET /api/v1/status ``` `runtime.ingest.detected=true` 表示图 API 当前可在 Redis 中看到采集器指标。若为 `false`，则仍处于请求仅模式。 对于本地图探索，首先加载代表性数据： ``` python scripts/dev/load_perf_fixture_dataset.py ``` ### 会话恢复与自动保存 近期的调查恢复现为后端托管： - 前端从 `GET /api/v1/graph/sessions/recent` 发现可恢复会话 - 权威工作区来自 `GET /api/v1/graph/sessions/{session_id}` - 自动保存回写至 `POST /api/v1/graph/sessions/{session_id}/snapshot` 当前发布的持久化行为： - 每节点资产管理范围的手动导出/导入往返 - 后端会话恢复返回保存的 `nodeAssetScopes` 到权威工作区快照 - 后端自动保存持久化更新的工作区快照，包括 `nodeAssetScopes`，作为同一工作区合同的一部分 - 在 `409` 冲突时，工作区快照版本陈旧会自动安全暂停并显示诚实提示，而不是静默覆盖更新的保存状态 - 恢复 UI 要求明确选择：`保存我的版本` 或 `加载保存版本` - 自动保存在任一恢复步骤成功前保持暂停 浏览器存储在设计上弱于后端合同： - 可保留最近会话提示与安全工作区偏好 - 绝不应成为图画布的事实来源 - 承载令牌保留在 `sessionStorage`，而非 `localStorage` 某些旧会话行仅保留简化种子级快照。发生此情况时，前端会显示 `legacy_bootstrap` 恢复提示，而不是假装已恢复完整画布。 ## 文档 | 主题 | 位置 | |------|------| | 部署 | [DEPLOYMENT.md](docs/DEPLOYMENT.md) | | 配置 | [CONFIGURATION.md](docs/CONFIGURATION.md) | | 功能 | [FEATURES.md](docs/FEATURES.md) | | 故障排查 | [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | ## 最近改进 - **安全性**：修复认证绕过；增加敏感端点的审计日志 - **摄取**：Solana 实时抓取（带 SPL 余额差分解析与速率限制弹性）；在扩展遇到空边界时按需地址触发 - **语义节点**：EVM `swap_event` 从日志感知解码提升；Solana 通用 DEX `swap_event` 支持未注册程序；桥接调用数据终点解码（通过 EVM ABI 与 Solana Anchor 启发式） - **可靠性**：增强错误处理、废弃行回收、空安全 JSON 字段访问、稳健的数据验证 详见 [CHANGELOG.md](CHANGELOG.md) 获取详细技术变更与迁移说明。 ## 开发 本仓库是进行图产品活跃冲刺工作的默认位置。 ## 调查流程 当前的调查外壳围绕以下有意的分析师工作流构建： - 桥接情报卡片直接在画布上展示可见协议、主要路由与桥接跳转状态混合 - 路由聚焦允许调查员将图结构限制在特定协议或路由切片，同时保留周围上下文 - 分支工作区支持单分支聚焦与使用后端分支元数据进行的双分支对比 - `新建调查` 清除当前图并返回种子搜索界面，无需强制登出或完整浏览器刷新 - 固定路径故事让调查员在对比分支或桥接路线时保持少数叙事弧线可见 - 对比简报将活动分支聚焦转化为可见节点、桥接跳转、路径与语义轨道的并排摘要 - 协议图例卡片直接在画布上汇总可见的交换、桥接、Lightning、侧链、服务与 Solana 轨道 - 会话简报将当前可见调查视角转化为可复制或导出的 Markdown 工件 - 检查器是节点细节、谱系、分支操作、固定路径与活跃调查上下文的叙事表面 - 桥接跳转新鲜度由挂载的检查器路径拥有，而非独立侧栏 - 空 `Prev` / `Next` 扩展会说明是否存在未编入索引的活动，或已编入索引但未产生新图结果 在新增图 UX 时，优先选择能帮助分析师回答“这里发生了什么？”或“此分支有何不同？”的操作，而非通用仪表板 chrome。 ## 近期产品优先级 实现完整调查员级覆盖的剩余工作： - 在会话创建/扩展期间运行地址增强，立即对新发现的地址进行筛查并打上制裁/AML/CFT、欺诈与实体标签 - 添加图安全增强适配器，为公共图结构打上 `risk_score`、`sanctioned`、`entity_*` 与欺诈标签 - 深化 EVM `swap_event` 检测，超越当前事务腿推断路径，实现完整的日志感知多跳路由解码 - 解析 Allbridge Core 桥接终点（当前受阻：终点位于临时 PDA；需 BridgeTracer API） 当前活跃： - 带有协议分类的桥接跳转 - Lightning 通道开启/关闭标记（追踪不继续进入 Lightning） - Liquid 挂入/撤出标记（追踪不继续进入 Liquid） - 当两个资产腿均存在于原始事件存储时的 EVM DEX / 聚合器 `swap_event` 节点 - 已注册协议的 Solana DEX `swap_event` 节点，以及未注册程序的通用回退 - 通过 Anchor 鉴别器 + EVM/Tron 地址启发式进行 Solana 桥接指令解码 - 在扩展遇到空边界时按需地址摄取 - 仍不完整的上下文下的 DEX / 聚合器交互回退到通用 `service` 节点 后端验证： ``` uv run pytest tests/test_trace_compiler -q ``` 前端验证： ``` cd frontend/app npm ci npm run lint npm run build ``` 仓库验证助手： ``` python scripts/quality/boundary_audit.py python scripts/quality/release_provenance_audit.py python scripts/quality/public_readiness_audit.py python scripts/quality/live_abuse_probe.py --username --password python scripts/dev/load_perf_fixture_dataset.py python scripts/quality/live_perf_probe.py --username --password ``` `load_perf_fixture_dataset.py` 会同时播种一个密集本地枢纽和一个桥接/跨链切面，以便性能探针可以测试桥接跳转渲染与状态轮询，而不仅仅是同链地址扩展。 ## 支持 如有使用问题、错误报告或功能请求，请在[GitHub 问题](https://github.com/storagebirddrop/jackdawsentry-graph/issues)中打开。 如需维护者联系或私人协调，请使用 `jackdawsentry.support@dawgus.com`。 安全问题请勿公开提问，请遵循 [SECURITY.md](SECURITY.md)。 本支持范围仅涵盖独立的图产品。私有 `jackdawsentry` 平台与合规流程不在本范围内。 更多细节请参见 [SUPPORT.md](SUPPORT.md)。 ## 品牌标识 规范的品牌源文件与生成的 favicon/logo 套件位于 `assets/branding/jackdaw-sentry/`。 要重新生成公共 logo、应用图标与社交预览资源： ``` python scripts/branding/generate_brand_assets.py ``` 请参见 [assets/branding/jackdaw-sentry/README.md](assets/branding/jackdaw-sentry/README.md) 获取资源清单与使用说明。 ## 许可证 MIT。参见 [LICENSE](LICENSE)。 ## 安全 在报告漏洞，请参见 [SECURITY.md](SECURITY.md)。 ## 与私有仓库的关系 私有仓库 `jackdawsentry` 可能会暂时嵌入或服务于本图，而在此期间边界正在收紧。这不会改变所有权： - 图产品演进属于本仓库； - 私有平台合规与企业流程属于那里； - 图到私有平台的依赖应逐步迁移出去

标签：DEX, EVM, SEO: 区块链取证工具, SEO: 开源区块链工具, SEO: 自托管区块链图, SEO: 资金追踪, SEO: 跨链追踪, UTXO, 二进制发布, 会话图, 免费RPC, 区块链取证, 区块链浏览器, 区块链追踪, 去中心化, 反诈骗, 可视化图, 可访问性, 合规扫描, 图探索, 开源工具, 性能优化, 搜索引擎查询, 数据隐私, 智能合约分析, 桥接合约, 检测绕过, 比特币追踪, 独立调查, 自托管, 节点部署, 请求拦截, 调查工具, 账户模型, 资金追踪, 跨链追踪, 逆向工具, 链上分析