Getting Started

This guide will help you get NCN Network v2 running on your local machine in about 15 minutes.

---

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Software	Version	Installation
Rust	1.70+	rustup.rs
Python	3.8+	python.org
Git	2.0+	git-scm.com

Verify Installation

# Check Rust version
rustc --version
# Expected: rustc 1.70.0 or higher

# Check Python version
python3 --version
# Expected: Python 3.8 or higher

# Check Git version
git --version
# Expected: git version 2.0 or higher

Hardware Requirements

For local development:

• CPU: 4+ cores recommended

• RAM: 8 GB minimum, 16 GB recommended

• Storage: 10 GB free space

---

Installation

Step 1: Clone the Repository

git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs

Step 2: Build All Components

# Build in release mode (recommended)
cargo build --release

# Or build in debug mode for development
cargo build

This will create the following binaries in target/release/ (or target/debug/):

• p2p_registry_node - P2P Registry service

• gateway_node - Gateway service

• compute_node - Compute Node service

• test_client - Test client

• subnet-cli - Subnet management CLI

Step 3: Set Up Python Environment (Optional)

If you want to run model inference:

cd compute_node/python_executors

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Verify installation
python verify_environment.py

---

Running the Network

You'll need 4 terminal windows to run all components:

Terminal 1: P2P Registry

The P2P Registry is the coordination service for the network.

cd ncn-network-v2-rs

# Start P2P Registry with default settings
cargo run --release --bin p2p_registry_node

# Or with custom settings
cargo run --release --bin p2p_registry_node -- \
  --p2p-listen-addr /ip4/0.0.0.0/tcp/8828 \
  --grpc-listen-addr 127.0.0.1:50050

Expected output:

Starting P2P Registry Node...
P2P listening on /ip4/0.0.0.0/tcp/8828
gRPC server listening on 127.0.0.1:50050
✓ P2P Registry initialized successfully

Terminal 2: Gateway Node

The Gateway routes inference requests and manages payments.

cd ncn-network-v2-rs/gateway_node

# Copy and configure environment
cp env.example .env

# Edit .env with your settings (optional for local dev)
# nano .env

# Start Gateway
cargo run --release --bin gateway_node

Expected output:

Starting Gateway Node...
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
Connected to P2P Registry at http://127.0.0.1:50050
✓ Gateway Node initialized successfully

Terminal 3: Compute Node

The Compute Node executes AI models.

cd ncn-network-v2-rs

# Start Compute Node
cargo run --release --bin compute_node -- \
  --gateway-addr http://127.0.0.1:50051 \
  --model-path ./models

Expected output:

Starting Compute Node...
Connecting to Gateway at http://127.0.0.1:50051
Model path: ./models
✓ Connected to Gateway
✓ Registered with Gateway
✓ Compute Node ready for tasks

Terminal 4: Test Client

Run a test inference request:

cd ncn-network-v2-rs

# Run basic test
cargo run --release --bin test_client

Expected output:

╔════════════════════════════════════════╗
║  NCN Network Test Client               ║
╚════════════════════════════════════════╝

Connecting to Gateway at http://127.0.0.1:50051...
✓ Connected to Gateway

Submitting inference request...
Task ID: abc123-def456-...
Status: queued

Waiting for result...
✓ Received result in 1.25s

Output: [inference result data]

---

Quick Start with Docker

For a faster setup, use Docker Compose:

cd ncn-network-v2-rs

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

This starts:

• P2P Registry on port 50050

• Gateway on ports 50051 (gRPC), 8080 (HTTP), 9000 (WebSocket)

• Compute Node connected to Gateway

See Docker Deployment Guide for more details.

---

Verify Everything is Working

Check Service Health

# Check P2P Registry
curl http://127.0.0.1:50050/health
# Expected: {"status": "healthy"}

# Check Gateway
curl http://127.0.0.1:8080/health
# Expected: {"status": "healthy"}

Submit a Test Request via HTTP

curl -X POST http://127.0.0.1:8080/api/v1/inference \
  -H "Content-Type: application/json" \
  -d '{
    "model_uuid": "test-model",
    "input_data": "{\"text\": \"Hello, world!\"}"
  }'

---

Directory Structure

After building, your directory should look like:

ncn-network-v2-rs/
├── target/release/           # Compiled binaries
│   ├── gateway_node
│   ├── compute_node
│   ├── p2p_registry_node
│   ├── test_client
│   └── subnet-cli
├── gateway_node/
│   ├── .env                  # Your configuration
│   └── env.example           # Example configuration
├── compute_node/
│   ├── models/               # AI models directory
│   └── python_executors/     # Python execution scripts
├── contracts/                # Smart contracts
├── proto/                    # Protocol definitions
└── docs/                     # Documentation

---

What's Next?

Now that you have NCN Network running locally, explore these topics:

Understand the System

• Key Concepts - Learn the terminology

• System Architecture - How it all fits together

• Payment Flow - How payments work

Deploy & Operate

• Docker Deployment - Production-ready containers

• Gateway Operator Guide - Run a gateway

• Compute Operator Guide - Provide compute

Integrate

• gRPC Client Guide - Build a client

• HTTP API Reference - REST API docs

• Payment Integration - Add payments

---

Troubleshooting

Common Issues

Build Fails with "linker not found"

Install build essentials:

# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install

"Connection refused" to P2P Registry

Ensure the P2P Registry is running and check the address:

# Verify P2P Registry is running
ps aux | grep p2p_registry

# Check if port is listening
netstat -tlnp | grep 50050

Compute Node fails to connect to Gateway

Verify the Gateway address matches:

# The address should match what Gateway is listening on
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051

For more help, see the Troubleshooting Guide.

---

Need Help?

• FAQ - Frequently asked questions

• Troubleshooting - Common issues and solutions

• GitHub Issues - Report bugs or request features