# System Overview This document provides a comprehensive overview of the NCN Network v2 architecture, including component responsibilities, interactions, and design decisions. *** ## High-Level Architecture NCN Network v2 is a decentralized AI inference network with four main component types: ``` ┌──────────────────────────────────────────────────────────────────────────┐ │ NCN Network v2 │ │ │ │ ┌─────────────┐ │ │ │ Clients │ Submit inference requests, pay for computation │ │ └──────┬──────┘ │ │ │ HTTP/gRPC/WebSocket │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Gateway Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Gateway 1 │ │ Gateway 2 │ │ Gateway N │ ... │ │ │ │ │ (Subnet 1) │ │ (Subnet 2) │ │ (Subnet N) │ │ │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └─────────┼────────────────┼────────────────┼──────────────────────┘ │ │ │ gRPC │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Compute Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Compute 1 │ │ Compute 2 │ │ Compute M │ ... │ │ │ │ │ (GPU/CPU) │ │ (GPU/CPU) │ │ (GPU/CPU) │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Coordination Layer │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ │ │ P2P Registry Network │ │ │ │ │ │ • Node Discovery (Kademlia DHT) │ │ │ │ │ │ • Validator Consensus │ │ │ │ │ │ • Subnet Management │ │ │ │ │ │ • Mempool for pending requests │ │ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Blockchain Layer │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ │ InferencePayment│ │ValidatorRegistry│ │ │ │ │ │ Contract │ │ Contract │ │ │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ Arbitrum / Ethereum │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────┘ ``` *** ## Component Deep Dive ### Gateway Node **Purpose**: Routes inference requests between clients and compute nodes, manages payments. **Key Responsibilities**: 1. Receive client requests (gRPC, HTTP, WebSocket) 2. Reserve available compute nodes 3. Request preprocessing validation from P2P Registry 4. Verify client payments on blockchain 5. Dispatch tasks to compute nodes 6. Request completion validation 7. Trigger payment distribution 8. Return results to clients **Internal Architecture**: ``` ┌─────────────────────────────────────────────────────────────┐ │ Gateway Node │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Protocol Layer │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │ │ │ │ gRPC │ │ HTTP │ │ WebSocket │ │ │ │ │ │ Server │ │ Server │ │ Server │ │ │ │ │ └────┬────┘ └────┬────┘ └──────┬──────┘ │ │ │ └───────┼────────────┼──────────────┼───────────────────┘ │ │ │ │ │ │ │ └────────────┴──────────────┘ │ │ │ │ │ ┌────────────────────▼──────────────────────────────────┐ │ │ │ Business Logic │ │ │ │ ┌────────────────┐ ┌────────────────┐ │ │ │ │ │ Reservation │ │ Payment │ │ │ │ │ │ Manager │ │ Processor │ │ │ │ │ └────────────────┘ └────────────────┘ │ │ │ │ ┌────────────────┐ ┌────────────────┐ │ │ │ │ │ State │ │ Finalization │ │ │ │ │ │ Manager │ │ Handler │ │ │ │ │ └────────────────┘ └────────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ External Clients │ │ │ │ ┌────────────────┐ ┌────────────────┐ │ │ │ │ │ Registry │ │ Blockchain │ │ │ │ │ │ Client │ │ Client │ │ │ │ │ └────────────────┘ └────────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` **State Management**: * **Reservation Manager**: Tracks compute node reservations * **Payment Processor**: Handles payment requests and verification * **State Manager**: Persists request lifecycle state * **Finalization Handler**: Manages completion and payment distribution *** ### Compute Node **Purpose**: Executes AI models in secure sandboxed environments. **Key Responsibilities**: 1. Register with Gateway 2. Sync models from subnet 3. Receive inference tasks 4. Execute models in sandbox 5. Sign computation results 6. Return results to Gateway **Internal Architecture**: ``` ┌─────────────────────────────────────────────────────────────┐ │ Compute Node │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Gateway Connection │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Bidirectional gRPC Stream (NodeInfo ↔ Task) │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Execution Manager │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Model │ │ Executor │ │ Result │ │ │ │ │ │ Loader │ │ Selector │ │ Signer │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Sandbox Layer │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │ │ OS Sandbox │ │ │ │ │ │ • seccomp (syscall filtering) │ │ │ │ │ │ • Namespaces (PID, network, mount) │ │ │ │ │ │ • Landlock (filesystem isolation) │ │ │ │ │ │ • Resource limits (CPU, memory, time) │ │ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │ │ Python Executor │ │ │ │ │ │ • Isolated Python process │ │ │ │ │ │ • File-based I/O │ │ │ │ │ │ • Timeout monitoring │ │ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Model Storage │ │ │ │ ./models/ │ │ │ │ ├── bark_semantic_model.pt │ │ │ │ ├── bark_coarse_model.pt │ │ │ │ └── bark_fine_model.pt │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` **Sandbox Security Layers**: | Layer | Technology | Protection | | -------------------- | ----------------- | --------------------------------- | | Syscall filtering | seccomp | Blocks dangerous syscalls | | Process isolation | PID namespace | Hides other processes | | Network isolation | Network namespace | No external network | | Filesystem isolation | Landlock | Read-only access to allowed paths | | Resource limits | rlimit | CPU, memory, time bounds | *** ### P2P Registry **Purpose**: Decentralized coordination service for node discovery, validation, and subnet management. **Key Responsibilities**: 1. Node registration and heartbeat tracking 2. Model registry 3. Subnet creation and management 4. Validator pool management 5. Preprocessing validation 6. Completion validation 7. P2P coordination with other registry nodes **Internal Architecture**: ``` ┌─────────────────────────────────────────────────────────────┐ │ P2P Registry Node │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Service Layer │ │ │ │ ┌────────────────┐ ┌────────────────┐ │ │ │ │ │ gRPC Server │ │ P2P Node │ │ │ │ │ │ (Port 50050) │ │ (Port 8828) │ │ │ │ │ └────────────────┘ └────────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Business Services │ │ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ │ │ Preprocessing │ │ Completion │ │ │ │ │ │ Service │ │ Service │ │ │ │ │ └───────────────┘ └───────────────┘ │ │ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ │ │ Subnet │ │ Validator │ │ │ │ │ │ Manager │ │ Pool │ │ │ │ │ └───────────────┘ └───────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Data Layer │ │ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ │ │ Mempool │ │ DHT Storage │ │ │ │ │ │ (in-memory) │ │ (Kademlia) │ │ │ │ │ └───────────────┘ └───────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Blockchain Sync │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Validator Registry Contract Sync │ │ │ │ │ │ • Periodic sync of registered validators │ │ │ │ │ │ • Stake amount verification │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` *** ### Smart Contracts **Purpose**: On-chain payment coordination and validator registry. **Contracts**: | Contract | Address (Forknet) | Purpose | | ----------------- | -------------------------------------------- | ----------------------------- | | InferencePayment | `0x4361115359E5C0a25c9b2f8Bb71184F010b768ea` | Payment handling | | NCNToken | `0x38E2565e8905BeAf83C34b266592465C22A2f108` | ERC20 payment token | | ValidatorRegistry | (TBD) | On-chain validator management | **InferencePayment Contract Flow**: ``` ┌─────────────────────────────────────────────────────────────┐ │ InferencePayment Contract │ │ │ │ initiateInferenceRequest() │ │ ├── Verify validator signatures (M-of-N) │ │ ├── Transfer tokens from client │ │ ├── Store request data │ │ └── Emit RequestInitiated event │ │ │ │ completeInferenceRequest() │ │ ├── Verify compute node signature │ │ ├── Verify validator signatures (M-of-N) │ │ ├── Distribute payment: │ │ │ ├── compute_price → Compute Node │ │ │ ├── gateway_gas → Gateway │ │ │ ├── validator_reward → Validators │ │ │ └── treasury_fee → Treasury │ │ └── Emit PaymentDistributed event │ │ │ │ handleExpiredRequest() │ │ ├── Check expiry timestamp │ │ └── Refund client │ │ │ └─────────────────────────────────────────────────────────────┘ ``` *** ## Data Flow ### Complete Request Lifecycle ``` Time → Client Gateway P2P Registry Compute Blockchain │ │ │ │ │ │ 1. Submit │ │ │ │ │───────────────▶│ │ │ │ │ │ 2. Discover │ │ │ │ │────────────────▶│ │ │ │ │◀────────────────│ │ │ │ │ (compute nodes) │ │ │ │ │ │ │ │ │ │ 3. Reserve │ │ │ │ │──────────────────────────────────▶ │ │ │◀────────────────────────────────── │ │ │ (reservation) │ │ │ │ │ │ │ │ │ │ 4. Preprocessing│ │ │ │ │────────────────▶│ │ │ │ │◀────────────────│ │ │ │ │ (signatures) │ │ │ │ │ │ │ │ │ 5. Pay │ │ │ │ │────────────────────────────────────────────────────────────────────▶ │ │ │ │ │ │ │ 6. Confirm │ │ │ │ │◀──────────────────────────────────────────────────── │ │ │ │ │ │ │ 7. Dispatch │ │ │ │ │──────────────────────────────────▶ │ │ │ │ │ 8. Execute │ │ │ │ │──────────── │ │ │ │ │ │ │ │ │ │ │◀─────────── │ │ │ │ │ │ │ │ 9. Result │ │ │ │ │◀────────────────────────────────── │ │ │ │ │ │ │ │ 10. Completion │ │ │ │ │────────────────▶│ │ │ │ │◀────────────────│ │ │ │ │ (signatures) │ │ │ │ │ │ │ │ │ │ 11. Finalize │ │ │ │ │────────────────────────────────────────────────────▶ │ │ │ │ │ │ 12. Result │ │ │ │ │◀───────────────│ │ │ │ │ │ │ │ │ ``` *** ## Scalability Design ### Horizontal Scaling | Component | Scaling Strategy | | --------- | --------------------------------------- | | Gateway | Multiple gateways, each manages subnets | | Compute | Add more compute nodes to subnet | | Registry | P2P network, distributed state | ### Performance Targets | Metric | Target | | ----------------- | -------------------- | | Inference latency | < 5 seconds | | Throughput | 100+ requests/second | | Uptime | 99.9% | | Payment success | 100% | ### Bottleneck Mitigation | Potential Bottleneck | Mitigation | | ----------------------- | ----------------------------- | | Single gateway | Multiple gateways per subnet | | Validator consensus | Parallel signature collection | | Blockchain confirmation | Optimistic execution | | Model loading | Model caching with TTL | *** ## Fault Tolerance ### Node Failures | Failure | Recovery | | -------------- | ------------------------------------- | | Gateway crash | Client reconnects to another gateway | | Compute crash | Gateway releases reservation, retries | | Registry crash | Other registry nodes continue | ### Payment Safety | Scenario | Protection | | --------------------- | ---------------------- | | Compute failure | Expiry-based refund | | Gateway failure | On-chain expiry refund | | Validator unavailable | M-of-N allows failures | *** ## Next Steps * [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow.md) - Detailed payment mechanics * [Validation & Consensus](/nc/neurochainai-guides/architecture/validation-consensus.md) - Validator system * [Security Model](/nc/neurochainai-guides/architecture/security-model.md) - Security architecture --- # 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/system-overview.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.