Running Locally

Guide for running NCN Network services on your local machine for development.

---

Quick Start

# Terminal 1: Start P2P Registry
cargo run --bin p2p_registry_node

# Terminal 2: Start Gateway
cargo run --bin gateway_node

# Terminal 3: Start Compute Node
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051

# Terminal 4: Run Test Client
cargo run --bin test_client

---

Prerequisites

• Environment Setup completed

• Project Built successfully

• 4 terminal windows available

---

Step 1: Start P2P Registry

The P2P Registry must start first as other services depend on it.

# Start with default settings
cargo run --bin p2p_registry_node

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

Expected Output

Starting P2P Registry Node...
P2P listening on /ip4/0.0.0.0/tcp/8828
Local peer ID: 12D3KooW...
gRPC server listening on 127.0.0.1:50050
✓ Validator pool initialized
✓ Mempool initialized
✓ P2P Registry ready

Verify Registry

# Check gRPC is responding
grpcurl -plaintext localhost:50050 list

---

Step 2: Start Gateway Node

Open a new terminal:

# Navigate to project root
cd ncn-network-v2-rs

# Copy example environment file
cp gateway_node/env.example gateway_node/.env

# Edit configuration if needed
nano gateway_node/.env

# Start Gateway
cargo run --bin gateway_node

Environment Variables

Create or edit gateway_node/.env:

# Required
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050

# Optional (defaults shown)
GRPC_ADDR=127.0.0.1:50051
HTTP_ADDR=127.0.0.1:8080
WS_ADDR=127.0.0.1:9000

# Development mode
REQUIRE_PAYMENT=false
ENABLE_PAYMENT_VERIFICATION=false

# Logging
RUST_LOG=info

Expected Output

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

Verify Gateway

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

# Check gRPC
grpcurl -plaintext localhost:50051 list

---

Step 3: Start Compute Node

Open a new terminal:

# Navigate to project root
cd ncn-network-v2-rs

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

Configuration Options

cargo run --bin compute_node -- \
  --gateway-addr http://127.0.0.1:50051 \
  --model-path ./models \
  --sandbox-mode disabled \
  --execution-timeout 300

Environment Variables

export SANDBOX_MODE=disabled      # For development
export REQUIRE_PAYMENT=false      # Skip payment verification
export RUST_LOG=info

Expected Output

Starting Compute Node...
Connecting to Gateway at http://127.0.0.1:50051
✓ Registered with Gateway
Waiting for tasks...

Verify Compute Node

The Gateway logs should show:

Compute node registered: compute-xxx (wallet: 0x...)

---

Step 4: Run Test Client

Open a new terminal:

# Navigate to project root
cd ncn-network-v2-rs

# Run test client
cargo run --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: req-abc123
Status: queued

⏳ Waiting for result...
✓ Received result

Output: [model output data]

✅ Test completed successfully!

---

Local Development Workflow

Full Stack Command Reference

# Terminal 1 - Registry
cargo run --bin p2p_registry_node

# Terminal 2 - Gateway
REQUIRE_PAYMENT=false cargo run --bin gateway_node

# Terminal 3 - Compute
SANDBOX_MODE=disabled cargo run --bin compute_node -- \
  --gateway-addr http://127.0.0.1:50051

# Terminal 4 - Test Client
cargo run --bin test_client

Using cargo-watch (Auto-Restart)

# Install cargo-watch
cargo install cargo-watch

# Auto-restart on file changes
cargo watch -x "run --bin gateway_node"

---

Local Blockchain (Optional)

For testing with payments:

Start Anvil

# Start local Ethereum node
anvil

# Expected output:
# Available Accounts (10)
# Private Keys (10)
# Listening on 127.0.0.1:8545

Deploy Contracts

cd contracts

# Deploy to local Anvil
forge script script/Deploy.s.sol \
  --rpc-url http://127.0.0.1:8545 \
  --broadcast

Configure Gateway for Payments

# gateway_node/.env
RPC_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x... # From deployment output
REQUIRE_PAYMENT=true
ENABLE_PAYMENT_VERIFICATION=true
GATEWAY_WALLET_PRIVATE_KEY=0x... # Anvil account

---

Port Reference

Service	Port	Protocol
P2P Registry gRPC	50050	gRPC
P2P Registry P2P	8828	libp2p
Gateway gRPC	50051	gRPC
Gateway HTTP	8080	HTTP
Gateway WebSocket	9000	WebSocket
Anvil (optional)	8545	JSON-RPC

---

Debugging Tips

Enable Debug Logging

# All components
export RUST_LOG=debug

# Specific component
export RUST_LOG=gateway_node=debug

# Trace level
export RUST_LOG=trace

Check Service Connectivity

# Registry health
grpcurl -plaintext localhost:50050 list

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

# Gateway gRPC
grpcurl -plaintext localhost:50051 list

View Active Connections

# Check listening ports
netstat -tlnp | grep -E "(50050|50051|8080|9000|8828)"

# Or using lsof
lsof -i :50051

---

Common Issues

"Connection refused" to Registry

# Ensure Registry is running first
ps aux | grep p2p_registry

# Check port is listening
netstat -tlnp | grep 50050

"No compute nodes available"

• Ensure Compute Node is running

• Check Gateway logs for registration

• Verify model paths exist

"Sandbox failed" on Compute

# Disable sandbox for development
export SANDBOX_MODE=disabled
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051

Changes not taking effect

# Rebuild after changes
cargo build

# Or use cargo-watch
cargo watch -x "run --bin gateway_node"

---

Next Steps

• Testing - Run the test suite

• Debugging - Debug issues

• Docker Deployment - Deploy with Docker