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

cd gateway_node
cargo build --release

Configure

# Copy example configuration
cp env.example .env

# Edit configuration (minimum required)
nano .env

Minimum Configuration:

# 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

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 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 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 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 for complete details.

---

Subnet CLI

The Gateway includes a CLI tool for subnet management:

# 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 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

{
  "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 for more help.

---

Related Documentation

• Architecture - Internal architecture details

• gRPC API - gRPC API reference

• HTTP API - HTTP API reference

• WebSocket API - WebSocket API reference

• Configuration - Configuration options

• Subnet CLI - Subnet management CLI