# Gateway Node

The Gateway Node is the primary entry point for clients into the NCN Network. It routes inference requests, manages compute node reservations, and handles payment processing.

***

## Overview

```
┌─────────────────────────────────────────────────────────────────────────┐
│                            Gateway Node                                  │
│                                                                         │
│   External Interfaces                    Internal Services              │
│   ┌─────────────┐                       ┌────────────────────┐          │
│   │    gRPC     │◀──────────────────────│ Reservation Manager│          │
│   │  (50051)    │                       └────────────────────┘          │
│   └─────────────┘                                                       │
│   ┌─────────────┐                       ┌────────────────────┐          │
│   │    HTTP     │◀──────────────────────│ Payment Processor  │          │
│   │   (8080)    │                       └────────────────────┘          │
│   └─────────────┘                                                       │
│   ┌─────────────┐                       ┌────────────────────┐          │
│   │  WebSocket  │◀──────────────────────│   State Manager    │          │
│   │   (9000)    │                       └────────────────────┘          │
│   └─────────────┘                                                       │
│                                         ┌────────────────────┐          │
│   Outbound Connections                  │   Finalizer        │          │
│   ┌─────────────┐                       └────────────────────┘          │
│   │  Registry   │────▶ P2P Registry (50050)                             │
│   │   Client    │                                                       │
│   └─────────────┘                                                       │
│   ┌─────────────┐                                                       │
│   │ Blockchain  │────▶ Ethereum RPC                                     │
│   │   Client    │                                                       │
│   └─────────────┘                                                       │
│   ┌─────────────┐                                                       │
│   │  Compute    │◀───▶ Compute Nodes (bidirectional stream)             │
│   │   Stream    │                                                       │
│   └─────────────┘                                                       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

***

## Features

* **Multi-Protocol Support**: gRPC, HTTP REST, and WebSocket interfaces
* **Compute Node Management**: Reservation system for task assignment
* **Payment Processing**: Blockchain payment verification and finalization
* **State Persistence**: Crash recovery with persistent state
* **Subnet Management**: CLI tool for creating and managing subnets
* **Metrics**: Prometheus-compatible metrics endpoint

***

## Quick Start

### Build

```bash
cd gateway_node
cargo build --release
```

### Configure

```bash
# Copy example configuration
cp env.example .env

# Edit configuration (minimum required)
nano .env
```

**Minimum Configuration**:

```bash
# Wallet (generate with: cast wallet new)
GATEWAY_WALLET_PRIVATE_KEY=0x...

# Blockchain
RPC_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea

# Network
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050
```

### Run

```bash
cargo run --release --bin gateway_node
```

**Expected Output**:

```
Starting Gateway Node...
Loading configuration from environment...
✓ Wallet loaded: 0x742d35Cc...
✓ Connected to P2P Registry at http://127.0.0.1:50050
gRPC server listening on 127.0.0.1:50051
HTTP server listening on 127.0.0.1:8080
WebSocket server listening on 127.0.0.1:9000
✓ Gateway Node initialized successfully
```

***

## Architecture

### Internal Modules

| Module              | File                  | Purpose                                 |
| ------------------- | --------------------- | --------------------------------------- |
| gRPC Server         | `src/grpc.rs`         | Compute node and client gRPC interfaces |
| HTTP Server         | `src/http.rs`         | REST API for clients                    |
| WebSocket Server    | `src/ws.rs`           | Real-time updates                       |
| Reservation Manager | `src/reservation.rs`  | Compute node reservations               |
| Payment Processor   | `src/payment.rs`      | Payment handling                        |
| State Manager       | `src/state.rs`        | Request lifecycle state                 |
| Finalization        | `src/finalization.rs` | Completion handling                     |
| Registry Client     | `src/registry.rs`     | P2P Registry communication              |
| Contract Client     | `src/contract.rs`     | Blockchain interactions                 |

### Request Flow

```
Client Request
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Receive Request (gRPC/HTTP/WS)                           │
│    └── Parse InferenceRequest                               │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Reserve Compute Node                                      │
│    ├── Query Registry for available nodes                   │
│    └── Reserve best matching node                           │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Request Preprocessing Validation                          │
│    ├── Send to P2P Registry                                 │
│    └── Collect M-of-N validator signatures                  │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Wait for Payment                                          │
│    ├── Return payment info to client                        │
│    └── Monitor blockchain for transaction                   │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. Dispatch Task                                             │
│    ├── Send to reserved compute node                        │
│    └── Mark reservation as computing                        │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 6. Receive Result                                            │
│    ├── Verify compute node signature                        │
│    └── Request completion validation                        │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 7. Finalize Payment                                          │
│    ├── Call smart contract                                  │
│    └── Distribute funds                                     │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│ 8. Return Result                                             │
│    └── Send InferenceResponse to client                     │
└─────────────────────────────────────────────────────────────┘
```

***

## API Interfaces

### gRPC API

**Service**: `GatewayClientService`

| RPC                      | Request            | Response                   | Description              |
| ------------------------ | ------------------ | -------------------------- | ------------------------ |
| `SubmitInferenceTask`    | `InferenceRequest` | `InferenceTaskStatus`      | Submit inference request |
| `SubscribeToTaskUpdates` | `RequestID`        | `stream InferenceResponse` | Subscribe to results     |

**Service**: `GatewayComputeService`

| RPC                  | Request             | Response                  | Description           |
| -------------------- | ------------------- | ------------------------- | --------------------- |
| `ConnectComputeNode` | `stream NodeInfo`   | `stream InferenceRequest` | Bidirectional stream  |
| `SendResponse`       | `InferenceResponse` | `Ack`                     | Send completed result |
| `SyncModels`         | `SyncModelsRequest` | `SyncModelsResponse`      | Sync subnet models    |

See [gRPC API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/grpc-api.md) for details.

### HTTP API

| Endpoint                 | Method | Description              |
| ------------------------ | ------ | ------------------------ |
| `/api/v1/inference`      | POST   | Submit inference request |
| `/api/v1/inference/{id}` | GET    | Get inference status     |
| `/api/v1/health`         | GET    | Health check             |
| `/api/v1/metrics`        | GET    | Prometheus metrics       |

See [HTTP API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/http-api.md) for details.

### WebSocket API

| Event         | Direction       | Description        |
| ------------- | --------------- | ------------------ |
| `task_status` | Server → Client | Task status update |
| `task_result` | Server → Client | Inference result   |
| `error`       | Server → Client | Error notification |

See [WebSocket API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/websocket-api.md) for details.

***

## Configuration

### Environment Variables

| Variable                     | Required | Default           | Description                |
| ---------------------------- | -------- | ----------------- | -------------------------- |
| `GATEWAY_WALLET_PRIVATE_KEY` | Yes      | -                 | Gateway wallet private key |
| `GATEWAY_WALLET_ADDRESS`     | No       | Derived           | Gateway wallet address     |
| `RPC_URL`                    | Yes      | -                 | Blockchain RPC endpoint    |
| `CONTRACT_ADDRESS`           | Yes      | -                 | InferencePayment contract  |
| `REGISTRY_GRPC_ADDR`         | Yes      | -                 | P2P Registry address       |
| `GRPC_ADDR`                  | No       | `127.0.0.1:50051` | gRPC listen address        |
| `HTTP_ADDR`                  | No       | `127.0.0.1:8080`  | HTTP listen address        |
| `WS_ADDR`                    | No       | `127.0.0.1:9000`  | WebSocket listen address   |
| `SUBNET_ID`                  | No       | `1`               | Gateway's subnet ID        |
| `GAS_LIMIT`                  | No       | `500000`          | Default gas limit          |
| `REQUIRED_CONFIRMATIONS`     | No       | `1`               | Required tx confirmations  |

See [Configuration Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/configuration.md) for complete details.

***

## Subnet CLI

The Gateway includes a CLI tool for subnet management:

```bash
# Generate subnet configuration template
subnet-cli template -o my_subnet.json

