Network Topology

This document describes the network architecture and communication patterns in NCN Network v2.

---

Overview

NCN Network is a distributed system with four main node types communicating over multiple protocols.

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Network Topology                                     │
│                                                                             │
│                           Internet / Public                                 │
│   ┌───────────────────────────────────────────────────────────────────────┐ │
│   │                                                                       │ │
│   │    Clients                                                            │ │
│   │    ┌─────────┐    ┌─────────┐    ┌─────────┐                         │ │
│   │    │Client A │    │Client B │    │Client C │                         │ │
│   │    └────┬────┘    └────┬────┘    └────┬────┘                         │ │
│   │         │              │              │                               │ │
│   │         │    HTTP/gRPC │              │                               │ │
│   │         │              │              │                               │ │
│   └─────────┼──────────────┼──────────────┼───────────────────────────────┘ │
│             │              │              │                                 │
│             └──────────────┼──────────────┘                                 │
│                            │                                                │
│                            ▼                                                │
│   ┌───────────────────────────────────────────────────────────────────────┐ │
│   │                      Gateway Layer                                    │ │
│   │    ┌─────────────────────────────────────────────────────────────┐   │ │
│   │    │                    Gateway Nodes                             │   │ │
│   │    │    ┌─────────┐    ┌─────────┐    ┌─────────┐                │   │ │
│   │    │    │Gateway 1│    │Gateway 2│    │Gateway 3│                │   │ │
│   │    │    └────┬────┘    └────┬────┘    └────┬────┘                │   │ │
│   │    └─────────┼──────────────┼──────────────┼─────────────────────┘   │ │
│   └──────────────┼──────────────┼──────────────┼─────────────────────────┘ │
│                  │              │              │                            │
│                  │    gRPC      │              │                            │
│                  │              │              │                            │
│   ┌──────────────┼──────────────┼──────────────┼─────────────────────────┐ │
│   │              │              │              │    Compute Layer        │ │
│   │    ┌─────────▼──────────────▼──────────────▼─────────────────────┐   │ │
│   │    │                    Compute Nodes                             │   │ │
│   │    │    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐ │   │ │
│   │    │    │Compute 1│    │Compute 2│    │Compute 3│    │Compute N│ │   │ │
│   │    │    │  (GPU)  │    │  (GPU)  │    │  (CPU)  │    │  (GPU)  │ │   │ │
│   │    │    └─────────┘    └─────────┘    └─────────┘    └─────────┘ │   │ │
│   │    └─────────────────────────────────────────────────────────────┘   │ │
│   └──────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
│                                                                             │
│   ┌───────────────────────────────────────────────────────────────────────┐ │
│   │                      Registry Layer (P2P)                             │ │
│   │    ┌─────────────────────────────────────────────────────────────┐   │ │
│   │    │                   P2P Registry Nodes                         │   │ │
│   │    │    ┌─────────┐ ◀───▶ ┌─────────┐ ◀───▶ ┌─────────┐          │   │ │
│   │    │    │Registry1│       │Registry2│       │Registry3│          │   │ │
│   │    │    │(Validator)      │(Validator)      │(Validator)         │   │ │
│   │    │    └─────────┘       └─────────┘       └─────────┘          │   │ │
│   │    └─────────────────────────────────────────────────────────────┘   │ │
│   └───────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
│                                                                             │
│   ┌───────────────────────────────────────────────────────────────────────┐ │
│   │                      Blockchain Layer                                 │ │
│   │    ┌─────────────────────────────────────────────────────────────┐   │ │
│   │    │              Ethereum-Compatible Network                     │   │ │
│   │    │    ┌─────────────────┐    ┌─────────────────┐               │   │ │
│   │    │    │ InferencePayment│    │  NCNToken       │               │   │ │
│   │    │    │     Contract    │    │  (ERC20)        │               │   │ │
│   │    │    └─────────────────┘    └─────────────────┘               │   │ │
│   │    └─────────────────────────────────────────────────────────────┘   │ │
│   └───────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Node Types

Gateway Nodes

Role: Entry points for clients, task routing, payment coordination

Connections:

• Inbound: Clients (HTTP, gRPC, WebSocket)

• Outbound: Compute nodes (gRPC), Registry (gRPC), Blockchain (JSON-RPC)

Ports:

Port	Protocol	Purpose
8080	HTTP	REST API
50051	gRPC	Client & compute API
9000	WebSocket	Real-time updates

Compute Nodes

Role: Execute AI models, return results

Connections:

• Inbound: None (pull-based)

• Outbound: Gateway (gRPC), Registry (gRPC)

Ports: No exposed ports (connects outbound to gateway)

P2P Registry Nodes

Role: Node discovery, validator consensus, subnet management

Connections:

• Inbound: Gateways (gRPC), compute nodes (gRPC), other registries (P2P)

• Outbound: Other registries (P2P), Blockchain (JSON-RPC)

Ports:

Port	Protocol	Purpose
50050	gRPC	Registry API
8828	libp2p	P2P networking

Blockchain

Role: Payment settlement, validator registry, subnet records

Connections:

• Inbound: All nodes (JSON-RPC)

• Outbound: Other blockchain nodes

---

Communication Protocols

Client ↔ Gateway

Protocol	Use Case	Format
HTTP/REST	Simple requests	JSON
gRPC	High-performance	Protobuf
WebSocket	Real-time updates	JSON

Gateway ↔ Compute

Protocol	Use Case	Format
gRPC	Task dispatch	Protobuf
gRPC Streaming	Task reception	Protobuf

