# 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](https://docs.neurochain.ai/nc/neurochainai-guides/operators/monitoring) - Set up monitoring
* [Production Deployment](https://docs.neurochain.ai/nc/neurochainai-guides/deployment/production) - Production hardening
* [Troubleshooting](https://docs.neurochain.ai/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues