Leokings/safeexit-ai

# SAFEEXIT AI 当前的基础库包含 TypeScript monorepo、共享的 domain schema、 经验证的链配置以及确定性的标准 token 扫描器。它 不会签名或提交交易，也不会与 OKX 服务集成。 ## 确定性扫描 扫描器会锁定（pin）一个区块，并仅从 EVM 读取调用或 显式的测试 fixtures 中获取值。ERC-20 合约、ERC-721/ERC-1155 token ID、spenders 和 NFT operators 必须在扫描 manifest 中提供。空结果仅 表示未找到所请求 manifest 对应的状态；这并不意味着 钱包没有其他资产或授权。 扫描器状态具有不同的含义： - `DETECTED`：读取到了正余额、所有权记录或有效授权。 - `SUPPORTED`：请求的确定性标准读取已完成，包括 有效的零值/错误结果。 - `UNSUPPORTED`：未启用经过验证的实现，当前包括 Permit2 授权扫描。 - `UNKNOWN`：配置的读取失败或无法确定状态。它永远不会 被转换为零余额。 配置的链包括 X Layer 主网（主要）、X Layer 测试网和本地 Anvil。X Layer 的值取自 [官方网络文档](https://web3.okx.com/onchainos/dev-docs/xlayer/developer/build-on-xlayer/network-information)。 ## 确定性规划 救援规划器将经过验证的 `WalletScan` 转换为按依赖关系排序的 `RescuePlan`。标准资产生成类型化的转账，相关的授权撤销 依赖于这些转账，经过验证的 adapter 输出依赖于其 领取/提现操作，而原生余额救援排在最后。原生 金额使用 `MAX_MINUS_GAS_RESERVE`；后续的模拟阶段必须在 执行前解析出实际金额。 仅当 Adapter 候选符合以下方面由代码拥有的信任记录时，它们才会被接受： Adapter ID、版本、链、合约、操作类型、自定义操作和 输出合约。规划器不接受通用的目标/calldata 操作，并且 其严格的输入会拒绝外部提供的可执行列表。 计划会被深度冻结，并带有一个确定性的完整性哈希。该哈希可以 检测规划与模拟之间的更改，但它不是钱包 签名或用户授权。 ## 本地模拟 本地/测试模拟提供程序对支持的标准操作进行编码，运行一个 区块锁定的调用，并在不提交交易的情况下估算 gas。它 会捕获成功、提供程序失败、revert 消息、gas 估算和基本的 类型化转账效果。转账效果是在成功调用后推断出来的， 并且明确不表示为基于完整 trace 的状态差异。 原生救援模拟会为原生转账和之前 成功模拟的操作预留 gas。失败、revert、不受支持和 受依赖关系阻止的操作会被计划模拟编排器排除在 `executableActions` 之外。 生产环境模拟器仅由 `OfficialDocsRequiredSimulationProvider` 表示；它没有任何 endpoint 或 虚构的 API。Adapter 操作需要单独经过审查的本地模拟解析器。 ## 命令 ``` npm install npm run typecheck npm test npm run build ``` 该工作区在 `apps/*` 和 `packages/*` 下使用 npm workspaces。 ## 托管服务准备 生产模式将经过验证的演示作为明确标记的只读 重放提供服务。本地固定执行器永远不会在托管模式下暴露。一个 基于 Bearer 认证、与提供程序无关的 agent 生命周期可在 `/api/agent/jobs` 下使用；它支持创建、分析、规划、模拟、监控和 状态操作，但无法签名或广播交易。 部署变量、数据库迁移步骤、API 冒烟测试和 需要官方文档的 OKX 交接记录在 [`DEPLOYMENT.md`](DEPLOYMENT.md) 中。 ## 黑客松演示 三分钟的演练仅使用开发者创建的合约和公开的 Anvil 账户。它演示了检测、规划、快照模拟、 解码审查、固定的本地签名、执行进度和最终状态 验证。 ### 一次性准备 前置条件为 Node.js 24、`npm install` 和 Foundry。脚本还 会检测 `.tools/foundry` 中的工作区本地 Foundry 二进制文件。 ``` npm run demo:prepare npm run dev ``` `demo:prepare` 会在 `127.0.0.1:8545` 上启动一个受管的隐藏 Anvil 进程，运行 Solidity 测试，部署固定的合约，为事件填充数据，在 Anvil 快照上执行 完整的救援，记录真实的 gas 收据，验证 最终效果，并恢复到原始的风险状态。打开 `http://localhost:3000/demo`，或使用 Next.js 打印的备用端口。 ### 三分钟故事 1. **0:00 - 事件扫描：** 显示 `CRITICAL INCIDENT`、100 SRT、Demo NFT #1、 50 SRT 可领取奖励和 25 SRT 固定攻击者额度。 2. **0:30 - AI 分析：** 展示每一条陈述都引用了结构化证据， 并且 AI 无法编辑操作列表。 3. **0:55 - 救援计划：** 审查领取、ERC-20 转账、NFT 转账，然后 是具有依赖关系的授权撤销。 4. **1:20 - 模拟：** 显示四个真实的快照收据、测量的 gas、 最终状态检查、被阻止的扫描和成功的快照恢复。 5. **1:50 - 审查并签名：** 确认来源、目的地、目标合约 和授权声明。选择 **Execute fixed Anvil rescue**。 6. **2:15 - 执行：** 观察四笔已确认的交易，然后呈现 最终事件报告，显示目的地有 150 SRT 和 NFT #1、 零可领取奖励、零额度和来源处零 SRT。 执行 API 在生产环境和非本地主机上被禁用。它 只能生成 `scripts/demo/run-rescue.ps1`，该脚本拒绝除 `31337` 之外的链，并使用固定的公共 Anvil 账户、合约地址、接收者 和操作签名。它不接受来自浏览器的任何 RPC URL、钱包、密钥、calldata 或目标。 ### 演示命令 ``` npm run demo:prepare # restart, reseed, and resimulate the managed fixture npm run demo:seed # seed a separately started fresh Anvil chain npm run demo:rescue # terminal fallback for the same fixed rescue npm run demo:stop # stop only the managed SAFEEXIT Anvil process npm run contracts:test ``` `demo:attacker` 是一个可选的失败路径演示，只能针对 固定的开发者钱包和接收池。它会使填充好的演练失效，因此 之后需运行 `npm run demo:prepare`。 `scripts/demo/common.ps1` 中的助记词和私钥是 Anvil 的公开 开发 fixtures。切勿为其充值或重复使用。 ### 限制 - 恢复是尽力而为的。EVM 链无法区分合法所有者 与持有相同私钥的其他方。 - 可执行的浏览器流程是仅限 localhost 的黑客松 fixture，而不是 生产环境钱包签名或私有中继实现。 - Permit2 发现、任意协议头寸、生产环境模拟、 私有提交、paymasters 和特定于 OKX 的执行未连接。 - 快照成功并不保证生产环境的执行。Gas、排序、 链状态、协议行为和攻击者行为都可能发生变化。 - `/` 和非演示的 `/rescue/[id]` 仍为审查草稿，绝不声称会扫描、 签名或广播生产环境交易。 ## 第 7 阶段 接地解释层 `@safeexit/ai` 仅接受经过验证的 `Incident`、`WalletScan`、`RescuePlan`、 `SimulationResult` 和 rescue-status 快照。它精确暴露了六个内部 工具：`scan_wallet`、`scan_approvals`、`get_rescue_plan`、`simulate_plan`、 `explain_action` 和 `get_rescue_status`。 模型提供程序只能返回事件快照中 已存在的 intent 和 ID。它们无法编造事实、交易目标、calldata、 接收者、链 ID 或执行请求。显示文本由 接地渲染器生成，并引用所使用的源记录。 未配置任何外部模型提供程序。因此，演示聊天将其自身标识为 确定性后备，并在没有凭证的情况下保持完全可用。 ## 第 8 阶段 agent-service 准备 `@safeexit/agent-service` 添加了与提供程序无关的事件作业生命周期和 `createIncident`、`analyseIncident`、`generatePlan`、`simulatePlan`、 `getDashboardUrl` 和 `monitorRescue` 方法。Scanner、planner、simulator、dashboard 和 monitor 行为是注入的端口。没有执行或钱包端口。 该 package 还包含版本化的概念性 A2A 请求/响应 schema。 它们是 SAFEEXIT 合约，并非声称的 OKX 线上格式。ASP 注册、 escrow、Agentic Wallet、marketplace 和服务发现都明确为 `OFFICIAL_DOCS_REQUIRED` 且未实现。有关 状态转换图和官方参考，请参阅 [`packages/agent-service/README.md`](packages/agent-service/README.md)。 ## 第 9 阶段 持久化与强化 `@safeexit/persistence` 使用 Prisma 和 PostgreSQL 来处理 incidents、scans、 assets、approvals、plans、actions、simulations、execution attempts 和 agent jobs。Agent 生命周期转换被规范化为独立的记录。 该 schema 有意不包含 private-key、seed-phrase、wallet-credential、 signature、calldata 或 raw-transaction 列。 将 `.env.example` 中的仅服务器端值复制到本地 `.env` 中，然后运行： ``` npm run db:validate npm run db:generate npx prisma migrate deploy ``` `POST /api/incidents` 是第一个持久化的 API 边界。它需要 所有权确认，仅接受严格的 JSON，强制执行 body 限制和 每进程速率限制，并在未配置数据库时返回 `503 PERSISTENCE_NOT_CONFIGURED`。它永远不会回退到虚假的持久化。具有 多个实例的生产环境部署应在部署边缘使用受信任的共享速率限制 adapter 替换内存限制器。 Web 应用应用了 CSP、点击劫持保护、MIME 嗅探保护、 referrer policy、permissions policy 和生产环境 HSTS。安全日志 会脱敏处理钱包密钥、凭证、签名、交易 payload 和 包含凭证的 PostgreSQL URL。

标签：EVM钱包, TypeScript, Web3, 区块链, 安全插件, 库, 应急响应, 智能合约, 测试用例, 自动化攻击