# Gateway

> Run the NeuroChain gateway — the Node.js service in front of the node that serves REST and WebSocket, routes by shard, broadcasts live events, rate-limits, and hosts optional AI tools; setup, configuration and security notes.

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

The gateway is a Node.js (Fastify) service between users and the node. The web app, the SDKs and the MCP server all talk to it.

| It does | Details |
|---------|---------|
| Serves the REST API | Most paths proxy the node; a few are its own — see [REST](/reference/rest) |
| Serves the WebSocket | `/ws` — live blocks, transactions, AI events, balance subscriptions; see [WebSocket](/reference/websocket) |
| Routes by shard | Sends each transaction to the node serving the sender's shard |
| Watches the chain | Polls the node, turns changes into events, raises contract activity alerts |
| Rate-limits | Per IP, globally and for AI endpoints |
| Hosts AI tools | Contract audit proxy, contract generation (SmartForge), documentation assistant |

The gateway never decides anything about chain state: signatures, balances and AI scores come from the node.

## Run

```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}
```

It listens on port `PORT` (3000) on all interfaces.

## Configuration

### Connection

| Variable | Default | Meaning |
|----------|---------|---------|
| `PORT` | `3000` | Listening port |
| `NODE_RPC_URL` | `http://localhost:9933` | The node's RPC |
| `NEUROCHAIN_SHARD_NODES` | — | Shard routing, e.g. `0=http://n0:9933,1=http://n1:9934` |
| `SHARD_NODE_URLS` | — | Same, positional (index = shard), used if the above is unset |
| `NETWORK_ID` | `neurochain-mainnet-1` | Network name reported in `/health` |
| `CORS_ALLOWED_ORIGINS` | `*` | Allowed browser origins — set your site's origin in production |
| `TLS_CERT`, `TLS_KEY` | — | PEM paths to serve HTTPS directly |

### Limits

| Variable | Default | Meaning |
|----------|---------|---------|
| `GLOBAL_RL_MAX_RPS` | 200 | Requests per second per IP |
| `AI_RL_MAX_RPM` | 10 | AI endpoint requests per minute per IP |
| `WS_MAX_MSG_BYTES` | 65 536 | Largest WebSocket message |
| `WS_MAX_SUBS_PER_CLIENT` | 50 | Balance subscriptions per connection |
| `WS_RPC_MAX_RPS` | 30 | RPC calls per second per connection |

### Chain watching

| Variable | Default | Meaning |
|----------|---------|---------|
| `POLL_NODE_INTERVAL_MS` | 2000 | How often the node is polled for new blocks |
| `SENTINEL_CHECK_INTERVAL_MS` | 30000 | Contract activity check |
| `SENTINEL_SPIKE_LOW_THRESHOLD` / `_HIGH_THRESHOLD` | 10 / 50 | Calls per interval that raise a medium / high alert |
| `SENTINEL_LOW_SCORE_THRESHOLD` | 60 | Alert when a contract below this security score starts being called |
| `ALERT_COOLDOWN_MS` | 60000 | Minimum gap between alerts for one contract |
| `PROTOCOL_PARAMS_REFRESH_MS` | 60000 | How often protocol parameters are re-read from the node |

### Faucet (test networks)

| Variable | Default | Meaning |
|----------|---------|---------|
| `FAUCET_AMOUNT` | 50 NRO | Amount per request |
| `FAUCET_COOLDOWN_SECS` | 86400 | Per address and IP |
| `REDIS_URL` | `redis://localhost:6379` | Optional — keeps the faucet cooldown across gateway restarts; without Redis it is kept in memory |

### AI tools

| Variable | Default | Meaning |
|----------|---------|---------|
| `ANTHROPIC_API_KEY` | — | Enables SmartForge contract generation with Claude; without it a built-in template generator is used |
| `SMARTFORGE_MODEL`, `SMARTFORGE_MAX_TOKENS` | — | Model and length for SmartForge |
| `AI_EXPORT_TOKEN` | — | If set, `/api/v1/ai/export/*` requires it |
| `ASSISTANT_ENABLED` | `0` | Documentation assistant (`POST /api/v1/assistant/ask`); rebuild its index with `npm run assistant:index` |

The full list with every default is in the repository's `.env.example`.

## Security notes

- Keep the node's RPC private and expose only the gateway (behind a reverse proxy with TLS, or with `TLS_CERT` / `TLS_KEY`).
- Set `CORS_ALLOWED_ORIGINS` to your own origins.
- `POST /api/v1/wallet/derive-address` receives a recovery phrase; the node refuses it on mainnet, and it should never be reachable on a public gateway.
- Some fields of `/api/v1/network/status` (`tps_peak`, `block_time_ms`, the `crypto` list, AI model figures) are fixed descriptive values, not measurements.

## Tests

```bash
cd neurochain/gateway
npm test            # HTTP API tests; the node must be running for the full set
```