Overview

NCN Network v2 consists of five main components that work together to provide decentralized AI inference.

---

Component Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                           NCN Network v2                                  │
│                                                                          │
│    ┌────────────────────────────────────────────────────────────────┐    │
│    │                        User Layer                               │    │
│    │   ┌──────────────────────────────────────────────────────┐     │    │
│    │   │               Test Client                             │     │    │
│    │   │   Example application for testing the network         │     │    │
│    │   └──────────────────────────────────────────────────────┘     │    │
│    └────────────────────────────────────────────────────────────────┘    │
│                                  │                                        │
│                                  ▼                                        │
│    ┌────────────────────────────────────────────────────────────────┐    │
│    │                       Gateway Layer                             │    │
│    │   ┌──────────────────────────────────────────────────────┐     │    │
│    │   │              Gateway Node                             │     │    │
│    │   │   • Routes inference requests                         │     │    │
│    │   │   • Manages compute reservations                      │     │    │
│    │   │   • Processes payments                                │     │    │
│    │   │   • Subnet CLI for management                         │     │    │
│    │   └──────────────────────────────────────────────────────┘     │    │
│    └────────────────────────────────────────────────────────────────┘    │
│                                  │                                        │
│                                  ▼                                        │
│    ┌────────────────────────────────────────────────────────────────┐    │
│    │                       Compute Layer                             │    │
│    │   ┌──────────────────────────────────────────────────────┐     │    │
│    │   │              Compute Node                             │     │    │
│    │   │   • Executes AI models                                │     │    │
│    │   │   • Sandboxed Python execution                        │     │    │
│    │   │   • Signs computation results                         │     │    │
│    │   │   • Model caching and management                      │     │    │
│    │   └──────────────────────────────────────────────────────┘     │    │
│    └────────────────────────────────────────────────────────────────┘    │
│                                  │                                        │
│                                  ▼                                        │
│    ┌────────────────────────────────────────────────────────────────┐    │
│    │                    Coordination Layer                           │    │
│    │   ┌──────────────────────────────────────────────────────┐     │    │
│    │   │              P2P Registry                             │     │    │
│    │   │   • Node discovery                                    │     │    │
│    │   │   • Validator consensus                               │     │    │
│    │   │   • Subnet management                                 │     │    │
│    │   │   • DHT-based storage                                 │     │    │
│    │   └──────────────────────────────────────────────────────┘     │    │
│    └────────────────────────────────────────────────────────────────┘    │
│                                  │                                        │
│                                  ▼                                        │
│    ┌────────────────────────────────────────────────────────────────┐    │
│    │                      Blockchain Layer                           │    │
│    │   ┌──────────────────────────────────────────────────────┐     │    │
│    │   │             Smart Contracts                           │     │    │
│    │   │   • InferencePayment (payment handling)               │     │    │
│    │   │   • NCNToken (ERC20 payment token)                    │     │    │
│    │   │   • ValidatorRegistry (on-chain validators)           │     │    │
│    │   └──────────────────────────────────────────────────────┘     │    │
│    └────────────────────────────────────────────────────────────────┘    │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

---

Component Summary

Component	Purpose	Technology	Documentation
Gateway Node	Request routing & payments	Rust, Tokio, Tonic	Details →
Compute Node	Model execution	Rust, Python	Details →
P2P Registry	Coordination & consensus	Rust, libp2p	Details →
Smart Contracts	On-chain payments	Solidity	Details →
Test Client	Testing & examples	Rust	Details →

---

Communication Protocols

Source	Destination	Protocol	Port
Client	Gateway	gRPC	50051
Client	Gateway	HTTP REST	8080
Client	Gateway	WebSocket	9000
Gateway	Compute	gRPC (stream)	50051
Gateway	Registry	gRPC	50050
Compute	Registry	gRPC	50050
Registry	Registry	libp2p	8828
All	Blockchain	JSON-RPC	External

---

Data Flow

Inference Request Flow

1. Client → Gateway (HTTP/gRPC)
   Request with model_uuid and input_data

2. Gateway → Registry (gRPC)
   Discover available compute nodes

3. Gateway internal
   Reserve compute node

4. Gateway → Registry (gRPC)
   Request preprocessing validation

5. Client → Blockchain (JSON-RPC)
   Submit payment transaction

6. Gateway → Compute (gRPC stream)
   Dispatch inference task

7. Compute internal
   Execute model in sandbox

8. Compute → Gateway (gRPC stream)
   Return signed result

9. Gateway → Registry (gRPC)
   Request completion validation

10. Gateway → Blockchain (JSON-RPC)
    Finalize payment distribution

11. Gateway → Client (HTTP/gRPC/WS)
    Return inference result

---

Build Instructions

Build All Components

# Clone repository
git clone https://github.com/your-org/ncn-network-v2-rs.git
cd ncn-network-v2-rs

# Build all components in release mode
cargo build --release

# Binaries available at:
# - target/release/gateway_node
# - target/release/compute_node
# - target/release/p2p_registry_node
# - target/release/test_client
# - target/release/subnet-cli

Build Individual Components

# Gateway Node
cargo build --release -p gateway_node

# Compute Node
cargo build --release -p compute_node

# P2P Registry
cargo build --release -p p2p_registry_node

# Test Client
cargo build --release -p test_client

Build Smart Contracts

cd contracts

# Install Foundry (if needed)
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Build contracts
forge build

# Run tests
forge test -vvv

---

Dependencies

Rust Crates (Workspace)

# Core async runtime
tokio = { version = "1", features = ["full"] }

# gRPC framework
tonic = "0.14.2"
prost = "0.14.1"

# P2P networking
libp2p = "0.56.0"

# Ethereum integration
ethers = { version = "2.0", features = ["legacy"] }

# CLI
clap = { version = "4.4", features = ["derive", "env"] }

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

Python Dependencies

# Model execution
torch>=2.1.0
transformers>=4.35.0

# Numerical computing
numpy>=1.24.3
scipy>=1.11.3

# Audio processing
soundfile>=0.12.1
librosa>=0.10.1

Smart Contract Dependencies

# OpenZeppelin contracts
openzeppelin-contracts = "5.0.0"

# Foundry forge-std
forge-std = "1.8.0"

---

Configuration Quick Reference

Component	Config File	Key Settings
Gateway	gateway_node/.env	GATEWAY_PRIVATE_KEY, RPC_URL, REGISTRY_GRPC_ADDR
Compute	Environment vars	GATEWAY_ADDR, MODEL_PATH, SANDBOX_MODE
Registry	Command line	--p2p-listen-addr, --grpc-listen-addr
Contracts	contracts/.env	PRIVATE_KEY, RPC_URL

See Configuration Guide for complete details.

---

Quick Start

1. Start P2P Registry

cargo run --release --bin p2p_registry_node

2. Start Gateway

cd gateway_node
cp env.example .env
# Edit .env as needed
cargo run --release --bin gateway_node

3. Start Compute Node

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

4. Run Test Client

cargo run --release --bin test_client

---

Next Steps

Explore each component in detail:

• Gateway Node - Request routing and payment processing

• Compute Node - Model execution and sandboxing

• P2P Registry - Coordination and consensus

• Smart Contracts - On-chain payment logic

• Test Client - Testing and integration examples