# About NCN Network

<p align="center"><strong>Decentralized AI Inference Network</strong></p>

<p align="center">A decentralized network for distributed AI model inference with blockchain-based payments, validator consensus, and sandboxed execution.</p>

***

## What is NCN Network?

NCN Network v2 is a decentralized infrastructure for running AI model inference at scale. It connects **clients** who need AI inference with **compute providers** who have GPU resources, coordinated through **gateway operators** and secured by **validator consensus**.

### Key Features

* **Decentralized Inference**: Run AI models across a distributed network of compute providers
* **Blockchain Payments**: Pay-per-inference with transparent fee distribution
* **Validator Consensus**: M-of-N validator signatures ensure fair computation
* **Sandboxed Execution**: Secure model execution with OS-level isolation
* **Subnet Model Distribution**: Gateway operators create subnets with curated models
* **Multi-Protocol Support**: gRPC, HTTP REST, and WebSocket interfaces

***

## Quick Start

Get up and running in 5 minutes:

```bash
# Clone the repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs

# Build all components
cargo build --release

# Start the P2P Registry
cargo run --bin p2p_registry_node

# Start the Gateway (new terminal)
cd gateway_node && cp env.example .env
cargo run --bin gateway_node

# Start a Compute Node (new terminal)
cargo run --bin compute_node -- \
  --gateway-addr http://127.0.0.1:50051 \
  --model-path ./models

# Run the test client (new terminal)
cargo run --bin test_client
```

