> For the complete documentation index, see [llms.txt](https://docs.neurochain.ai/nc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neurochain.ai/nc/neurochainai-guides/components/gateway-node.md). # 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