# 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](/nc/neurochainai-guides/architecture/system-overview.md) - High-level architecture * [Security Model](/nc/neurochainai-guides/architecture/security-model.md) - Security architecture * [Deployment](/nc/neurochainai-guides/deployment/deployment.md) - Deployment options --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.neurochain.ai/nc/neurochainai-guides/architecture/network-topology.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.