> For the complete documentation index, see [llms.txt](https://docs.neurochain.ai/nc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neurochain.ai/nc/neurochainai-guides/architecture/network-topology.md). # 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