# VMGuardian

> VMGuardian — AI-аудитор контрактів NeuroChain — п'ять правил для байткоду, вбудована нейромережа і як її результат змішується, шлюз розгортання на кожному валідаторі, підписані атестації, сертифікати, безперервний моніторинг і реєстр моделей у мережі.

Source: https://docs.nro.world/uk/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 імпортованих host-функцій |

Оцінка нижче 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`.

## Шлюз розгортання

Кожен валідатор запускає шлюз для кожної транзакції розгортання — див. [Розгортання контрактів](/uk/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 байти, big-endian) ‖ SHA3-256(bytecode) (32 байти) ‖ timestamp (8 байтів, big-endian)`. Браузер перевіряє його тим самим 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 додає зверху сповіщення про активність (`contract_alert` через [WebSocket](/uk/reference/websocket)): незвичні сплески викликів і контракти з низькою оцінкою, які почали викликати.

## Версії моделі

Ваги моделі версіонуються в мережі, тож усі валідатори працюють з однією моделлю:

1. Валідатор реєструє нову версію (`POST /api/v1/models/register`, лише валідатори) — вона переходить у `voting` на 2 000 блоків.
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="експериментально" />

План — доводити результат VMGuardian віртуальною машиною з нульовим розголошенням (RISC Zero / SP1): доказ, що *ця оцінка — `analyze_v2(bytecode)` з вагами, схваленими мережею*, який будь-хто — зокрема інша мережа — може перевірити без довіри до жодної ноди. Моделі досить малі, щоб це було практично.

**Як це тестується:** дизайн і каркас prover'а є в репозиторії (`docs/zkml-poc.md`, `neurochain/zkml/`). Для збірки prover'а потрібен інструментарій RISC Zero / SP1, який у середовищі збірки проєкту ще не запускався; перевірки в мережі поки немає.

## Обмеження

- Навчено лише на синтетичних даних і справжніх *безпечних* контрактах — справжніх експлойтів у WASM вона ще не бачила.
- Зміщення знахідок у байтах і власні набори правил поки недоступні.
- Чиста оцінка означає, що відомих ризикованих шаблонів не знайдено, а не що контракт правильний.