# Gateway Operator

Complete guide for running a Gateway node on NCN Network.

***

## Overview

Gateway nodes are the entry points for clients. They:

* Accept inference requests from clients
* Route tasks to compute nodes
* Coordinate payments
* Manage subnet configurations

**Earnings**: \~10% of each inference fee (routing fee)

***

## Requirements

### Hardware

| Resource | Minimum   | Recommended |
| -------- | --------- | ----------- |
| CPU      | 2 cores   | 4 cores     |
| RAM      | 4 GB      | 8 GB        |
| Storage  | 50 GB SSD | 100 GB SSD  |
| Network  | 100 Mbps  | 1 Gbps      |

### Software

* Linux (Ubuntu 22.04 recommended)
* Rust 1.70+ (for building)
* Network connectivity to blockchain RPC

### Capital

* Subnet creation fee (varies by models)
* Gas for blockchain transactions
* Reserve for operational costs

***

## Setup

### 1. Install Dependencies

```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install build tools
sudo apt install -y build-essential pkg-config libssl-dev git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

### 2. Build Gateway

```bash
# Clone repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs

# Build release
cargo build --release -p gateway_node

# Copy binary
sudo cp target/release/gateway_node /usr/local/bin/
```

### 3. Generate Wallet

```bash
# Generate new wallet (or use existing)
# Save the private key securely!

# Using cast (Foundry)
cast wallet new

# Output:
# Address: 0x...
# Private Key: 0x...
```

### 4. Configure Gateway

Create `/etc/ncn/gateway.env`:

```bash
# Network Configuration
REGISTRY_GRPC_ADDR=http://registry.ncn-network.io:50050
RPC_URL=https://testnet-rpc-1.forknet.io
CHAIN_ID=828

# Contract Addresses
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
TOKEN_ADDRESS=0x38E2565e8905BeAf83C34b266592465C22A2f108

# Wallet (SECURE THIS!)
GATEWAY_WALLET_PRIVATE_KEY=0x...
GATEWAY_WALLET_ADDRESS=0x...

# Server Addresses
GRPC_ADDR=0.0.0.0:50051
HTTP_ADDR=0.0.0.0:8080
WS_ADDR=0.0.0.0:9000

# Payment Settings
REQUIRE_PAYMENT=true
ENABLE_PAYMENT_VERIFICATION=true
REQUIRED_CONFIRMATIONS=1

# Transaction Settings
GAS_LIMIT=500000
GAS_PRICE_MULTIPLIER=1.1

# Logging
RUST_LOG=info
```

### 5. Create Systemd Service

Create `/etc/systemd/system/ncn-gateway.service`:

```ini
[Unit]
Description=NCN Gateway Node
After=network.target

[Service]
Type=simple
User=ncn
EnvironmentFile=/etc/ncn/gateway.env
ExecStart=/usr/local/bin/gateway_node
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### 6. Start Gateway

```bash
# Create service user
sudo useradd -r -s /bin/false ncn

# Set permissions
sudo chown ncn:ncn /etc/ncn/gateway.env
sudo chmod 600 /etc/ncn/gateway.env

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable ncn-gateway
sudo systemctl start ncn-gateway

# Check status
sudo systemctl status ncn-gateway
```

***

## Create a Subnet

### 1. Prepare Subnet Configuration

Create `subnet_config.json`:

```json
{
  "models": [
    {
      "model_uuid": "bark_semantic",
      "source": "huggingface",
      "path": "suno/bark",
      "name": "Bark Semantic Model",
      "category": "audio",
      "description": "Text to semantic tokens",
      "max_tokens": 1024,
      "version": "1.0.0",
      "input_format": "json",
      "output_format": "json"
    },
    {
      "model_uuid": "bark_coarse",
      "source": "huggingface",
      "path": "suno/bark",
      "name": "Bark Coarse Model",
      "category": "audio",
      "description": "Semantic to coarse tokens",
      "max_tokens": 1024,
      "version": "1.0.0",
      "input_format": "json",
      "output_format": "json"
    }
  ]
}
```

### 2. Estimate Fee

```bash
# Using subnet CLI
cargo run --bin subnet-cli -- estimate -c subnet_config.json

# Output:
# Estimated fee: 0.05 ETH
# Fee quote ID: quote-123
# Valid until: 2024-01-15 10:00:00 UTC
```

### 3. Create Subnet

```bash
# Create subnet (will prompt for payment)
cargo run --bin subnet-cli -- create \
  -c subnet_config.json \
  --gateway-addr http://127.0.0.1:50051 \
  --wallet-key $GATEWAY_WALLET_PRIVATE_KEY

# Output:
# Subnet created!
# Subnet ID: 1
# Models: bark_semantic, bark_coarse
```

***

## Operations

### Monitor Gateway

```bash
# View logs
sudo journalctl -u ncn-gateway -f

# Check health
curl http://localhost:8080/health

# View metrics (if enabled)
curl http://localhost:8080/metrics
```

### View Connected Compute Nodes

```bash
# Check logs for registrations
grep "registered" /var/log/ncn/gateway.log

# Or via API (if implemented)
curl http://localhost:8080/api/v1/nodes
```

### Check Subnet Status

```bash
cargo run --bin subnet-cli -- list --gateway-addr http://127.0.0.1:50051
```

***

## Earnings

### Fee Distribution

For each inference request:

* **10%** goes to Gateway (you)
* **80%** goes to Compute Node
* **5%** goes to Validators
* **5%** goes to Treasury

### Track Earnings

```bash
# Check wallet balance
cast balance $GATEWAY_WALLET_ADDRESS --rpc-url $RPC_URL

# View transaction history
cast logs --from-block latest-1000 \
  --address $CONTRACT_ADDRESS \
  --rpc-url $RPC_URL
```

***

## Maintenance

### Update Gateway

```bash
# Stop service
sudo systemctl stop ncn-gateway

# Pull updates
cd ncn-network-v2-rs
git pull

# Rebuild
cargo build --release -p gateway_node

# Update binary
sudo cp target/release/gateway_node /usr/local/bin/

# Restart
sudo systemctl start ncn-gateway
```

### Backup Configuration

```bash
# Backup configuration and keys
sudo tar -czf gateway-backup.tar.gz /etc/ncn/

# Store securely offsite
```

### Rotate Keys

```bash
# Generate new wallet
cast wallet new

# Update configuration
sudo nano /etc/ncn/gateway.env

# Restart service
sudo systemctl restart ncn-gateway
```

***

## Troubleshooting

### Gateway Won't Start

```bash
# Check logs
sudo journalctl -u ncn-gateway -n 100

# Common issues:
# - Registry not reachable
# - Invalid private key
# - Port already in use
```

### No Compute Nodes

* Check compute nodes are running
* Verify they're targeting your gateway address
* Check network connectivity

### Payment Issues

* Verify RPC URL is correct
* Check wallet has sufficient balance
* Verify contract address

***

## Security Best Practices

1. **Secure Private Key**
   * Use hardware wallet or HSM in production
   * Never commit keys to version control
2. **Firewall**
   * Only expose necessary ports
   * Use TLS for production
3. **Monitoring**
   * Set up alerts for anomalies
   * Monitor for unauthorized access

***

## Next Steps

* [Monitoring](/nc/neurochainai-guides/operators/monitoring.md) - Set up monitoring
* [Production Deployment](/nc/neurochainai-guides/deployment/production.md) - Production hardening
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting.md) - Common issues


---

# 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/operators/gateway-operator.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.