Gateway/Compute ↔ Registry

Protocol	Use Case	Format
gRPC	Validation requests	Protobuf
gRPC	Node discovery	Protobuf
gRPC	Subnet management	Protobuf

Registry ↔ Registry

Protocol	Use Case	Format
libp2p Kademlia	Peer discovery	Binary
libp2p DHT	State replication	Binary

All Nodes ↔ Blockchain

Protocol	Use Case	Format
JSON-RPC	Transaction submission	JSON
JSON-RPC	Event monitoring	JSON
WebSocket	Real-time events	JSON

---

Request Flow

Inference Request Path

   Client                Gateway              Registry             Compute
      │                     │                    │                    │
      │ 1. Submit request   │                    │                    │
      │────────────────────▶│                    │                    │
      │                     │                    │                    │
      │                     │ 2. Request         │                    │
      │                     │    preprocessing   │                    │
      │                     │───────────────────▶│                    │
      │                     │                    │                    │
      │                     │ 3. Validation      │                    │
      │                     │◀───────────────────│                    │
      │                     │                    │                    │
      │ 4. Payment info     │                    │                    │
      │◀────────────────────│                    │                    │
      │                     │                    │                    │
      │ 5. Pay blockchain   │                    │                    │
      │         │           │                    │                    │
      │         └─────────────────────────────────────────────────────▶ Blockchain
      │                     │                    │                    │
      │ 6. Confirm payment  │                    │                    │
      │────────────────────▶│                    │                    │
      │                     │                    │                    │
      │                     │ 7. Dispatch task   │                    │
      │                     │───────────────────────────────────────▶│
      │                     │                    │                    │
      │                     │                    │      8. Execute   │
      │                     │                    │         model     │
      │                     │                    │                    │
      │                     │ 9. Return result   │                    │
      │                     │◀───────────────────────────────────────│
      │                     │                    │                    │
      │                     │ 10. Request        │                    │
      │                     │     completion     │                    │
      │                     │───────────────────▶│                    │
      │                     │                    │                    │
      │                     │ 11. Validation     │                    │
      │                     │◀───────────────────│                    │
      │                     │                    │                    │
      │                     │ 12. Complete on    │                    │
      │                     │     blockchain     │                    │
      │                     │         │          │                    │
      │                     │         └───────────────────────────────▶ Blockchain
      │                     │                    │                    │
      │ 13. Return result   │                    │                    │
      │◀────────────────────│                    │                    │
      │                     │                    │                    │

---

Network Requirements

Bandwidth

Connection	Minimum	Recommended
Client → Gateway	10 Mbps	100 Mbps
Gateway → Compute	100 Mbps	1 Gbps
Gateway → Registry	10 Mbps	100 Mbps
Registry ↔ Registry	10 Mbps	100 Mbps

Latency

Connection	Target	Maximum
Client → Gateway	< 50ms	200ms
Gateway → Compute	< 10ms	50ms
Gateway → Registry	< 10ms	50ms
Registry ↔ Registry	< 100ms	500ms

Firewall Rules

Gateway:

# Inbound
TCP 8080 (HTTP) - Public
TCP 50051 (gRPC) - Public
TCP 9000 (WS) - Public

# Outbound
TCP 50050 (Registry) - Internal
TCP * (Compute) - Internal
TCP 8545 (Blockchain) - External

Compute:

# Inbound
None

# Outbound
TCP 50051 (Gateway) - Internal
TCP 50050 (Registry) - Internal

Registry:

# Inbound
TCP 50050 (gRPC) - Internal
TCP 8828 (P2P) - Public

# Outbound
TCP 8828 (P2P) - Public
TCP 8545 (Blockchain) - External

---

High Availability

Gateway HA

                    Load Balancer
                    ┌───────────────────┐
                    │    HAProxy/NGINX  │
                    └─────────┬─────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │Gateway 1 │   │Gateway 2 │   │Gateway 3 │
        │ (Active) │   │ (Active) │   │ (Active) │
        └──────────┘   └──────────┘   └──────────┘

Registry HA (P2P)

        ┌──────────────────────────────────────┐
        │             P2P Network              │
        │                                      │
        │   ┌──────────┐     ┌──────────┐     │
        │   │Registry 1│◀───▶│Registry 2│     │
        │   └────┬─────┘     └────┬─────┘     │
        │        │                │           │
        │        │   ┌──────────┐ │           │
        │        └──▶│Registry 3│◀┘           │
        │            └──────────┘             │
        │                                      │
        └──────────────────────────────────────┘

Compute HA

Multiple compute nodes provide redundancy:

• Tasks automatically route to available nodes

• Failed tasks retry on different nodes

• No single point of failure

---

Security Zones

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   PUBLIC ZONE (Internet exposed)                                            │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • Gateway HTTP (8080)                                               │   │
│   │  • Gateway gRPC (50051)                                              │   │
│   │  • Gateway WebSocket (9000)                                          │   │
│   │  • Registry P2P (8828)                                               │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│   DMZ (Controlled access)                                                   │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • Gateway ↔ Registry communication                                  │   │
│   │  • Gateway ↔ Compute communication                                   │   │
│   │  • Registry gRPC (50050)                                             │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│   PRIVATE ZONE (Internal only)                                              │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • Compute nodes (no exposed ports)                                  │   │
│   │  • Database connections (if any)                                     │   │
│   │  • Internal monitoring                                               │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Related Documentation

• System Overview - High-level architecture

• Security Model - Security architecture

• Deployment - Deployment options