# Gateway

> NeuroChain gateway 실행 — 노드 앞에서 REST와 WebSocket을 제공하고, 샤드별로 라우팅하며, 실시간 이벤트를 브로드캐스트하고, 요청을 제한하고, 선택적 AI 도구를 호스팅하는 Node.js 서비스의 설정, 구성, 보안 참고 사항입니다.

Source: https://docs.nro.world/ko/operate/gateway

Gateway는 사용자와 노드 사이에 있는 Node.js(Fastify) 서비스입니다. 웹 앱, SDK, MCP 서버는 모두 gateway와 통신합니다.

| 하는 일 | 세부 사항 |
|---------|-----------|
| REST API 제공 | 대부분의 경로는 노드를 프록시하며, 일부는 자체 경로입니다 — [REST](/ko/reference/rest) 참고 |
| WebSocket 제공 | `/ws` — 실시간 블록, 트랜잭션, AI 이벤트, 잔액 구독. [WebSocket](/ko/reference/websocket) 참고 |
| 샤드별 라우팅 | 각 트랜잭션을 발신자의 샤드를 담당하는 노드로 보냅니다 |
| 체인 감시 | 노드를 폴링하고, 변경 사항을 이벤트로 변환하며, 컨트랙트 활동 알림을 발생시킵니다 |
| 요청 제한 | IP별, 전역 및 AI 엔드포인트별 |
| AI 도구 호스팅 | 컨트랙트 감사 프록시, 컨트랙트 생성(SmartForge), 문서 도우미 |

Gateway는 체인 상태에 대해 아무것도 결정하지 않습니다: 서명, 잔액, AI 점수는 노드에서 옵니다.

## 실행

```bash
cd neurochain/gateway
npm install
NODE_RPC_URL=http://localhost:9933 node src/index.js
```

```bash
curl -s http://localhost:3000/health
# {"status":"ok","network":"neurochain-mainnet-1","height":11,"peers":0,"round":0,"mempool":0}
```

모든 인터페이스의 `PORT`(3000) 포트에서 수신합니다.

## 구성 {#configuration}

### 연결

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `PORT` | `3000` | 수신 포트 |
| `NODE_RPC_URL` | `http://localhost:9933` | 노드의 RPC |
| `NEUROCHAIN_SHARD_NODES` | — | 샤드 라우팅, 예: `0=http://n0:9933,1=http://n1:9934` |
| `SHARD_NODE_URLS` | — | 위와 같지만 위치 기반(인덱스 = 샤드)이며, 위 변수가 설정되지 않았을 때 사용됩니다 |
| `NETWORK_ID` | `neurochain-mainnet-1` | `/health`에 표시되는 네트워크 이름 |
| `CORS_ALLOWED_ORIGINS` | `*` | 허용되는 브라우저 출처 — 프로덕션에서는 사이트의 출처를 설정하십시오 |
| `TLS_CERT`, `TLS_KEY` | — | HTTPS를 직접 제공하기 위한 PEM 경로 |

### 한도

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `GLOBAL_RL_MAX_RPS` | 200 | IP당 초당 요청 수 |
| `AI_RL_MAX_RPM` | 10 | IP당 분당 AI 엔드포인트 요청 수 |
| `WS_MAX_MSG_BYTES` | 65 536 | 최대 WebSocket 메시지 크기 |
| `WS_MAX_SUBS_PER_CLIENT` | 50 | 연결당 잔액 구독 수 |
| `WS_RPC_MAX_RPS` | 30 | 연결당 초당 RPC 호출 수 |

### 체인 감시

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `POLL_NODE_INTERVAL_MS` | 2000 | 새 블록을 위해 노드를 폴링하는 주기 |
| `SENTINEL_CHECK_INTERVAL_MS` | 30000 | 컨트랙트 활동 확인 주기 |
| `SENTINEL_SPIKE_LOW_THRESHOLD` / `_HIGH_THRESHOLD` | 10 / 50 | 중간 / 높은 수준 알림을 발생시키는 주기당 호출 수 |
| `SENTINEL_LOW_SCORE_THRESHOLD` | 60 | 이 보안 점수 미만의 컨트랙트가 호출되기 시작하면 알림 |
| `ALERT_COOLDOWN_MS` | 60000 | 한 컨트랙트에 대한 알림 사이의 최소 간격 |
| `PROTOCOL_PARAMS_REFRESH_MS` | 60000 | 노드에서 프로토콜 파라미터를 다시 읽는 주기 |

### Faucet(테스트 네트워크)

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `FAUCET_AMOUNT` | 50 NRO | 요청당 금액 |
| `FAUCET_COOLDOWN_SECS` | 86400 | 주소 및 IP별 |
| `REDIS_URL` | `redis://localhost:6379` | 선택 사항 — gateway를 재시작해도 faucet 쿨다운을 유지합니다. Redis가 없으면 메모리에 보관됩니다 |

### AI 도구

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `ANTHROPIC_API_KEY` | — | Claude를 이용한 SmartForge 컨트랙트 생성을 활성화합니다. 없으면 내장 템플릿 생성기가 사용됩니다 |
| `SMARTFORGE_MODEL`, `SMARTFORGE_MAX_TOKENS` | — | SmartForge의 모델과 길이 |
| `AI_EXPORT_TOKEN` | — | 설정하면 `/api/v1/ai/export/*`에 이 토큰이 필요합니다 |
| `ASSISTANT_ENABLED` | `0` | 문서 도우미(`POST /api/v1/assistant/ask`). 인덱스는 `npm run assistant:index`로 다시 빌드합니다 |

모든 기본값이 포함된 전체 목록은 저장소의 `.env.example`에 있습니다.

## 보안 참고 사항

- 노드의 RPC는 비공개로 두고 gateway만 노출하십시오(TLS가 있는 리버스 프록시 뒤에 두거나 `TLS_CERT` / `TLS_KEY` 사용).
- `CORS_ALLOWED_ORIGINS`를 자신의 출처로 설정하십시오.
- `POST /api/v1/wallet/derive-address`는 복구 구문을 받습니다. mainnet에서는 노드가 이를 거부하며, 공개 gateway에서는 절대 접근할 수 없어야 합니다.
- `/api/v1/network/status`의 일부 필드(`tps_peak`, `block_time_ms`, `crypto` 목록, AI 모델 수치)는 측정값이 아닌 고정된 설명 값입니다.

## 테스트

```bash
cd neurochain/gateway
npm test            # HTTP API 테스트, 전체 세트에는 노드가 실행 중이어야 함
```