# VMGuardian

> VMGuardian——NeuroChain 的 AI 合约审计器——五条字节码规则、内置神经网络及其融合方式、每个验证者都会运行的部署关卡、签名证明、证书、持续监控以及链上模型注册表。

Source: https://docs.nro.world/zh/ai/vmguardian

VMGuardian 审计 WebAssembly 字节码。它在三个地方以**同一份代码**运行，因此合约在任何地方得到的分数都相同：

| 位置 | 时机 |
|------|------|
| 浏览器（WASM 模块） | 在你发送部署之前即时运行 |
| 每个验证者，在共识中 | 每一笔部署交易——即关卡 |
| 每个节点，在后台 | 持续运行，覆盖每个已部署的合约 |

## 分数如何得出

### 1. 规则（启发式）

分析器逐条指令解码代码段（单次线性扫描，因此即使是 512 KiB 的合约也能快速分析），并检查五种模式。每次命中都会增加风险；总和上限为 1.0。

| 规则 | 严重程度 | 增加 | 触发条件 |
|------|----------|------|----------|
| `reentrancy` | 严重 | 0.40 | 动态 `call_indirect` 之后紧跟存储写入 |
| `uncapped_loop` | 严重 | 0.35 | 没有条件分支可以跳出的循环 |
| `unbounded_memory` | 警告 | 0.20 | 超过 8 条 `memory.grow` 指令 |
| `unchecked_call` | 警告 | 0.15 | 结果被丢弃的调用 |
| `large_import_surface` | 信息 | 0.10 | 导入超过 20 个宿主函数 |

低于 0.5 的分数报告为 `safe`。

### 2. 神经网络

一个小型内置网络（10 个输入 → 32 → 16 → 1，897 个参数）根据十个特征为同一字节码评分：无上限循环的占比、重入模式、被丢弃的调用、`memory.grow`、导入、间接调用、存储写入、循环和算术运算的密度，以及代码大小。它在节点内部运行，不需要任何 ML 运行时。

### 3. 融合

```
if |network − rules| > 0.25:   risk = rules                 (model: "heuristic")
else:                          risk = 0.3 × network + 0.7 × rules   (model: "ml+heuristic")
```

网络的权重较小，并且在与规则严重不一致时被忽略——它主要基于合成数据以及来自某条公共 CosmWasm 链的真实安全合约训练，在获得真实漏洞利用数据之前，还不能给予更多信任。

各处显示的**安全分数**为 `100 − risk × 100`。

## 部署关卡

每个验证者都会对每笔部署交易运行关卡——参见[部署合约](/zh/build/deploy#_4-what-every-validator-does)：

| 情形 | 结果 |
|------|------|
| 字节码哈希在受信任列表中（如 NRC-20 等官方模板） | 分数 100，不做分析 |
| 关卡已被治理关闭（`deploy_security_enabled = 0`） | 中性分数 70 |
| `risk ≥ deploy_risk_threshold`（默认 0.80） | 部署失败，不收费；连同违规项写入日志；计入 `nc_deploy_rejected_total` |
| 其他情况 | 创建合约并记录其分数 |

## 自行检查合约

```bash
curl -s -X POST "$NODE_RPC/api/v1/contracts/analyze" \
  -H 'Content-Type: application/json' -d "{\"bytecode_hex\":\"$HEX\"}"
```

```json
{
  "risk_score": 0,
  "security_score": 100,
  "safe": true,
  "ml_score": 0.439,
  "model": "heuristic",
  "violations": [],
  "gas_estimate": 34550
}
```

（这里网络给出 0.44，而规则给出 0，因此仅由规则决定。）

通过 gateway 时，请使用 `POST /api/v1/contracts/audit`，请求体相同。gateway 从不自行为合约评分；它只转发给节点。

## 签名证明

`POST /api/v1/contracts/attest` 运行同样的分析，并用节点的 ML-DSA-65 密钥对结果签名：

```json
{
  "score": 100,
  "risk_score": 0,
  "bytecode_hash": "18642df0…",
  "timestamp": 1791200887,
  "signature": "665a7ab2…",
  "pubkey": "6e80bab8…",
  "model": "heuristic",
  "ml_score": 0.439,
  "violations": []
}
```

被签名的消息为 `"nc-attest|" ‖ score（4 字节，大端序） ‖ SHA3-256(bytecode)（32 字节） ‖ timestamp（8 字节，大端序）`。浏览器用与钱包相同的 WASM 模块验证它，随后部署页面显示经过证明的分数。

证明能说明是*哪个节点*计算了分数。在无需信任节点的前提下证明分数计算正确，是下文 ZKML 工作的目标。

## 证书

合约按分数获得链上安全证书：

| 等级 | 分数 |
|------|------|
| Gold | 90 及以上 |
| Silver | 75 – 89 |
| Bronze | 低于 75 |

证书是创世时部署的系统合约 `ncert.app` 中的记录，并为 API 建立了索引：`GET /api/v1/certificates`、`/certificates/:id`、`/certificates/contract/:address`。

## 持续监控

每个节点每隔 `MONITOR_INTERVAL_SECS`（20 秒）重新分析已部署的合约。当分数变化达到 `MONITOR_SCORE_THRESHOLD`（10）分或以上时——通常发生在新模型版本激活之后——节点通过共识发出证书更新，预言机日志记录 `score_degraded` 或 `score_improved`。

gateway 在此之上还提供活动告警（通过 [WebSocket](/zh/reference/websocket) 发送 `contract_alert`）：异常的调用激增，以及开始被调用的低分合约。

## 模型版本

模型权重在链上进行版本管理，因此所有验证者运行同一个模型：

1. 某个验证者注册一个新版本（`POST /api/v1/models/register`，仅限验证者）——它进入为期 2 000 个区块的 `voting` 状态。
2. 其他验证者通过 P2P 获取权重，将其哈希与注册信息核对，然后确认。
3. 获得 `2f + 1` 个验证者的确认后，该版本变为 `active` 并替换前一个版本；否则在截止时变为 `rejected`。

注册表：`GET /api/v1/models/registry`。Prometheus：`nc_model_active_count`、`nc_model_voting_count`、`nc_model_version{…}`。

## 可验证 AI <Badge type="warning" text="实验性" />

计划是用零知识虚拟机（RISC Zero / SP1）证明 VMGuardian 的结果：证明*该分数就是链所批准权重下的 `analyze_v2(bytecode)`*，任何人——包括另一条链——都可以在不信任任何节点的情况下验证。这些模型足够小，使这一方案切实可行。

**测试情况：** 设计和证明器脚手架已在仓库中（`docs/zkml-poc.md`、`neurochain/zkml/`）。构建证明器需要 RISC Zero / SP1 工具链，而它尚未在项目的构建环境中运行过；目前还没有链上验证。

## 局限

- 仅基于合成数据和真实的*安全*合约训练——尚未见过 WASM 中的真实漏洞利用。
- 目前尚不提供发现项的字节偏移和自定义规则集。
- 干净的分数意味着未发现已知的风险模式，而不代表合约是正确的。