alexbelij/mantle-sentinel
GitHub: alexbelij/mantle-sentinel
Mantle Sentinel 是一款基于超维度计算（HDC）的免训练链上行为异常检测器，专为 Mantle DeFi 合约提供零误报的实时攻击预警与可解释性分析。
Stars: 2 | Forks: 0
# Mantle Sentinel — HDC 行为 DNA Agent
[](https://github.com/alexbelij/mantle-sentinel/actions/workflows/pytest.yml)
**专为 [Mantle AI 黑客松 — 图灵测试第二阶段](https://dorahacks.io/hackathon/mantle-ai/detail) 构建，赛道 02：AI Alpha 与数据**
[实时演示](https://mntsentinel.xyz) · [仪表盘](https://mntsentinel.xyz/dashboard/) · [Mantlescan 上的合约](https://mantlescan.xyz/address/0x0899E1507CFfefF8620455721F5bd528Bb072187) · [博客](https://alexbelij.medium.com/how-we-detect-smart-contract-exploits-without-training-data-using-hyperdimensional-computing-on-e94d5d83e6b8) · [X 帖子](https://x.com/alexbelij/status/2066546074576109803)
## 结果
| 指标 | Sentinel | 签名基线 |
| ----------------------------- | ---------------------------- | ------------------ |
| 正常/攻击分离比 | **4.3×** (USDC.e 真实数据) | ~1.2× |
| 检测延迟 | ≤2 个窗口 (≤100 笔交易) | 4+ 个窗口 |
| 误报率 | **0** 次 (USDC.e) | — |
*数据来源：3,993 笔真实的 Mantle USDC.e 交易。完整方法论：
[`docs/BENCHMARK_PROTOCOL.md`](docs/BENCHMARK_PROTOCOL.md).*
### 注入场景
| 场景 | 签名 | 已检测 | 延迟 |
| ----------------- | ------------------------------- | -------- | --------- |
| S1 选择器洪泛 | 新选择器占主导 | ✅ | 2 个窗口 |
| S3 Gas 偏移 | Gas 高出基线 5 倍 | ✅ | 3 个窗口 |
| S5 时序突发 | 交易间隔接近零 | ✅ | 2 个窗口 |
| S7 Payload 突变 | 随机化的 calldata | ✅ | 4 个窗口 |
## 截图
| 首页 | 仪表盘 | 移动端 |
|---------|-----------|--------|
|  |  |  |
### 自攻击检测
## 实时扫描 — Mantle 热门 DeFi 合约
一条命令，零配置。`sentinel scan` 会获取链上历史记录并运行完整的 HDC pipeline：
```
python -m sentinel scan 0x09bc4e0d864854c6afb6eb9a9cdf58ac190d0df9
```
| 合约 | 协议 | 健康度 | 漂移度 (中位数) | 漂移度 (p99) | 选择器 | 警报 |
|----------|----------|--------|----------------|-------------|-----------|--------|
| 0x09bc4e… | USDC.e | 83/100 | 0.222 | 0.730 | 4 | 4 |
| 0x78c1b0… | WMNT | 74/100 | 0.282 | 0.778 | 10 | 6 |
| 0x201eba… | USDT | 70/100 | 0.153 | 0.656 | 2 | 12 |
| 0xcda86a… | mETH | 68/100 | 0.274 | 0.978 | 2 | 4 |
| 0xcfA5aE… | Lendle Pool | 81/100 | 0.317 | 0.706 | 5 | 4 |
完整报告：[`bench/reports/`](bench/reports/) · 摘要：[`bench/reports/SUMMARY.md`](bench/reports/SUMMARY.md)
## 问题所在
基于签名的工具无法发现新型攻击。纯粹的 LLM 监控器既缓慢又昂贵。
Sentinel 检测的是**变化本身**——确定性的、针对单笔交易的微秒级更新——它使用 10,000 维的超维度 (HDC) 行为签名，*然后*才要求 Z.ai 用通俗易懂的英语解释已确认的警报。
该模型**绝不**处于检测循环中。
## 核心功能
- **免训练异常检测** — 10,000 维 HDC 行为指纹，零 GPU，零重训练
- **链上证明** — 每个警报都锚定在 Mantle 主网上的 Sentinel 注册表合约中
- **Telegram 警报** — 通过 [@MantleSentinelBot](https://t.me/MantleSentinelBot) 进行实时通知
- **Z.ai 解释** — 已确认的警报会收到来自 Z.ai GLM 的通俗英文简报
- **实时仪表盘** — 在 [mntsentinel.xyz/dashboard](https://mntsentinel.xyz/dashboard/) 查看实时漂移度仪表和警报表
- **Supabase 数据 pipeline** — 自动化扫描 → Supabase → 仪表盘上的历史漂移度图表
## 工作原理
```
[Mantle RPC]
│
T0 Entropy pre-filter (calldata selector distribution)
│
T1 HDC Encoder — 10,000-dim bipolar hypervector per window
│
T2 Drift = max(Hamming distance, timing deviation)
│
T3 Detector — static threshold or BOCPD regime-change
│
T4 Feature attribution (ablation: recompute bundle without feature f)
│
T5 Z.ai natural-language explanation (restates Tier-4 findings only)
│
[Telegram alert + on-chain logAlert() + Dashboard]
```
归因计算发生在调用 Z.ai **之前**（纯代数计算）——无论是否有 LLM，结构化的解释都会存在。
## 对比
| | Sentinel | Forta | Chainalysis | LLM 监控器 |
|-----------------|----------------|---------------|----------------|---------------|
| **训练** | 无 | 每个机器人 | 签名 | Fine-tune |
| **检测** | 代数计算 | 规则 / ML | 模式数据库 | Prompt |
| **速度** | <1 µs/tx | 秒 | 批处理 | 1–5 s/tx |
| **GPU** | 否 | 可选 | 否 | 必需 |
| **新型攻击** | ✅ | ❌ | ❌ | 部分 |
## 快速开始
```
git clone https://github.com/alexbelij/mantle-sentinel
cd mantle-sentinel
pip install -r requirements.txt
# 自攻击演示 — 开箱即用，零 config：
python bench/self_attack.py --dry-run
# 扫描任意 Mantle contract（需要 ETHERSCAN_KEY）：
python -m sentinel scan 0x09bc4e0d864854c6afb6eb9a9cdf58ac190d0df9
```
在 `.env` 中设置 `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID`，即可通过 [@MantleSentinelBot](https://t.me/MantleSentinelBot) 启用 Telegram 警报。
## CI/CD 集成
Sentinel 在你的 pipeline 中充当健康检查门控：
**GitHub Actions** — 通过 `--min-health` 阈值进行每周定时的扫描。
参见 [`.github/workflows/scan-cron.yml`](.github/workflows/scan-cron.yml)。
**Pre-commit** — 如果合约健康度低于阈值，则阻止推送。
```
pip install pre-commit && pre-commit install
```
**任何 CI** — 退出代码 0 = 健康，1 = 低于阈值：
```
python -m sentinel scan --min-health 60
```
## Python SDK
```
from sentinel import SentinelClient
client = SentinelClient()
report = client.scan("0x09bc4e0d864854c6afb6eb9a9cdf58ac190d0df9")
print(f"Health: {report.health_score}/100")
print(f"Alerts: {report.alert_count}")
print(f"Healthy: {report.is_healthy}")
# 扫描多个 contracts
reports = client.scan_multiple([
"0x09bc4e0d864854c6afb6eb9a9cdf58ac190d0df9", # USDC.e
"0x78c1b0c915c4faa5fffa6cabf0219da63d7f4cb8", # WMNT
])
for r in reports:
print(f"{r.address[:10]}… → {r.health_score}/100")
```
要重放真实的 USDC.e 快照（已被 gitignored —— 请先获取它）：
```
cp .env.example .env # add ETHERSCAN_KEY + TELEGRAM_*
python bench/capture_etherscan.py # downloads raw.jsonl (~4k txs)
python -m sentinel replay \
--snapshot bench/data/0x09bc4e0d864854c6afb6eb9a9cdf58ac190d0df9/raw.jsonl \
--inject S1
```
实时链上模式（预热、注入异常、在 Mantle 上锚定警报）：
```
pip install web3 eth-account
export MANTLE_PRIVATE_KEY=0x... # see .env.example
python bench/self_attack.py \
--victim 0x1f88f063C00893642Ca4a74FE4d25Bf20c468E64 \
--rpc https://rpc.sepolia.mantle.xyz
```
## 合约 — `SentinelAlertRegistry` v2
不可变的、所有者门控的链上注册表，用于记录行为漂移警报。
源码：[`contracts/SentinelAlertRegistry.sol`](contracts/SentinelAlertRegistry.sol).
| 网络 | 链 ID | 地址 |
| ------------------ | -------- | -------------------------------------------- |
| **Mantle 主网** | 5000 | `0x0899E1507CFfefF8620455721F5bd528Bb072187` |
| Mantle 测试网 | 5003 | `0x2543Cc701632b105eE3DB75345140a7357664389` |
浏览器：[mantlescan.xyz/address/0x0899…72187](https://mantlescan.xyz/address/0x0899E1507CFfefF8620455721F5bd528Bb072187)
`driftScore` 存储时扩大了 10,000 倍（`0.87` → `8700`）。事件带有存储中的 `alertIndex`，因此任何链下消费者都可以重构时间线，而无需扫描数组。读取操作（`getAlertCount`, `getAlert`, `getLatestAlerts`）的时间复杂度为 O(1) 或具有受限的 Gas 消耗。
## Z.ai 集成
[`sentinel/explain_zai.py`](sentinel/explain_zai.py) 会在每个确认的警报上（在第 4 层归因**之后**）调用 Z.ai（兼容 OpenAI 的 `chat/completions`）。
Z.ai 只是重述结构化的发现——它无法创建或抑制警报。Prompt 模板与 schema：[`docs/zai_prompt.md`](docs/zai_prompt.md)。
- Endpoint：`https://api.z.ai/api/paas/v4` · 模型 `glm-4.5-flash`（免费层级）
- 无 `ZAI_API_KEY` → 确定性的试运行解释（CI 绝不会请求该 API）
- 警报 Payload schema：[`contracts/alert.schema.json`](contracts/alert.schema.json)
## 🤖 Telegram 机器人
通过 [@MantleSentinelBot](https://t.me/MantleSentinelBot) 进行交互式监控：
| 命令 | 描述 |
|---------|-------------|
| `/health` | 所有受监控合约的健康度评分 |
| `/scan ` | 特定合约的最新扫描结果 |
| `/status` | 监控正常运行时间和统计信息 |
| `/help` | 命令列表 |
该机器人从 Supabase 数据库中读取数据，该数据库通过 GitHub Actions（[`.github/workflows/scan-cron.yml`](.github/workflows/scan-cron.yml)）每 4 小时更新一次。
**Webhook 设置**（一次性）：
```
curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
-d "url=https://mntsentinel.xyz/api/telegram"
```
## 测试
```
python -m pytest tests/ -q # 137 passed
forge test # 6 passed (contracts/SentinelAlertRegistry.sol)
```
CI：GitHub Actions 会在每次推送 / PR 时运行 Python 测试套件：
[`.github/workflows/pytest.yml`](.github/workflows/pytest.yml)。
合约测试通过 Foundry 在本地运行（`forge test`）。
## 仓库布局
```
sentinel/ Python package — Tiers T0–T5 pipeline
prefilter.py T0 entropy pre-filter
hdc.py T1 hyperdimensional encoder
drift.py T2 Hamming + timing drift
detector.py T3 static / BOCPD detector
bocpd.py Bayesian online change-point detector
interpreter.py T4 feature-ablation attribution
explain_zai.py T5 Z.ai explainer + contract profiler (dry-run safe)
scan.py one-command behavioral audit
notify_telegram.py Telegram fan-out
replay.py snapshot replay harness
contracts/ SentinelAlertRegistry.sol (v2) + VictimCounter.sol + ABI/deployments
test/ Foundry tests (forge)
tests/ pytest suite
bench/ self_attack.py demo + real snapshot data + scan reports
scripts/ scan_to_supabase.py — data pipeline for Supabase
dashboard/ static on-chain alert viewer
docs/landing/ marketing site + Telegram webhook (Vercel)
docs/landing/api/ Vercel Python serverless functions
```
**博客：** [我们如何在没有训练数据的情况下检测智能合约漏洞](https://alexbelij.medium.com/how-we-detect-smart-contract-exploits-without-training-data-using-hyperdimensional-computing-on-e94d5d83e6b8) · **视频：** [YouTube 演示](https://www.youtube.com/watch?v=s-OED4oZ8ho) · **赛道：** AI Alpha 与数据 · **黑客松：** [Mantle 图灵测试第二阶段](https://dorahacks.io/hackathon/mantle-ai/detail)
标签：Apex, DeFi, 区块链安全, 异常检测, 智能合约审计, 机器学习, 逆向工具