内容
# <img src="logo.jpg" width="28" height="28" style="vertical-align:middle;margin-right:6px">守望者
**监控链条。 在下一个区块之前采取行动。**
🌐 **[守望者官网](https://wardenofficial.com)**
为罗宾汉链提供实时链条监控。 用简单的语言描述您正在观察的内容； 守望者将每个匹配结果推送到您的 webhook、AI 代理或仪表板 - 签名、上链且在 1 秒内生效。 无需轮询，无需索引，无需胶水代码。
---
## 工作原理
```
┌──────────────┐ WS (eth_subscribe) ┌──────────────┐ POST (HMAC) ┌─────────────┐
│ RHC RPC │─────────────────────────▶│ 守望者 │───────────────▶│ 您的 │
│ (日志) │ │ (断言条件) │ │ webhook │
└──────────────┘ └──────┬───────┘ └─────────────┘
│
│ recordDelivery (上链)
▼
┌──────────────┐
│ 流托管 │
│ (Solidity) │
└──────────────┘
```
1. **描述。** 输入 "鲸鱼超过 100k TSLA" 或编写 JSON 断言条件。 在链上锁定 ETH 到托管账户。
2. **匹配。** 守望者通过 WebSocket 实时监控 RHC 日志。 在毫秒级别评估您的断言条件。
3. **交付。** 匹配后 → 向您的 webhook 发送 POST 请求（HMAC 签名、幂等键、重试 3 次）。 在链上写入接收确认。
---
## 快速入门
### 命令行界面
```bash
# 用简单的语言描述事件
warden ai "鲸鱼超过 100k TSLA"
# 订阅
warden subscribe --ai "鲸鱼超过 100k TSLA" \
--webhook https://webhook.site/your-id \
--amount 0.05
# 实时监控
warden watch --ai "swap 超过 50k" \
--webhook https://webhook.site/your-id \
--amount 0.1
# 检查系统健康状况
warden doctor
# 发送测试 webhook（零成本）
warden sandbox --webhook https://webhook.site/your-id
# 重放最近的交付记录
warden replay-last
```
### 工作空间（可视化构建工具）
```bash
cd workspace && node server.mjs
# 打开 http://localhost:4000
```
### Docker（一键部署）
```bash
cp .env.example .env # 填写 RPC URL + 密钥
docker compose -f docker/docker-compose.yml up --build
```
| 服务 | 端口 | 描述 |
|---------|------|-------------|
| **工作空间** | `4000` | 可视化构建工具、 dry-run、实时 feed、点击解释 |
| **Prometheus** | `9091` | 指标收集 |
| **Grafana** | `3000` | 预置仪表板（管理员/管理员） |
| **指标** | `9090` | 匹配器指标（Prometheus 抓取目标） |
---
## 断言条件语言
```json
{
"and": [
{ "field": "eventName", "op": "eq", "value": "转账" },
{ "field": "value", "op": "gte", "value": "1000000000000000000000" }
]
}
```
### 操作符
`eq` `neq` `gte` `lte` `gt` `lt` `in` `not_in` `contains` `starts_with` `ends_with` `regex`
嵌套 `and`/`or` 最多 6 级，32 个条件最多。 正则表达式模式经过安全检查，以防止灾难性回溯。
### 简易语言解析器
输入自然语言 - 自动转换为 JSON：
| 输入 | 输出 |
|-------|--------|
| `鲸鱼超过 100k TSLA` | 转账 ≥ 100,000 TSLA |
| `10 AAPL 以下转账` | 转账 ≤ 10 AAPL |
| `超过 50000 的 swap` | Swap 事件 ≥ 50,000 |
| `从 0xPool 清算` | 从地址清算 |
| `至 0xABC 超过 5000` | 至地址 ≥ 5,000 |
识别的 ticker：TSLA, AAPL, NVDA, AMZN, MSFT, GOOGL, META, MSTR, SPY, QCOM.
---
## 架构
```
warden/
├── matcher/ 断言条件引擎、RHC 日志监听器、webhook 交付、指标
├── cli/ warden subscribe | list | cancel | tail | watch | replay | sandbox | doctor | ai
├── mcp/ MCP 服务器（只读托管 + 本地 stdio 签名）
├── workspace/ 可视化构建工具、简易语言解析器、dry-run、实时 feed、点击解释
├── dashboard/ 只读状态页面（Express + SQLite）
├── docker/ Docker Compose、Prometheus、Grafana 仪表板
├── foundry/ StreamEscrow.sol + 测试（Foundry）
└── docs/ 示例断言条件
```
### MCP（AI 代理集成）
```bash
# 只读托管（无需密钥）：
WARDEN_MCP_URL=https://wardenofficial.com/mcp
# 本地 stdio（订阅 + 取消）：
claude mcp add --transport stdio warden -- node mcp/dist/index.js
```
工具：`recent_deliveries`, `warden_sandbox_dispatch`, `subscribe_to_events`, `list_subscriptions`, `cancel_subscription`.
---
## 监控合约
默认：TSLA 转账事件。
```bash
# 单个代币
WATCH_TOKEN_ADDRESS=0x322F0929c4625eD5bAd873c95208D54E1c003b2d
# 多个自定义合约（专业版）
WATCH_CONTRACTS=0xAAA:Transfer,0xBBB:Swap,0xCCC:Liquidation
# ticker 简写
WATCH_CONTRACTS=TSLA:Transfer,AAPL:Transfer
```
---
## 示例
参见 `docs/examples/`：
- `whale.json` — 大型代币转账（≥ 1,000 代币）
- `treasury-outflow.json` — 从 treasury 流出大量资金
- `compliance-watch.json` — KYC/合规地址活动
- `liquidation-guard.json` — 借贷池提现
- `pool-deposit-rebalance.json` — 触发重新平衡的池存款
---
## 当前版本（v0.2）与未来规划
**当前版本：**
- 12 个断言条件运算符 + 正则表达式安全
- 简易语言解析器（基于规则，无 LLM）
- 带有实时 dry-run + 点击解释的 web 工作空间
- webhook 交付（HMAC、幂等、重试 ×3）
- 链上托管 + 交付回执（Solidity）
- MCP 服务器（5 个工具，任意 MCP 客户端）
- 命令行界面（9 个命令）
- Docker Compose + Prometheus + Grafana
- 可配置的监控目标（ERC-20 + 任意事件）
**未来规划：**
- 持久的至少一次交付队列
- 多个匹配器中继器 / 多签
- SSE 作为 webhook 替代方案
- 原生钱包订阅
- 历史事件重放
---
## 安全
- `MATCHER_PRIVATE_KEY` — 仅需用于支付 gas。 永不超出该范围。
- `USER_PRIVATE_KEY` — 从不在托管的 MCP 中设置。 仅限命令行界面/本地使用。
- 合约存储 `keccak256(断言条件)` + `keccak256(webhook)` — 链上永远不会存储明文。
- 每个 webhook POST 请求都使用 HMAC-SHA256 签名。 使用 `delivery.ts` 中的参考验证器进行验证。
---
MIT 许可证。 为罗宾汉链生态系统而构建。
