# VMGuardian

> NeuroChain의 AI 컨트랙트 감사기 VMGuardian — 다섯 가지 바이트코드 규칙, 내장 신경망과 그 결과를 혼합하는 방법, 모든 검증자가 실행하는 배포 게이트, 서명된 증명, 인증서, 지속적 모니터링, 온체인 모델 레지스트리.

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

VMGuardian은 WebAssembly 바이트코드를 감사합니다. **같은 코드**로 세 곳에서 실행되므로, 컨트랙트는 어디서나 같은 점수를 받습니다.

| 위치 | 시점 |
|------|------|
| 브라우저(WASM 모듈) | 배포를 보내기 전, 즉시 |
| 모든 검증자, 합의 과정에서 | 모든 배포 트랜잭션마다 — 게이트 |
| 모든 노드, 백그라운드에서 | 배포된 모든 컨트랙트에 대해 지속적으로 |

## 점수가 만들어지는 방식

### 1. 규칙(휴리스틱)

분석기는 코드 섹션을 명령어 단위로 디코딩하고(한 번의 선형 패스이므로 512 KiB 컨트랙트도 빠르게 분석됩니다) 다섯 가지 패턴을 검사합니다. 일치할 때마다 위험도가 더해지며, 합계는 1.0으로 제한됩니다.

| 규칙 | 심각도 | 가산 | 발동 조건 |
|------|--------|------|-----------|
| `reentrancy` | 치명적 | 0.40 | 동적 `call_indirect` 뒤에 스토리지 쓰기가 이어짐 |
| `uncapped_loop` | 치명적 | 0.35 | 빠져나가는 조건 분기가 없는 루프 |
| `unbounded_memory` | 경고 | 0.20 | `memory.grow` 명령어가 8개 초과 |
| `unchecked_call` | 경고 | 0.15 | 결과를 버리는 호출 |
| `large_import_surface` | 정보 | 0.10 | import한 host 함수가 20개 초과 |

0.5 미만의 점수는 `safe`로 보고됩니다.

### 2. 신경망

작은 내장 신경망(입력 10 → 32 → 16 → 1, 파라미터 897개)이 같은 바이트코드를 열 가지 특징으로 평가합니다: 제한 없는 루프의 비율, 재진입 패턴, 결과를 버리는 호출, `memory.grow`·import·간접 호출·저장·루프·산술 연산의 밀도, 그리고 코드 크기. 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`입니다.

## 배포 게이트

모든 검증자가 각 배포 트랜잭션에 대해 게이트를 실행합니다 — [컨트랙트 배포](/ko/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는 그 위에 활동 알림을 추가합니다([WebSocket](/ko/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)`*라는 증명으로, 어떤 노드도 신뢰하지 않고 누구나 — 다른 체인을 포함해 — 확인할 수 있습니다. 모델이 충분히 작아서 이것이 실용적입니다.

**테스트 방법:** 설계와 prover 골격이 저장소에 있습니다(`docs/zkml-poc.md`, `neurochain/zkml/`). prover를 빌드하려면 RISC Zero / SP1 툴체인이 필요한데, 프로젝트의 빌드 환경에서는 아직 실행된 적이 없습니다. 온체인 검증은 아직 없습니다.

## 한계

- 합성 데이터와 실제 *안전한* 컨트랙트로만 학습되었습니다 — WASM의 실제 익스플로잇은 아직 보지 못했습니다.
- 발견 항목의 바이트 오프셋과 사용자 정의 규칙 세트는 아직 제공되지 않습니다.
- 깨끗한 점수는 알려진 위험 패턴이 발견되지 않았다는 뜻이지, 컨트랙트가 올바르다는 뜻이 아닙니다.