demola13777/watchtower

# WatchTower 为自主 AI 交易代理提供的威胁情报中间件。 WatchTower 让代理在交易前问一个问题：**这个 token 是否足够安全可以接触？** 它结合了 token 情报模块、面向代理的 API、MCP 工具、x402 风格的机器支付以及公共链上证明，以便交易代理可以在执行前拦截恶意合约。 该项目专为 OKX AI Hackathon 打造，采用了面向生产环境的架构：免费层级的数据提供者和自托管的支付验证隔离在服务边界之后，以便日后无需重写扫描引擎、SDK、MCP server 或路由逻辑即可替换它们。 ## 为什么开发它 自主交易代理发现和执行机会的速度比人类审查的速度更快。这产生了一种新的失败模式：代理可能会在操作员注意到之前与蜜罐、流动性差的 token、集中供应或可疑市场进行交互。 WatchTower 被设计为代理优先的安全层： - 代理通过 SDK、REST API 或 MCP 从其自身的 runtime 调用 WatchTower。 - WatchTower 返回机器可读的 `TRADE`、`CAUTION` 或 `ABORT` 建议。 - 深度扫描生成可作为凭证共享的公共报告。 - 扫描证明记录在 X Layer 上以供独立验证。 WatchTower 不是钱包仪表板，并且公共 Web 体验不需要连接钱包。 ## WatchTower 的与众不同之处 WatchTower 是一个威胁情报 oracle，而不是一个执行计划验证器。它不尝试签名或强制执行完整的交易策略。相反，它在决策点为自主代理提供最新的 token 风险情报。 核心产品形态包括： - 用于代理代码的 **SDK 中间件**。 - 用于桌面和本地 AI 代理的 **MCP 工具**。 - 用于直接集成的 **REST API**。 - 用于机器到机器访问的 **x402 风格支付挑战**。 - 用于透明度的 **公共扫描报告**和**链上证明**。 这使得 WatchTower 保持专注：它回答目标 token 在代理投入资金之前是否存在危险。 ## 架构 ``` flowchart LR Agent["AI Trading Agent"] --> SDK["WatchTower SDK"] Agent --> MCP["MCP Tool Call"] SDK --> API["/api/scan or /api/scan/deep"] MCP --> MCPRoute["/api/mcp"] API --> Payment["PaymentService Boundary"] MCPRoute --> Payment Payment --> Engine["Threat Engine"] Engine --> Modules["DexScreener / GoPlus / Ethplorer / Social Radar"] Engine --> DB["SQLite or Turso"] Engine --> Registry["WatchTowerRegistry on X Layer"] DB --> Reports["/report/[scanHash]"] Registry --> Verify["/verify"] ``` 关键边界： - `src/lib/payment.ts` 集中处理支付验证。 - `src/lib/scan-service.ts` 协调共享的扫描工作流。 - `src/lib/engine.ts` 包含威胁评分模块和确定性扫描 hash。 - `src/lib/chain-resolver.ts` 解析或验证扫描 `chainId`。 - `src/app/api/mcp` 将相同的扫描工作流公开为 MCP 工具。 - `packages/watchtower-sdk` 提供代理端集成。 - `contracts/src/WatchTowerRegistry.sol` 存储链感知的扫描证明。 ## 核心功能 ### 代理优先的扫描接口 - `POST /api/scan` 用于快速的 Tier 2 防火墙扫描。 - `POST /api/scan/deep` 用于 Tier 1 详细报告和证明。 - `POST /api/mcp` 用于兼容 MCP 的代理。 - `okx-watchtower-middleware` SDK 适用于 TypeScript/Node 代理。 ### 威胁情报模块 | 模块 | 当前来源 | 用途 | | --- | --- | --- | | Liquidity Intelligence | DexScreener | 流动性深度、缺失交易对、死市场、交易对存在时间、交易量 | | Contract DNA Scanner | GoPlus Security | 蜜罐、出售限制、可铸造性、所有者余额控制、税率 | | Whale Intelligence | Ethplorer | 持有者集中度和最大持有者风险 | | Social Threat Radar | 当前由 DexScreener 支持，架构已准备好支持 LunarCrush | 社交存在感、交易倾斜、波动性、类似机器人的活动指标 | ### 链感知扫描 Token 地址在 EVM 链之间并不是全局唯一的。WatchTower 在 REST、SDK 和 MCP 请求中接受 `chainId`。如果省略，它会尝试使用流动性、bytecode 和安全配置文件信号进行链解析。 默认回退： - X Layer Mainnet: `196` - X Layer Testnet 支持：`1952` ### x402 风格的支付边界 受保护的扫描路由返回 `402 Payment Required` 以及 `PAYMENT-REQUIRED` 挑战。 当前定价： - Tier 1 深度扫描：`1 USDT` - Tier 2 防火墙扫描：`0.5 USDT` 当前模式： - **开发 / 自托管 Web3 验证** - 代理将 ERC-20 USDT 转移到配置的 Treasury。 - 重试请求发送 `Authorization: L402 `。 - 验证器检查链 ID、交易成功状态、token 合约、Treasury 接收方、金额、确认深度和重放状态。 `PaymentService` 接口被特意集中化，以便生产级的 x402 facilitator 或 LSAT 风格的密码学验证器可以替换自托管验证器，而无需更改扫描引擎或路由逻辑。 ### 公共报告和证明 深度扫描生成： - 位于 `/report/[scanHash]` 的公共报告。 - 使用以下内容的确定性 hash： ``` sha256(chainId:tokenAddress:threatScore:confidence:timestamp) ``` - 来自 `WatchTowerRegistry` 的 X Layer 注册表事件。 - 通过 `/verify` 进行验证。 当前的 X Layer Testnet 注册表： - 地址：`0x035FE9151000cd4346f4A07f5878474ea6fd21b7` - Chain ID: `1952` - 部署交易：`0xc2c598922d62814f74d6060c67038be96618a5583b44c53f992a124d9c2eef9e` ## 快速开始 ### 要求 - Node.js 20+ - npm - Foundry，仅在处理合约时需要 - 配置好的 `.env.local` ### 安装 ``` npm install cd packages/watchtower-sdk && npm install && npm run build cd ../.. ``` ### 配置 ``` cp .env.example .env.local ``` 对于无需付费扫描的本地开发，应用程序可以以最小配置启动。要使付费扫描路由工作，请配置活动的支付网络： ``` NEXT_PUBLIC_NETWORK_ENV=testnet TESTNET_RPC_URL=https://testrpc.xlayer.tech TESTNET_TREASURY_ADDRESS=0x... TESTNET_USDT_ADDRESS=0x... TESTNET_PAYMENT_TOKEN_DECIMALS=6 ``` 用于注册表写入： ``` PRIVATE_KEY=0x... NEXT_PUBLIC_REGISTRY_ADDRESS=0x035FE9151000cd4346f4A07f5878474ea6fd21b7 NEXT_PUBLIC_REGISTRY_CHAIN_ID=1952 NEXT_PUBLIC_REGISTRY_RPC_URL=https://testrpc.xlayer.tech ``` 切勿提交真实的 private key。 ### 本地运行 ``` npm run dev ``` 打开： - 主页：`http://localhost:3000` - 网络仪表板：`http://localhost:3000/network` - 验证器：`http://localhost:3000/verify` - MCP 端点：`http://localhost:3000/api/mcp` ## SDK 使用 SDK 位于 `packages/watchtower-sdk` 中，命名为 `okx-watchtower-middleware`。 ``` import { WatchTowerClient, WatchTowerAbortError } from "okx-watchtower-middleware"; const wt = new WatchTowerClient({ apiUrl: "https://watchtower.xyz", agentWallet: "0xYourAgentWallet", chainId: 196, threshold: 70, paymentPrivateKey: process.env.AGENT_PAYMENT_KEY, }); try { const intel = await wt.guardTransaction("0xTokenAddress"); console.log(intel.recommendation, intel.threatScore); // Continue only if your agent's own policy accepts the result. } catch (error) { if (error instanceof WatchTowerAbortError) { console.log("Trade blocked", error.threatScore, error.reasoning); } } ``` 如果配置了 `paymentPrivateKey`，SDK 会通过发送 ERC-20 支付交易并使用结算 hash 重试，自动处理 `402` 挑战。 深度扫描： ``` const report = await wt.deepScan("0xTokenAddress", { chainId: 196 }); console.log(report.verification.scanHash); ``` ## MCP 集成 WatchTower 在以下位置公开了一个 Streamable HTTP MCP 端点： ``` http://localhost:3000/api/mcp ``` MCP 配置示例： ``` { "mcpServers": { "watchtower": { "url": "http://localhost:3000/api/mcp" } } } ``` 可用工具： - `scan_token` - `deep_scan_token` 输入： ``` { "tokenAddress": "0x...", "chainId": "196", "agentWallet": "0x..." } ``` 付费 MCP 工具调用使用与 REST 相同的支付边界。故意拒绝批量付费工具调用，以便一个支付挑战映射到一个付费扫描操作。 ## REST API 概述 ### `POST /api/scan` Tier 2 防火墙扫描。价格：`0.5 USDT`。 请求： ``` { "tokenAddress": "0x...", "chainId": "196", "agentWallet": "0x..." } ``` 响应： ``` { "success": true, "data": { "tokenAddress": "0x...", "chainId": "196", "threatScore": 42, "confidence": 0.75, "recommendation": "CAUTION", "reasoning": [], "scanHash": "..." } } ``` ### `POST /api/scan/deep` Tier 1 深度扫描。价格：`1 USDT`。 返回包含模块分解、建议、公共报告 hash 以及链上提交成功时的注册表交易 hash 的完整报告。 ### `GET /api/telemetry` 只读仪表板指标和最新扫描源。 查询参数： - `page` - `limit`，上限为 `100` ## 演示工作流 受保护的 SDK 代理： ``` node demo/protected-agent.js ``` 深度扫描 API 演示： ``` node demo/deep-scan-agent.js ``` MCP 演示： ``` node demo/mcp-agent.js ``` 支付挑战回归测试： ``` npm run test:payments ``` 设置 `PAYMENT_TEST_TX_HASH` 以验证真实的结算交易和重放拒绝。 ## 智能合约 注册表存储链感知的扫描证明。 ``` event ScanRecorded( uint256 indexed chainId, address indexed tokenAddress, string scanHash, uint256 threatScore, uint256 timestamp ); ``` 部署： ``` cd contracts forge script script/DeployWatchTowerRegistry.s.sol:DeployWatchTowerRegistry \ --rpc-url $TESTNET_RPC_URL \ --broadcast \ --slow ``` 测试： ``` cd contracts forge test ``` ## 数据库 本地开发使用位于 `watchtower.db` 的 SQLite。 生产环境应使用 Turso/libSQL： ``` TURSO_DATABASE_URL=libsql://... TURSO_AUTH_TOKEN=... npm run db:push ``` 应用程序自动选择数据库驱动程序： - 设置了 `TURSO_DATABASE_URL`：Turso/libSQL - 未设置：本地 SQLite ## 在 Vercel 上部署 公共部署所需： - `NEXT_PUBLIC_SITE_URL` - `TURSO_DATABASE_URL` - `TURSO_AUTH_TOKEN` - `PRIVATE_KEY`，仅在部署的服务器需要写入证明时需要 - 注册表变量： - `NEXT_PUBLIC_REGISTRY_ADDRESS` - `NEXT_PUBLIC_REGISTRY_CHAIN_ID` - `NEXT_PUBLIC_REGISTRY_RPC_URL` - 活动网络的支付变量： - `NEXT_PUBLIC_NETWORK_ENV` - `TESTNET_RPC_URL` 或 `MAINNET_RPC_URL` - Treasury 地址 - 接受的 token 地址 - token 小数位数 推荐的生产设置： - `PAYMENT_MIN_CONFIRMATIONS=1` 或更高 - `RECORD_FIREWALL_SCANS=false` 如果 gas 成本应限制在深度扫描中 - 所有生产链的付费 RPC 提供商 - Turso 数据库而不是本地 SQLite 该项目包括： - Next 元数据 - `robots.ts` - `sitemap.ts` - 基本安全标头 - 报告加载/错误/未找到状态 ## 验证命令 ``` npm run lint npm run build cd packages/watchtower-sdk && npm run build cd ../../contracts && forge test cd .. && npm run test:payments ``` ## 当前限制 这些是已知并特意记录的： - 支付层是自托管的 Web3 验证，尚未完全集成生产级的 x402 facilitator。 - 通过交易 hash 的公共/手动支付仍然是一条便利路径；SDK 代理可以使用 `paymentPrivateKey` 自动结算。 - 速率限制在内存中进行，并在 serverless 实例间重置。对于生产规模，请使用 Redis、Upstash 或基于数据库的限制器。 - 免费层级的情报 API 可能会进行速率限制或返回不完整的数据。当模块不可用时，引擎会降低置信度。 - Social Threat Radar 已准备好支持 LunarCrush，但当前免费层级的实现由 DexScreener 支持。 - 本地 SQLite 仅用于开发。Vercel/公共部署应使用 Turso。 - 服务器端的注册表写入器使用 `PRIVATE_KEY`；对于生产环境，请将签名移至托管托管、relayer 或基于 KMS 的密钥管理。 ## 路线图 - 生产级 x402 facilitator 或兼容 LSAT 的签名支付信封。 - 基于 Redis/Upstash 的速率限制和幂等性控制。 - 用于 DexScreener 替代方案、GoPlus、Ethplorer 和 LunarCrush 的付费提供商适配器。 - 针对手动 Web 流程的更强请求绑定支付证明。 - 专用的 SDK 包发布工作流。 - 为所有权转移和事件索引扩展 Foundry 测试。 - 用于 lint、build、SDK 构建、支付挑战测试和 Foundry 测试的 CI pipeline。 ## 项目结构 ``` watchtower/ src/app/ Next.js routes, pages, and API handlers src/app/api/scan Tier 2 firewall endpoint src/app/api/scan/deep Tier 1 deep scan endpoint src/app/api/mcp MCP Streamable HTTP endpoint src/lib/engine.ts Threat intelligence engine src/lib/payment.ts PaymentService boundary src/lib/scan-service.ts Shared scan orchestration src/lib/chain-resolver.ts Chain detection and fallback logic src/lib/db Drizzle schema and database connection packages/watchtower-sdk Agent SDK contracts/ WatchTowerRegistry and Foundry tests demo/ Agent and API demos scripts/ Regression scripts ``` ## 许可证 ISC

标签：API中间件, DeFi, MITM代理, OKX, 人工智能代理, 区块链安全, 威胁情报, 开发者工具