For detailed setup instructions, see the [Getting Started Guide](https://docs.neurochain.ai/nc/neurochainai-guides/introduction/getting-started).

***

## Architecture Overview

```
┌─────────────┐     ┌─────────────────┐     ┌───────────────┐
│   Clients   │────▶│  Gateway Nodes  │────▶│ Compute Nodes │
└─────────────┘     └────────┬────────┘     └───────────────┘
                             │
                    ┌────────▼────────┐
                    │   P2P Registry  │
                    │   (Validators)  │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   Blockchain    │
                    │   (Arbitrum)    │
                    └─────────────────┘
```

### Components

| Component           | Role                              | Documentation                                                                                 |
| ------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
| **Gateway Node**    | Routes requests, manages payments | [Gateway Docs](https://docs.neurochain.ai/nc/neurochainai-guides/components/gateway-node)     |
| **Compute Node**    | Executes AI models in sandboxes   | [Compute Docs](https://docs.neurochain.ai/nc/neurochainai-guides/components/compute-node)     |
| **P2P Registry**    | Validator network for consensus   | [Registry Docs](https://docs.neurochain.ai/nc/neurochainai-guides/components/p2p-registry)    |
| **Smart Contracts** | On-chain payment coordination     | [Contract Docs](https://docs.neurochain.ai/nc/neurochainai-guides/components/smart-contracts) |

***

## Documentation Sections

### Getting Started

* [Quick Start Guide](https://docs.neurochain.ai/nc/neurochainai-guides/introduction/getting-started) - Get running in 5 minutes
* [Key Concepts](https://docs.neurochain.ai/nc/neurochainai-guides/introduction/key-concepts) - Core terminology and concepts
* [Use Cases](https://docs.neurochain.ai/nc/neurochainai-guides/introduction/use-cases) - Real-world applications

### Architecture

* [System Overview](https://docs.neurochain.ai/nc/neurochainai-guides/architecture/system-overview) - High-level design
* [Payment Flow](https://docs.neurochain.ai/nc/neurochainai-guides/architecture/payment-flow) - Blockchain integration
* [Validation & Consensus](https://docs.neurochain.ai/nc/neurochainai-guides/architecture/validation-consensus) - Validator mechanism
* [Security Model](https://docs.neurochain.ai/nc/neurochainai-guides/architecture/security-model) - Security architecture

### Component Deep Dives

* [Gateway Node](https://docs.neurochain.ai/nc/neurochainai-guides/components/gateway-node) - Request routing and payments
* [Compute Node](https://docs.neurochain.ai/nc/neurochainai-guides/components/compute-node) - Model execution
* [P2P Registry](https://docs.neurochain.ai/nc/neurochainai-guides/components/p2p-registry) - Service discovery
* [Smart Contracts](https://docs.neurochain.ai/nc/neurochainai-guides/components/smart-contracts) - On-chain logic

### Guides

* [Development Setup](https://docs.neurochain.ai/nc/neurochainai-guides/development/development) - Local development
* [Docker Deployment](https://docs.neurochain.ai/nc/neurochainai-guides/deployment/docker) - Container deployment
* [Running a Gateway](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/gateway-operator.md) - Gateway operation
* [Running a Compute Node](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/compute-operator.md) - Compute operation

### Reference

* [API Reference](https://docs.neurochain.ai/nc/neurochainai-guides/api-reference/api-reference) - Complete API documentation
* [Configuration](https://docs.neurochain.ai/nc/neurochainai-guides/configuration/configuration) - All configuration options
* [Troubleshooting](https://docs.neurochain.ai/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues and solutions

***

## System Requirements

### Minimum Requirements

| Component    | CPU     | RAM  | Storage | Network  |
| ------------ | ------- | ---- | ------- | -------- |
| Gateway Node | 2 cores | 4 GB | 50 GB   | 100 Mbps |
| Compute Node | 4 cores | 8 GB | 100 GB  | 100 Mbps |
| P2P Registry | 2 cores | 4 GB | 50 GB   | 100 Mbps |

### Software Requirements

* **Rust**: 1.70+
* **Python**: 3.8+ (for model execution)
* **Git**: 2.0+
* **Docker**: 20.10+ (optional)

### Supported Platforms

* Linux (recommended for production)
* macOS (development)
* Windows (experimental)

***

## Network Configurations

### Testnet (Forknet)

| Setting  | Value                                        |
| -------- | -------------------------------------------- |
| RPC URL  | `https://testnet-rpc-1.forknet.io`           |
| Chain ID | 828                                          |
| Contract | `0x4361115359E5C0a25c9b2f8Bb71184F010b768ea` |
| Token    | `0x38E2565e8905BeAf83C34b266592465C22A2f108` |

### Local Development

| Service           | Default Port |
| ----------------- | ------------ |
| Gateway gRPC      | 50051        |
| Gateway HTTP      | 8080         |
| Gateway WebSocket | 9000         |
| P2P Registry gRPC | 50050        |
| P2P Registry P2P  | 8828         |

***

## Project Status

| Metric            | Value            |
| ----------------- | ---------------- |
| **Completion**    | 85%              |
| **Lines of Code** | 18,000+          |
| **Test Coverage** | 78%              |
| **Components**    | 4 services + CLI |

### Completed Features ✅

* Blockchain-based payment system
* Validator consensus mechanism
* Sandboxed model execution (seccomp, namespaces, Landlock)
* Subnet-based model distribution
* Gateway CLI for subnet management
* gRPC/HTTP/WebSocket support
* Prometheus metrics

### In Progress 🚧

* Model auto-downloader (Phase 11)
* Integration testing (Phase 12)
* Production deployment (Phase 13)

***

## Getting Help

* [**Troubleshooting Guide**](https://docs.neurochain.ai/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues and solutions
* [**FAQ**](https://docs.neurochain.ai/nc/neurochainai-guides/troubleshooting/faq) - Frequently asked questions
* [**GitHub Issues**](https://github.com/your-org/ncn-network-v2-rs/issues) - Bug reports and feature requests

***

## Contributing

We welcome contributions! See our [Contributing Guide](https://docs.neurochain.ai/nc/neurochainai-guides/contributing/contributing) for:

* [Code Style Guidelines](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/code-style.md)
* [Pull Request Process](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/pull-requests.md)
* [Documentation Guidelines](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/documentation.md)

***

## License

MIT License - see [LICENSE](https://github.com/neurochainai/ncn-network-v2-rs/blob/main/LICENSE) for details.

***

<p align="center"><strong>Built with Rust, Solidity, and Python</strong></p>