sukrutkrdg/warden402.xyz

# Warden — `warden402.xyz` **在 Base 上进行交易的 agents 的执行前安全与信任层。** 给 Warden 提供一个 token、一个待处理的 transaction 或一个地址 → 获得一个单一的决策： **`block` · `review` · `clear`**，附带原因、风险评分和通俗易懂的摘要。 Warden 使用 [x402 Bazaar](https://402.com.tr) 作为其智能后端，并在此基础上构建 **判断**、**可证明的过往记录**以及（下一步）**firewall**。 ## 为什么 x402 基础设施的发展领先于需求；缺失的一层是**信任**。市场 垂直领域已经很拥挤（Coinbase Bazaar + 数十个克隆版），但*执行前安全*领域 尚属空白。Warden 占据了该垂直领域。 ## 包含内容 | 路径 | 内容 | |------|------| | `web/` | **网站** (warden402.xyz) — 落地页 + 实时演示 + 过往记录。**进程内**运行 guard，因此可以作为单个 Vercel 项目部署。 | | `src/` | 独立的 **Hono Guard API**（逻辑相同） — 用于 agents/SDK/MCP 和持久化账本主机。 | | `sdk/` | `@warden402/sdk` — 客户端 + `enforce`/`assertSafe` 网关 + LangChain 工具。 | | `mcp/` | `warden402-mcp` — 暴露 `guard_token` / `guard_tx` / `guard_address` 的 stdio MCP 服务器。 | | `scripts/` | `smoke.ts`（离线决策测试），`probe.ts`（校准），`recheck.ts`（结果复查工具）。 | ## 决策契约（不可变主干） 每个 endpoint 都会返回一个 `Verdict` (`src/schema/verdict.ts`)。原则： 1. **LLM 绝不触碰裁决。** `decision` 和 `riskScore` 来自确定性 规则；LLM 只负责编写 `summary`。可审计。 2. **安全失效。** 如果无法获取 Bazaar 信号，它将变为 `unknown` → `degraded:true` → 裁决最多是 `review`，绝不会出现错误的 `clear`。 3. **每个裁决都会被记录快照**（`verdictId` + 信号证据）→ 构成过往记录护城河。 ### 决策规则 - 硬性规则：`honeypot` 或 `sanctions` 失败 → **block**（无论得分多少）。 - 加权平均风险 ≥ 70 → **block**；降级 → **review**。 - 任何单一的 `fail`（例如流动性枯竭）都会将决策底线设为 **review**（不能被 平均值稀释）。2 个或以上的 `warn` → **review**。否则为 **clear**。 ## Endpoints | Endpoint | 检查内容 | |----------|----------------| | `GET /guard/token?address=` | honeypot、税费、流动性、持有人集中度、OFAC | | `POST /guard/tx` `{from,to,calldata}` | 解码 calldata（unlimited approve / setApprovalForAll）、针对交易对手的 sanctions + 合约风险 | | `GET /guard/address?address=` | sanctions、合约风险、存在时间/活跃度 | | `GET /track-record` | 公开信任统计数据（决策分布、命中率、抓住/遗漏的 rugs） | （网站通过 `/api/guard` 暴露相同内容。） ## 本地运行 ``` # 单项目站点（推荐）— 在进程内运行 guard cd web && npm install cp .env.example .env.local # set BAZAAR_INTERNAL_SECRET npm run dev # http://localhost:3000 # 或者独立的 Hono API npm install cp .env.example .env # set BAZAAR_INTERNAL_SECRET npm run smoke # offline decision tests npm run dev # http://localhost:8787 ``` ## 生产拓扑 - **`web/` 是生产环境的 API + 网站。** 作为单个 Vercel 项目部署 （Root Directory = `web`）。它**进程内**运行 guard/firewall，因此 agents 实际调用的 endpoints（`/api/guard`、`/api/firewall`）都在这里上线。 热路径对 **edge 友好**：KV 存储（无 `fs`）+ 基于 IP 的速率限制。 当设置了 `KV_REST_API_URL` / `KV_REST_API_TOKEN` 时，会开启持久化。 - **`src/` (Hono API) 是一个可选的 Node 主机** — 适用于需要 持久化磁盘账本或 x402 支付层的团队。非必需；默认不部署。 `src/` 模块是规范逻辑；**偏移防护测试** （`tests/drift.test.ts`）可证明网站副本保持完全一致。 - **偏移（drift）无法被静默发布：** 如果两者出现分歧，`npm test` 将会失败。 ## 部署 参见 **[DEPLOY.md](./DEPLOY.md)**。TL;DR：新建 Vercel 项目，**Root Directory = `web`**， 设置 `BAZAAR_INTERNAL_SECRET`（+ 可选的 `KV_REST_API_URL`/`KV_REST_API_TOKEN` 用于 持久化过往记录），部署。完成。 ## Bazaar 内部认证 Warden 调用 Bazaar 时**无需支付** x402（这样我们自己的产品就不会给自己计费），通过使用 `X-Warden-Internal` header 实现。Bazaar 必须具有匹配的 `WARDEN_INTERNAL_SECRET`。在 设置之前，所有信号都将返回 `unknown`，并且裁决将安全地保持在 `review` 状态。 ## 路线图 1. ✅ Guard MVP (`/guard/token`) + 裁决契约 2. ✅ `/guard/tx`（签名前） + `/guard/address` + 过往记录 + 复查工具 3. ✅ SDK / MCP / 网站 4. ⏳ x402 支付层（免费层 → 402）+ MCP Registry / Agentic.Market 上架 5. ⏳ **Firewall / 策略网关** — 位于 agent 的 x402 + 链上调用的前端： 支出限额、基于信任分数的允许/拒绝、异常 + 注入抽干（injection-drain）检测、审计日志。 B2B，Cloudflare Worker edge。北极星。

标签：Hono框架, MCP协议, TypeScript, Web3安全, 交易风险控制, 人工智能代理, 安全插件, 智能合约审计, 自动化攻击