# Validate configuration
subnet-cli validate -c my_subnet.json

# Estimate creation fee
subnet-cli estimate -c my_subnet.json

# Create subnet (with payment)
export GATEWAY_PRIVATE_KEY="0x..."
subnet-cli create -c my_subnet.json --yes

# List subnets
subnet-cli list

# Get subnet details
subnet-cli get -s 1
```

See [Subnet CLI Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/subnet-cli.md) for complete documentation.

***

## State Management

The Gateway persists state to handle restarts and crashes:

### Persisted Data

* Request lifecycle state
* Payment confirmations
* Compute completions
* Reservation status

### State File

```json
{
  "requests": {
    "req-123": {
      "status": "Computing",
      "created_at": 1704067200,
      "payment_tx": "0x...",
      "reserved_node": "0xCompute..."
    }
  }
}
```

### Recovery

On startup, the Gateway:

1. Loads persisted state
2. Resumes pending requests
3. Re-establishes compute node connections
4. Continues payment monitoring

***

## Metrics

Prometheus metrics available at `/api/v1/metrics`:

| Metric                            | Type    | Description               |
| --------------------------------- | ------- | ------------------------- |
| `gateway_requests_total`          | Counter | Total requests received   |
| `gateway_requests_active`         | Gauge   | Currently active requests |
| `gateway_requests_completed`      | Counter | Completed requests        |
| `gateway_requests_failed`         | Counter | Failed requests           |
| `gateway_payment_total_wei`       | Counter | Total payments processed  |
| `gateway_compute_nodes_connected` | Gauge   | Connected compute nodes   |
| `gateway_reservations_active`     | Gauge   | Active reservations       |

***

## Troubleshooting

### Common Issues

**"Failed to connect to Registry"**

```
Error: Failed to connect to P2P Registry at http://127.0.0.1:50050
```

* Verify P2P Registry is running
* Check `REGISTRY_GRPC_ADDR` configuration

**"No compute nodes available"**

```
Error: No nodes support model semantic.pt
```

* Verify compute nodes are connected and idle
* Check if model is in compute node's supported models

**"Payment verification failed"**

```
Error: Transaction not found or not confirmed
```

* Check blockchain connection (`RPC_URL`)
* Verify transaction has enough confirmations

See [Gateway Troubleshooting](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/gateway-issues.md) for more help.

***

## Related Documentation

* [Architecture](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/architecture.md) - Internal architecture details
* [gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/grpc-api.md) - gRPC API reference
* [HTTP API](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/http-api.md) - HTTP API reference
* [WebSocket API](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/websocket-api.md) - WebSocket API reference
* [Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/configuration.md) - Configuration options
* [Subnet CLI](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/subnet-cli.md) - Subnet management CLI


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.neurochain.ai/nc/neurochainai-guides/components/gateway-node.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.