# NeurochainAI Node Setup
The Node Setup of Neurochain AI is an integral aspect of its infrastructure.
WIP: V2 node set up guids will be updated with Developer alpha release
# Grant Program
Empowering the Future of AI: Introducing NeurochainAI's Grant Program
## AI Democratization Initiative (ADI)
In the rapidly evolving world of artificial intelligence, innovation often comes from unexpected places. At NeurochainAI, we believe in the power of individual developers and small startups to drive groundbreaking advancements in AI technology. That's why we're thrilled to announce our new grant program, designed to support and nurture the next generation of AI innovators.
### Who We're Looking For
Our grant program is specifically tailored for two groups:
1. **Indie AI Developers**: Solo developers or small teams working on open-source projects or innovative AI applications. These are the unsung heroes of the AI world, often pushing the boundaries of what's possible with limited resources.
2. **Small AI Startups**: Early-stage companies focused on AI applications, particularly those utilizing open-source AI language models (LLMs). These startups are the seedbeds of innovation, exploring niche markets and pioneering new approaches to AI.
### What We Offer
Selected grant recipients will receive:
* **$5,000 worth of AI inference credits**: This substantial computational boost will help you develop, test, and scale your AI projects without financial strain.
* **Access to NeurochainAI's decentralized AI infrastructure**: Leverage our robust platform to build and deploy your AI solutions efficiently.
* **Community support**: Join our thriving community of over 100,000 members, opening doors to potential customers, collaboration, networking, and valuable feedback.
### Why Apply?
Our grant program isn't just about financial support. It's about joining a movement to democratize AI and push the boundaries of what's possible. Here's why you should consider applying:
1. **Foster Innovation**: Get the resources you need to bring your cutting-edge AI ideas to life.
2. **Scale Your Project**: Use our infrastructure to take your project from concept to reality, and beyond.
3. **Join a Community**: Become part of a network of like-minded innovators and industry experts.
4. **Align with the Future**: Build on a decentralized AI platform that's shaping the future of the industry.
### Eligibility and Application Process
To be eligible, your project or business should have at least 100 users. This ensures that we're supporting initiatives with real-world traction and potential for impact.
**Fill out this form to apply:** [**https://app.youform.com/forms/x3etflwj**](https://app.youform.com/forms/x3etflwj)
Have a thriving AI business with more than 1,000 customers and are looking to optimize your inference cost? We have a solution for you as well, please fill out the same form.
### Join Us in Shaping the Future of AI
At NeurochainAI, we're committed to decentralizing AI and making advanced tools accessible to innovators worldwide. Our grant program is more than just funding – it's an invitation to be part of a revolution in AI development.
Are you ready to take your AI project to the next level? Do you have a vision for how AI can change the world? If so, we want to hear from you. Apply for our grant program today and let's build the future of AI together.
# Legal Disclaimer
Legal Disclaimer of Neurochain AI
The information contained in this Whitepaper is provided for informational purposes only and should not be construed as financial, investment, or legal advice. This document's contents are presented solely for informational purposes and do not constitute an offer to buy, sell, or invest in any securities or tokens.
Neurochain.AI is not licenced or authorised to operate as a cryptocurrency exchange or provide investment services. Therefore, we offer no recommendations or advice regarding the purchase, sale, or investment in cryptocurrencies or tokens. Users are solely responsible for their own investment decisions and should seek the counsel of licenced financial advisors or attorneys.
Investing in digital assets, including cryptocurrencies and tokens, carries a high level of risk. The value of these assets is extremely volatile and can fluctuate substantially. Prior to making any decisions, investors should carefully consider their financial situation, risk aversion, and investment goals in light of the fact that past performance is not indicative of future results.
In the event that third-party projects utilise the Neurochain.AI infrastructure, we neither endorse nor guarantee the legitimacy, accuracy, or dependability of such projects. Neurochain.AI or its affiliates cannot be held liable for the promotion, sale, or offering of securities by third-party projects utilising the Neurochain.AI infrastructure, and we disclaim any and all liability in any jurisdiction arising from such activities.
Before engaging in investment activities, it is strongly advised that you consult with a qualified financial advisor, attorney, or tax professional. This Whitepaper's content is not intended to replace professional advice or independent verification. Before making investment decisions, it is the sole responsibility of users to conduct their own research and diligence.
Neurochain.AI and its team members, advisors, partners, and affiliates disclaim all liability for any direct or indirect loss, damage, or expense incurred by individuals or organisations relying on the information contained in this whitepaper. We take no responsibility for the accuracy, dependability, or completeness of any external links or references that may appear in this document.
By accessing and reading this whitepaper, you acknowledge and consent to the terms outlined in this legal disclaimer.
# About NCN Network
Decentralized AI Inference Network
A decentralized network for distributed AI model inference with blockchain-based payments, validator consensus, and sandboxed execution.
***
## 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](/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](/nc/neurochainai-guides/components/gateway-node) |
| **Compute Node** | Executes AI models in sandboxes | [Compute Docs](/nc/neurochainai-guides/components/compute-node) |
| **P2P Registry** | Validator network for consensus | [Registry Docs](/nc/neurochainai-guides/components/p2p-registry) |
| **Smart Contracts** | On-chain payment coordination | [Contract Docs](/nc/neurochainai-guides/components/smart-contracts) |
***
## Documentation Sections
### Getting Started
* [Quick Start Guide](/nc/neurochainai-guides/introduction/getting-started) - Get running in 5 minutes
* [Key Concepts](/nc/neurochainai-guides/introduction/key-concepts) - Core terminology and concepts
* [Use Cases](/nc/neurochainai-guides/introduction/use-cases) - Real-world applications
### Architecture
* [System Overview](/nc/neurochainai-guides/architecture/system-overview) - High-level design
* [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow) - Blockchain integration
* [Validation & Consensus](/nc/neurochainai-guides/architecture/validation-consensus) - Validator mechanism
* [Security Model](/nc/neurochainai-guides/architecture/security-model) - Security architecture
### Component Deep Dives
* [Gateway Node](/nc/neurochainai-guides/components/gateway-node) - Request routing and payments
* [Compute Node](/nc/neurochainai-guides/components/compute-node) - Model execution
* [P2P Registry](/nc/neurochainai-guides/components/p2p-registry) - Service discovery
* [Smart Contracts](/nc/neurochainai-guides/components/smart-contracts) - On-chain logic
### Guides
* [Development Setup](/nc/neurochainai-guides/development/development) - Local development
* [Docker Deployment](/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](/nc/neurochainai-guides/api-reference/api-reference) - Complete API documentation
* [Configuration](/nc/neurochainai-guides/configuration/configuration) - All configuration options
* [Troubleshooting](/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**](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues and solutions
* [**FAQ**](/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](/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.
***
Built with Rust, Solidity, and Python
# Getting Started
This guide will help you get NCN Network v2 running on your local machine in about 15 minutes.
***
## Prerequisites
Before you begin, ensure you have the following installed:
### Required Software
| Software | Version | Installation |
| ---------- | ------- | ----------------------------------------------- |
| **Rust** | 1.70+ | [rustup.rs](https://rustup.rs/) |
| **Python** | 3.8+ | [python.org](https://www.python.org/downloads/) |
| **Git** | 2.0+ | [git-scm.com](https://git-scm.com/) |
### Verify Installation
```bash
# Check Rust version
rustc --version
# Expected: rustc 1.70.0 or higher
# Check Python version
python3 --version
# Expected: Python 3.8 or higher
# Check Git version
git --version
# Expected: git version 2.0 or higher
```
### Hardware Requirements
For local development:
* **CPU**: 4+ cores recommended
* **RAM**: 8 GB minimum, 16 GB recommended
* **Storage**: 10 GB free space
***
## Installation
### Step 1: Clone the Repository
```bash
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
```
### Step 2: Build All Components
```bash
# Build in release mode (recommended)
cargo build --release
# Or build in debug mode for development
cargo build
```
This will create the following binaries in `target/release/` (or `target/debug/`):
* `p2p_registry_node` - P2P Registry service
* `gateway_node` - Gateway service
* `compute_node` - Compute Node service
* `test_client` - Test client
* `subnet-cli` - Subnet management CLI
### Step 3: Set Up Python Environment (Optional)
If you want to run model inference:
```bash
cd compute_node/python_executors
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Verify installation
python verify_environment.py
```
***
## Running the Network
You'll need **4 terminal windows** to run all components:
### Terminal 1: P2P Registry
The P2P Registry is the coordination service for the network.
```bash
cd ncn-network-v2-rs
# Start P2P Registry with default settings
cargo run --release --bin p2p_registry_node
# Or with custom settings
cargo run --release --bin p2p_registry_node -- \
--p2p-listen-addr /ip4/0.0.0.0/tcp/8828 \
--grpc-listen-addr 127.0.0.1:50050
```
**Expected output:**
```
Starting P2P Registry Node...
P2P listening on /ip4/0.0.0.0/tcp/8828
gRPC server listening on 127.0.0.1:50050
✓ P2P Registry initialized successfully
```
### Terminal 2: Gateway Node
The Gateway routes inference requests and manages payments.
```bash
cd ncn-network-v2-rs/gateway_node
# Copy and configure environment
cp env.example .env
# Edit .env with your settings (optional for local dev)
# nano .env
# Start Gateway
cargo run --release --bin gateway_node
```
**Expected output:**
```
Starting Gateway Node...
gRPC server listening on 127.0.0.1:50051
HTTP server listening on 127.0.0.1:8080
WebSocket server listening on 127.0.0.1:9000
Connected to P2P Registry at http://127.0.0.1:50050
✓ Gateway Node initialized successfully
```
### Terminal 3: Compute Node
The Compute Node executes AI models.
```bash
cd ncn-network-v2-rs
# Start Compute Node
cargo run --release --bin compute_node -- \
--gateway-addr http://127.0.0.1:50051 \
--model-path ./models
```
**Expected output:**
```
Starting Compute Node...
Connecting to Gateway at http://127.0.0.1:50051
Model path: ./models
✓ Connected to Gateway
✓ Registered with Gateway
✓ Compute Node ready for tasks
```
### Terminal 4: Test Client
Run a test inference request:
```bash
cd ncn-network-v2-rs
# Run basic test
cargo run --release --bin test_client
```
**Expected output:**
```
╔════════════════════════════════════════╗
║ NCN Network Test Client ║
╚════════════════════════════════════════╝
Connecting to Gateway at http://127.0.0.1:50051...
✓ Connected to Gateway
Submitting inference request...
Task ID: abc123-def456-...
Status: queued
Waiting for result...
✓ Received result in 1.25s
Output: [inference result data]
```
***
## Quick Start with Docker
For a faster setup, use Docker Compose:
```bash
cd ncn-network-v2-rs
# Start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop all services
docker-compose down
```
This starts:
* P2P Registry on port 50050
* Gateway on ports 50051 (gRPC), 8080 (HTTP), 9000 (WebSocket)
* Compute Node connected to Gateway
See [Docker Deployment Guide](/nc/neurochainai-guides/deployment/docker) for more details.
***
## Verify Everything is Working
### Check Service Health
```bash
# Check P2P Registry
curl http://127.0.0.1:50050/health
# Expected: {"status": "healthy"}
# Check Gateway
curl http://127.0.0.1:8080/health
# Expected: {"status": "healthy"}
```
### Submit a Test Request via HTTP
```bash
curl -X POST http://127.0.0.1:8080/api/v1/inference \
-H "Content-Type: application/json" \
-d '{
"model_uuid": "test-model",
"input_data": "{\"text\": \"Hello, world!\"}"
}'
```
***
## Directory Structure
After building, your directory should look like:
```
ncn-network-v2-rs/
├── target/release/ # Compiled binaries
│ ├── gateway_node
│ ├── compute_node
│ ├── p2p_registry_node
│ ├── test_client
│ └── subnet-cli
├── gateway_node/
│ ├── .env # Your configuration
│ └── env.example # Example configuration
├── compute_node/
│ ├── models/ # AI models directory
│ └── python_executors/ # Python execution scripts
├── contracts/ # Smart contracts
├── proto/ # Protocol definitions
└── docs/ # Documentation
```
***
## What's Next?
Now that you have NCN Network running locally, explore these topics:
### Understand the System
* [Key Concepts](/nc/neurochainai-guides/introduction/key-concepts) - Learn the terminology
* [System Architecture](/nc/neurochainai-guides/architecture/system-overview) - How it all fits together
* [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow) - How payments work
### Deploy & Operate
* [Docker Deployment](/nc/neurochainai-guides/deployment/docker) - Production-ready containers
* [Gateway Operator Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/gateway-operator.md) - Run a gateway
* [Compute Operator Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/compute-operator.md) - Provide compute
### Integrate
* [gRPC Client Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/grpc-client.md) - Build a client
* [HTTP API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/http-endpoints.md) - REST API docs
* [Payment Integration](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/payment-integration.md) - Add payments
***
## Troubleshooting
### Common Issues
#### Build Fails with "linker not found"
Install build essentials:
```bash
# Ubuntu/Debian
sudo apt install build-essential
# macOS
xcode-select --install
```
#### "Connection refused" to P2P Registry
Ensure the P2P Registry is running and check the address:
```bash
# Verify P2P Registry is running
ps aux | grep p2p_registry
# Check if port is listening
netstat -tlnp | grep 50050
```
#### Compute Node fails to connect to Gateway
Verify the Gateway address matches:
```bash
# The address should match what Gateway is listening on
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051
```
For more help, see the [Troubleshooting Guide](/nc/neurochainai-guides/troubleshooting/troubleshooting).
***
## Need Help?
* [**FAQ**](/nc/neurochainai-guides/troubleshooting/faq) - Frequently asked questions
* [**Troubleshooting**](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues and solutions
* [**GitHub Issues**](https://github.com/your-org/ncn-network-v2-rs/issues) - Report bugs or request features
# Key Concepts
This page explains the core terminology and concepts used throughout NCN Network v2.
***
## Network Participants
### Client
An application or user that wants to run AI inference. Clients submit inference requests to Gateway Nodes and pay for computation using blockchain transactions.
**Responsibilities:**
* Submit inference requests
* Pay for computation
* Receive and verify results
### Gateway Node
A service operator that routes inference requests between clients and compute nodes. Gateway operators create **subnets** with specific AI models and earn fees for coordinating requests.
**Responsibilities:**
* Receive client requests
* Reserve compute nodes
* Coordinate payments
* Return results to clients
* Create and manage subnets
### Compute Node
A service provider with GPU/CPU resources that executes AI models. Compute nodes join subnets, download required models, and earn fees for performing inference.
**Responsibilities:**
* Execute AI models in sandboxed environments
* Sign computation results
* Report execution metrics
### Validator
A network participant that validates preprocessing and completion of inference requests. Validators stake tokens and earn fees for honest validation.
**Responsibilities:**
* Validate request preprocessing (payment amounts, node selection)
* Validate computation completion (result integrity)
* Sign validation attestations
* Participate in consensus
### P2P Registry
The decentralized coordination service that maintains network state, facilitates service discovery, and coordinates validator consensus.
**Responsibilities:**
* Node registration and discovery
* Model registry
* Subnet management
* Validator pool management
* Preprocessing/completion validation
***
## Core Concepts
### Subnet
A subnet is a logical grouping of AI models managed by a Gateway operator. When a Gateway creates a subnet:
1. The Gateway specifies which models are included
2. The Gateway pays a creation fee
3. Validators sign the subnet configuration
4. Compute nodes can join the subnet and download models
**Subnet Structure:**
```
Subnet #1
├── Gateway: 0xGateway...
├── Models:
│ ├── bark_semantic_model.pt
│ ├── bark_coarse_model.pt
│ └── bark_fine_model.pt
├── Status: active
└── Validators: [0xVal1, 0xVal2, 0xVal3]
```
### Payment Tree
The payment tree defines how inference fees are distributed among participants:
| Recipient | Description | Typical % |
| -------------------- | ----------------------------- | --------- |
| **Compute Price** | Payment to compute node | 80% |
| **Gateway Gas** | Gas reimbursement for gateway | 10% |
| **Validator Reward** | Split among validators | 5% |
| **Treasury Fee** | Protocol treasury | 5% |
**Example Payment Tree:**
```json
{
"compute_price_wei": "800000000000000000",
"gateway_gas_wei": "100000000000000000",
"validator_reward_wei": "50000000000000000",
"treasury_fee_wei": "50000000000000000"
}
```
### Preprocessing Validation
Before a client pays for inference, validators verify the request setup:
1. Gateway is registered and reputable
2. Compute node is available and capable
3. Payment amounts are calculated correctly
4. Request parameters are valid
Validators sign the preprocessing validation, and the client includes these signatures when paying on-chain.
### Completion Validation
After compute finishes, validators verify the result:
1. Compute node signature is valid
2. Result format is correct
3. Computation time is reasonable
4. Result hash matches actual result
Validators sign the completion validation, enabling payment distribution.
### M-of-N Consensus
NCN uses an M-of-N signature scheme for validation:
* **N** validators are selected for each request (default: 5)
* **M** signatures are required (default: 3)
* Both preprocessing and completion require M-of-N consensus
This prevents:
* Malicious validators from blocking requests
* Colluding validators from approving invalid requests
***
## Execution Model
### Sandboxed Execution
Compute nodes execute models in isolated sandboxes with multiple security layers:
```
┌─────────────────────────────────────────┐
│ Host System │
│ ┌───────────────────────────────────┐ │
│ │ Sandbox (per execution) │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ Python Executor │ │ │
│ │ │ ┌───────────────────────┐ │ │ │
│ │ │ │ AI Model │ │ │ │
│ │ │ └───────────────────────┘ │ │ │
│ │ └─────────────────────────────┘ │ │
│ │ Restrictions: │ │
│ │ • No network access │ │
│ │ • Limited filesystem │ │
│ │ • Memory/CPU limits │ │
│ │ • Time limits │ │
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
**Security Layers:**
1. **seccomp** - System call filtering
2. **Linux namespaces** - Process isolation (PID, network, mount)
3. **Landlock** - Filesystem access control
4. **Resource limits** - CPU, memory, time bounds
### Model Types
NCN supports various model types:
| Type | Extension | Framework | Description |
| ------------ | -------------- | ------------ | ------------------------- |
| TorchScript | `.pt`, `.pth` | PyTorch | Serialized PyTorch models |
| ONNX | `.onnx` | ONNX Runtime | Cross-platform models |
| Safetensors | `.safetensors` | Multiple | Safe tensor storage |
| Hugging Face | - | Transformers | Auto-download from HF Hub |
### Executor Scripts
Python executor scripts handle model loading and inference:
```
compute_node/python_executors/
├── generic_model_executor.py # General-purpose executor
├── semantic_model_executor.py # Bark semantic model
├── coarse_model_executor.py # Bark coarse model
├── requirements.txt # Python dependencies
└── verify_environment.py # Environment verification
```
***
## Payment Flow
### Request Lifecycle
```
1. CLIENT submits request to GATEWAY
↓
2. GATEWAY reserves COMPUTE NODE
↓
3. VALIDATORS sign preprocessing (M-of-N)
↓
4. CLIENT pays on blockchain
↓
5. GATEWAY confirms payment
↓
6. COMPUTE NODE executes model
↓
7. COMPUTE NODE signs result
↓
8. VALIDATORS sign completion (M-of-N)
↓
9. Smart contract distributes payment
↓
10. CLIENT receives result
```
### Request States
| State | Description |
| -------------------- | ------------------------------------------ |
| `Received` | Request received by gateway |
| `AwaitingPayment` | Compute node reserved, waiting for payment |
| `PaymentConfirmed` | Payment verified on blockchain |
| `Computing` | Model execution in progress |
| `AwaitingValidation` | Compute complete, waiting for validators |
| `Finalizing` | Validators confirmed, distributing payment |
| `Completed` | Successfully finished |
| `Failed` | Request failed (may include refund) |
### Smart Contract
The `InferencePayment` contract handles:
1. **Initiation**: Client deposits payment with validator signatures
2. **Completion**: Gateway calls completion with compute signature + validator signatures
3. **Distribution**: Contract sends funds to compute node, gateway, validators, treasury
4. **Expiry**: Automatic refund if request isn't completed in time
5. **Disputes**: Admin can mark requests as failed for refunds
***
## Network Protocol
### Communication Channels
| Channel | Protocol | Purpose |
| ------------------- | --------------------- | --------------------------- |
| Gateway ↔ Client | gRPC, HTTP, WebSocket | Request submission, results |
| Gateway ↔ Compute | gRPC (streaming) | Task assignment, responses |
| Gateway ↔ Registry | gRPC | Node discovery, validation |
| Compute ↔ Registry | gRPC | Registration, model sync |
| Registry ↔ Registry | libp2p | P2P coordination |
### Protocol Buffers
All services communicate using Protocol Buffers. Key message types:
```protobuf
// Inference request from client
message InferenceRequest {
string request_id = 1;
string model_uuid = 2;
string input_data = 3;
PreprocessingValidation preprocessing_validation = 5;
TransactionConfirmation transaction_confirmation = 6;
}
// Response with result and attestations
message InferenceResponse {
string request_id = 1;
string output_data = 2;
ComputeLog compute_log = 3;
string response_signature = 5;
CompletionValidation completion_validation = 7;
}
```
***
## Cryptographic Primitives
### Signing
NCN uses **secp256k1 ECDSA** signatures (Ethereum-compatible):
* **Compute nodes** sign computation results
* **Validators** sign preprocessing and completion validations
* **Gateways** sign subnet creation requests
* **Clients** sign blockchain transactions
### Hashing
**SHA-256** is used for:
* Result integrity (result hash)
* Configuration integrity (config hash)
* Executor script verification (executor hash)
### Address Format
All addresses use **Ethereum-style** hex addresses:
```
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
```
***
## Glossary
| Term | Definition |
| ------------ | ------------------------------------------------------------- |
| **DHT** | Distributed Hash Table - Used for P2P node discovery |
| **gRPC** | Google Remote Procedure Call - Primary communication protocol |
| **Kademlia** | DHT protocol used by libp2p for peer discovery |
| **libp2p** | Modular network stack used for P2P communication |
| **Mempool** | In-memory storage for pending requests/validations |
| **seccomp** | Linux kernel feature for system call filtering |
| **Landlock** | Linux security module for filesystem access control |
| **Wei** | Smallest unit of Ether (1 ETH = 10^18 Wei) |
| **ABI** | Application Binary Interface - Smart contract encoding |
| **RPC** | Remote Procedure Call |
***
## Next Steps
* [System Architecture](/nc/neurochainai-guides/architecture/system-overview) - Detailed architecture
* [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow) - Payment deep dive
* [Getting Started](/nc/neurochainai-guides/introduction/getting-started) - Run your first request
# Use Cases
NCN Network v2 enables various decentralized AI applications. This page covers common use cases and implementation patterns.
***
## AI Inference as a Service
### Overview
Deploy AI models and offer inference as a pay-per-use service.
```
┌──────────┐ ┌──────────────┐ ┌───────────────┐
│ Client │────▶│ Gateway │────▶│ Compute Node │
│ (App) │ │ (Your Org) │ │ (GPU Farm) │
└──────────┘ └──────────────┘ └───────────────┘
│ │
└───────────── Payment ─────────────────┘
```
### Benefits
* **No infrastructure management**: Use existing compute providers
* **Pay only for usage**: No idle GPU costs
* **Scalable**: Add more compute nodes as demand grows
* **Transparent pricing**: On-chain payment records
### Implementation
1. **Gateway Operator**: Create a subnet with your models
2. **Compute Providers**: Join your subnet, provide GPU resources
3. **Clients**: Send inference requests, pay per request
### Example: Image Classification Service
```python
# Client code
import requests
response = requests.post(
"https://your-gateway.com/api/v1/inference",
json={
"model_uuid": "resnet50",
"input_data": {"image_url": "https://example.com/image.jpg"}
},
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
result = response.json()
print(f"Classification: {result['output_data']}")
```
***
## Decentralized Model Hosting
### Overview
Host AI models in a decentralized network where multiple compute providers can serve requests.
### Architecture
```
┌────────────────┐
│ Subnet │
│ (Model Set) │
└───────┬────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
│ Compute 1 │ │ Compute 2 │ │ Compute 3 │
│ (Provider A) │ │ (Provider B) │ │ (Provider C) │
└───────────────┘ └───────────────┘ └───────────────┘
```
### Benefits
* **Redundancy**: Multiple providers serve requests
* **Geographic distribution**: Low latency worldwide
* **Censorship resistance**: No single point of control
* **Competition**: Providers compete on price and quality
### Setup
1. **Create Subnet**:
```bash
subnet-cli create -c model_config.json
```
2. **Providers Join**:
```bash
compute_node --subnet-id 1 --sync-models
```
3. **Clients Connect**:
```bash
# Requests automatically routed to available providers
```
***
## Text-to-Audio Pipeline (Bark)
### Overview
NCN Network supports the Bark text-to-audio model with distributed pipeline execution.
### Pipeline Stages
```
Input Text → Semantic → Coarse → Fine → Audio Output
Stage Stage Stage
```
### Implementation
The Bark pipeline uses three specialized models:
| Stage | Model | Purpose |
| -------- | ------------------------ | ---------------------------------- |
| Semantic | `bark_semantic_model.pt` | Text to semantic tokens |
| Coarse | `bark_coarse_model.pt` | Semantic to coarse acoustic tokens |
| Fine | `bark_fine_model.pt` | Coarse to fine acoustic tokens |
### Subnet Configuration
```json
{
"gateway_address": "0xYourGateway",
"models": [
{
"name": "bark_semantic",
"download_url": "https://huggingface.co/suno/bark/resolve/main/...",
"executor_script": "semantic_model_executor.py"
},
{
"name": "bark_coarse",
"download_url": "https://huggingface.co/suno/bark/resolve/main/...",
"executor_script": "coarse_model_executor.py"
},
{
"name": "bark_fine",
"download_url": "https://huggingface.co/suno/bark/resolve/main/...",
"executor_script": "fine_model_executor.py"
}
]
}
```
### Client Usage
```python
# Run Bark pipeline
text = "Hello, this is a test of the NCN Network text-to-speech system."
# Stage 1: Semantic
semantic_tokens = client.inference("bark_semantic", {"text": text})
# Stage 2: Coarse
coarse_tokens = client.inference("bark_coarse", {"semantic_tokens": semantic_tokens})
# Stage 3: Fine
audio_data = client.inference("bark_fine", {"coarse_tokens": coarse_tokens})
# Save audio
with open("output.wav", "wb") as f:
f.write(audio_data)
```
***
## Custom Model Deployment
### Overview
Deploy your own trained models on the NCN Network.
### Requirements
1. **Model Format**: TorchScript (`.pt`), ONNX (`.onnx`), or Safetensors
2. **Executor Script**: Python script for inference
3. **Input/Output Schema**: JSON format definition
### Step-by-Step
#### 1. Export Your Model
```python
import torch
# Your trained model
model = MyModel()
model.load_state_dict(torch.load("model_weights.pth"))
model.eval()
# Export to TorchScript
scripted = torch.jit.script(model)
scripted.save("my_model.pt")
```
#### 2. Create Executor Script
```python
# my_model_executor.py
import os
import json
import torch
def main():
# Load input
input_file = os.environ.get("INPUT_FILE")
with open(input_file) as f:
input_data = json.load(f)
# Load model
model = torch.jit.load("my_model.pt")
# Run inference
input_tensor = torch.tensor(input_data["input"])
output = model(input_tensor)
# Write output
output_file = os.environ.get("OUTPUT_FILE")
with open(output_file, "w") as f:
json.dump({"output": output.tolist()}, f)
if __name__ == "__main__":
main()
```
#### 3. Configure Subnet
```json
{
"models": [
{
"name": "my_model",
"download_url": "https://your-storage.com/my_model.pt",
"executor_script": "base64_encoded_executor_script",
"file_size_bytes": 500000000
}
]
}
```
#### 4. Deploy
```bash
subnet-cli create -c my_model_config.json
```
***
## Batch Processing
### Overview
Process large batches of inference requests efficiently.
### Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Batch Job │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Request │ │ Request │ │ Request │ │ Request │ ...│
│ │ 1 │ │ 2 │ │ 3 │ │ N │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
└───────┼────────────┼────────────┼────────────┼──────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────────────────────────────────────────────┐
│ Load Balancer │
│ (Gateway Distribution) │
└───────────────────────────────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│Compute1│ │Compute2│ │Compute3│ │Compute4│
└────────┘ └────────┘ └────────┘ └────────┘
```
### Implementation
```python
import asyncio
from ncn_client import NCNClient
async def process_batch(items):
client = NCNClient("https://gateway.example.com")
# Submit all requests concurrently
tasks = [
client.inference_async("model_name", item)
for item in items
]
# Wait for all results
results = await asyncio.gather(*tasks)
return results
# Process 1000 items
batch = load_batch_data()
results = asyncio.run(process_batch(batch))
```
***
## Real-Time Applications
### Overview
Build real-time AI applications with WebSocket streaming.
### WebSocket Connection
```javascript
const ws = new WebSocket("wss://gateway.example.com/ws");
ws.onopen = () => {
// Subscribe to task updates
ws.send(JSON.stringify({
type: "subscribe",
request_id: "my-request-123"
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === "task_status") {
console.log(`Status: ${data.status}`);
} else if (data.type === "task_result") {
console.log(`Result: ${data.output_data}`);
}
};
```
### Use Cases
* Live transcription
* Real-time translation
* Interactive chatbots
* Voice assistants
***
## Next Steps
* [Getting Started](/nc/neurochainai-guides/introduction/getting-started) - Set up your environment
* [Key Concepts](/nc/neurochainai-guides/introduction/key-concepts) - Understand the system
* [Client Integration](/nc/neurochainai-guides/clients/clients) - Build your client
# Overview
This section provides detailed documentation of NCN Network v2's architecture, from high-level system design to specific implementation details.
***
## Architecture Documentation
### [System Overview](/nc/neurochainai-guides/architecture/system-overview)
High-level system design including:
* Component responsibilities
* Data flow patterns
* Design principles
* Scalability considerations
### [Network Topology](/nc/neurochainai-guides/architecture/network-topology)
Network communication patterns:
* P2P network structure (Kademlia DHT)
* Service discovery mechanisms
* gRPC communication channels
* Multi-protocol client interfaces
### [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow)
Blockchain payment integration:
* End-to-end payment sequence
* Fee calculation and distribution
* Smart contract interactions
* Transaction confirmation
### [Validation & Consensus](/nc/neurochainai-guides/architecture/validation-consensus)
Validator consensus mechanism:
* Preprocessing validation
* Completion validation
* M-of-N signature scheme
* Validator reputation and slashing
### [Security Model](/nc/neurochainai-guides/architecture/security-model)
Security architecture:
* Threat model
* Sandboxed execution
* Cryptographic signing
* Access control
***
## Quick Reference
### System Diagram
```
┌──────────────────────────────────────────────────────────────────┐
│ NCN Network v2 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────────────┐ ┌────────────────────┐ │
│ │ Clients │────▶│ Gateway Nodes │────▶│ Compute Nodes │ │
│ │ (HTTP/ │ │ (Rust service) │ │ (Rust + Python) │ │
│ │ gRPC/ │ │ │ │ │ │
│ │ WS) │◀────│ • Routing │◀────│ • Model Execution │ │
│ └─────────┘ │ • Payments │ │ • Sandboxing │ │
│ │ • Reservations │ │ • Signing │ │
│ └────────┬────────┘ └────────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ P2P Registry │ │
│ │ (Rust + libp2p) │
│ │ │ │
│ │ • Discovery │ │
│ │ • Validation │ │
│ │ • Subnets │ │
│ │ • Consensus │ │
│ └────────┬────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Blockchain │ │
│ │ (Arbitrum) │ │
│ │ │ │
│ │ • Payments │ │
│ │ • Validators │ │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
```
### Component Summary
| Component | Technology | Primary Role | Key Interfaces |
| --------------- | ------------------ | ------------------------- | --------------------- |
| Gateway Node | Rust, Tokio, Tonic | Request routing, payments | gRPC, HTTP, WebSocket |
| Compute Node | Rust, Python | Model execution | gRPC (to Gateway) |
| P2P Registry | Rust, libp2p | Coordination, validation | gRPC, P2P |
| Smart Contracts | Solidity, Foundry | Payment handling | Ethereum ABI |
### Communication Protocols
| Protocol | Use Case | Port (Default) |
| --------- | ------------------ | -------------- |
| gRPC | Service-to-service | 50050, 50051 |
| HTTP REST | Client requests | 8080 |
| WebSocket | Real-time updates | 9000 |
| libp2p | P2P coordination | 8828 |
| JSON-RPC | Blockchain | External |
### Data Flow Overview
```
1. Request Submission
Client → HTTP/gRPC → Gateway → gRPC → P2P Registry
↓
2. Preprocessing Validation
P2P Registry selects validators → M-of-N signatures
↓
3. Payment
Client → Blockchain (smart contract) → Gateway confirms
↓
4. Execution
Gateway → gRPC stream → Compute Node → Sandbox → Model
↓
5. Completion Validation
Compute signs → P2P Registry → M-of-N validator signatures
↓
6. Payment Distribution
Gateway → Smart Contract → Funds distributed
↓
7. Result Delivery
Gateway → HTTP/gRPC/WS → Client
```
***
## Design Principles
### 1. Decentralization
* No single point of failure
* P2P coordination via DHT
* Multiple gateway and compute nodes
### 2. Security First
* Sandboxed model execution
* Cryptographic attestations
* Payment verification
### 3. Scalability
* Horizontal scaling of compute nodes
* Async I/O with Tokio
* Efficient binary protocols (protobuf)
### 4. Transparency
* On-chain payment records
* Validator signatures
* Execution logs
### 5. Operator Economics
* Gateway operators earn routing fees
* Compute operators earn execution fees
* Validators earn consensus fees
***
## Technology Stack
### Backend Services
| Layer | Technology | Purpose |
| ------------- | ---------- | -------------------- |
| Runtime | Tokio | Async runtime |
| RPC | Tonic | gRPC framework |
| Web | Axum | HTTP server |
| P2P | libp2p | P2P networking |
| Crypto | ethers-rs | Ethereum integration |
| Serialization | Protobuf | Binary encoding |
### Smart Contracts
| Technology | Purpose |
| ------------ | --------------------- |
| Solidity | Contract language |
| Foundry | Development framework |
| OpenZeppelin | Security libraries |
### Model Execution
| Technology | Purpose |
| ---------- | -------------------- |
| Python | Executor runtime |
| PyTorch | ML framework |
| seccomp | Syscall filtering |
| Landlock | Filesystem isolation |
***
## Next Steps
Dive deeper into specific architecture topics:
1. [**System Overview**](/nc/neurochainai-guides/architecture/system-overview) - Complete system design
2. [**Payment Flow**](/nc/neurochainai-guides/architecture/payment-flow) - Payment mechanics
3. [**Security Model**](/nc/neurochainai-guides/architecture/security-model) - Security architecture
# 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) - Detailed payment mechanics
* [Validation & Consensus](/nc/neurochainai-guides/architecture/validation-consensus) - Validator system
* [Security Model](/nc/neurochainai-guides/architecture/security-model) - Security architecture
# Payment Flow
This document details the blockchain-based payment system in NCN Network v2, including fee calculation, transaction flow, and smart contract interactions.
***
## Overview
NCN Network uses an **escrow-based payment model** where clients deposit funds before computation, and payments are distributed after validated completion.
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Payment Flow Overview │
│ │
│ 1. Request 2. Validate 3. Pay 4. Compute │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Client │──────▶│Validators│─────▶│Blockchain│─────▶│ Compute │ │
│ │ │ │ (M-of-N) │ │ (Escrow) │ │ Node │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
│ 8. Result 7. Validate 6. Complete 5. Sign │ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────▼──┐ │
│ │ Client │◀──────│Validators│◀─────│Blockchain│◀─────│ Result │ │
│ │ │ │ (M-of-N) │ │(Distribute)│ │ │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Payment Tree
Every inference request has an associated **Payment Tree** that defines how funds are distributed:
### Structure
```protobuf
message PaymentTree {
string compute_price_wei = 1; // Payment to compute node
string gateway_gas_wei = 2; // Gas reimbursement for gateway
string validator_reward_wei = 3; // Split among validators
string treasury_fee_wei = 4; // Protocol treasury
}
```
### Distribution Breakdown
| Recipient | Purpose | Typical % |
| ---------------- | ------------------------------ | --------- |
| **Compute Node** | Payment for model execution | 80% |
| **Gateway** | Gas costs and routing fee | 10% |
| **Validators** | Consensus participation reward | 5% |
| **Treasury** | Protocol development fund | 5% |
### Example Payment Tree
For a 1 ETH total payment:
```json
{
"compute_price_wei": "800000000000000000", // 0.8 ETH
"gateway_gas_wei": "100000000000000000", // 0.1 ETH
"validator_reward_wei": "50000000000000000", // 0.05 ETH
"treasury_fee_wei": "50000000000000000" // 0.05 ETH
}
```
***
## Fee Calculation
### Compute Price
The compute price is calculated based on:
```
compute_price = base_price + (token_count × price_per_token) + (execution_time × time_rate)
```
| Factor | Description | Example |
| ----------------- | ----------------------- | ----------- |
| `base_price` | Minimum fee per request | 0.001 ETH |
| `token_count` | Input/output tokens | 1000 tokens |
| `price_per_token` | Per-token rate | 0.0001 ETH |
| `execution_time` | Estimated compute time | 5 seconds |
| `time_rate` | Per-second rate | 0.001 ETH/s |
### Gateway Gas
```
gateway_gas = estimated_gas × gas_price × gas_multiplier
```
Covers:
* Transaction submission
* Event monitoring
* Result relay
### Validator Reward
```
validator_reward = compute_price × validator_rate
validator_per_validator = validator_reward / num_validators
```
Split equally among participating validators.
### Treasury Fee
```
treasury_fee = total_payment × treasury_rate
```
Fixed percentage (default: 5%) for protocol development.
***
## Payment Lifecycle
### Phase 1: Fee Estimation
Before payment, clients can estimate fees:
```
Client Gateway Registry
│ │ │
│ 1. EstimateFee │ │
│─────────────────────────▶│ │
│ │ 2. EstimateSubnetFee │
│ │─────────────────────────▶│
│ │ │
│ │ 3. Fee + Quote ID │
│ │◀─────────────────────────│
│ 4. Estimated Fee │ │
│◀─────────────────────────│ │
```
**Response includes:**
* `fee_wei` - Total estimated fee
* `fee_quote_id` - Valid for 10 minutes
* `config_hash` - Anti-tampering hash
* `expires_at` - Quote expiration
### Phase 2: Preprocessing Validation
Validators verify request setup:
```
Gateway Registry Validators
│ │ │
│ 1. RequestPreprocessing │ │
│─────────────────────────▶│ │
│ │ 2. Select N validators │
│ │─────────────────────────▶│
│ │ │
│ │ 3. Validate & Sign │
│ │◀─────────────────────────│
│ │ (M-of-N signatures) │
│ 4. PreprocessingValidation│ │
│◀─────────────────────────│ │
```
**Validators verify:**
* Gateway is registered and reputable
* Compute node is available and capable
* Payment amounts are correctly calculated
* Request parameters are valid
### Phase 3: Payment Initiation
Client pays on blockchain:
```
Client Blockchain Gateway
│ │ │
│ 1. Approve token spend │ │
│─────────────────────────▶│ │
│ │ │
│ 2. initiateInferenceRequest() │
│─────────────────────────▶│ │
│ (amount, signatures) │ │
│ │ 3. RequestInitiated │
│ │ (event) │
│ │──────────────────────▶│
│ 4. tx_hash │ │
│◀─────────────────────────│ │
│ │ │
│ 5. Confirm payment │ │
│───────────────────────────────────────────────────▶│
```
**Smart contract verifies:**
* M-of-N validator signatures
* Correct payment amount
* Request not expired
* Token allowance sufficient
### Phase 4: Execution
After payment confirmation, compute proceeds:
```
Gateway Compute Registry
│ │ │
│ 1. Dispatch task │ │
│─────────────────────────▶│ │
│ (with payment info) │ │
│ │ 2. Verify payment │
│ │ 3. Execute model │
│ │ 4. Sign result │
│ 5. InferenceResponse │ │
│◀─────────────────────────│ │
│ (signed result) │ │
```
### Phase 5: Completion Validation
Validators verify computation:
```
Gateway Registry Validators
│ │ │
│ 1. RequestCompletion │ │
│─────────────────────────▶│ │
│ (signed result) │ │
│ │ 2. Select N validators │
│ │─────────────────────────▶│
│ │ │
│ │ 3. Validate & Sign │
│ │◀─────────────────────────│
│ │ (M-of-N signatures) │
│ 4. CompletionValidation │ │
│◀─────────────────────────│ │
```
**Validators verify:**
* Compute node signature is valid
* Result format is correct
* Computation time is reasonable
* Result hash matches
### Phase 6: Payment Distribution
Gateway finalizes on blockchain:
```
Gateway Blockchain Recipients
│ │ │
│ 1. completeInferenceRequest() │
│─────────────────────────▶│ │
│ (completion signatures)│ │
│ │ │
│ │ 2. Verify signatures │
│ │ 3. Transfer to compute │
│ │─────────────────────────▶│
│ │ 4. Transfer to gateway │
│ │─────────────────────────▶│
│ │ 5. Transfer to validators│
│ │─────────────────────────▶│
│ │ 6. Transfer to treasury │
│ │─────────────────────────▶│
│ │ │
│ │ 7. PaymentDistributed │
│ 8. tx_hash │ (event) │
│◀─────────────────────────│ │
```
***
## Smart Contract Interface
### InferencePayment Contract
#### `initiateInferenceRequest`
```solidity
function initiateInferenceRequest(
bytes32 requestId,
address gateway,
address computeNode,
uint256 computePrice,
uint256 gatewayGas,
uint256 validatorReward,
uint256 treasuryFee,
uint256 expiry,
bytes[] calldata validatorSignatures
) external;
```
**Requirements:**
* Caller has approved token spend
* M-of-N validator signatures valid
* Expiry timestamp in future
* Request ID not already used
#### `completeInferenceRequest`
```solidity
function completeInferenceRequest(
bytes32 requestId,
bytes calldata computeSignature,
bytes32 resultHash,
bytes[] calldata validatorSignatures
) external;
```
**Requirements:**
* Request exists and is pending
* Compute node signature valid
* M-of-N validator signatures valid
* Called by original gateway
#### `handleExpiredRequest`
```solidity
function handleExpiredRequest(bytes32 requestId) external;
```
**Behavior:**
* If request expired, refund to original payer
* Anyone can call (gas incentive)
### Events
```solidity
event RequestInitiated(
bytes32 indexed requestId,
address indexed client,
address indexed gateway,
uint256 totalAmount
);
event PaymentDistributed(
bytes32 indexed requestId,
address computeNode,
uint256 computePayment,
address gateway,
uint256 gatewayPayment
);
event RequestRefunded(
bytes32 indexed requestId,
address indexed client,
uint256 amount
);
```
***
## Failure Handling
### Compute Failure
If computation fails:
1. Gateway calls `markRequestFailed` (admin function)
2. Or request expires after timeout
3. Client receives automatic refund
```
┌─────────────────────────────────────────────────────────┐
│ Failure Recovery │
│ │
│ Compute fails → Gateway notifies → Expiry triggers │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Log failure Mark failed (admin) Auto-refund │
│ │
└─────────────────────────────────────────────────────────┘
```
### Validator Rejection
If validators reject completion:
1. Gateway cannot call `completeInferenceRequest`
2. Request expires
3. Client refunded automatically
### Transaction Failure
If blockchain transaction fails:
1. Gateway retries with exponential backoff
2. After max retries, request marked failed
3. Client refunded if funds escrowed
***
## Security Considerations
### Double-Spend Prevention
* Request IDs are unique (UUID v4)
* Each request ID can only be initiated once
* Completion only possible for initiated requests
### Signature Verification
* All signatures verified on-chain
* ECDSA signatures with secp256k1
* Validators must be registered in contract
### Expiry Protection
* Preprocessing validations expire (10 min)
* Payment requests expire (configurable, default 1 hour)
* Automatic refund after expiry
### Reentrancy Protection
* `ReentrancyGuard` on all payment functions
* Checks-Effects-Interactions pattern
* No external calls before state updates
***
## Token Flow Diagram
```
InferencePayment Contract
┌────────────────────────────┐
│ │
Client │ Escrow Balance │
┌──────┐ deposit │ ┌────────────────┐ │
│ NCN │─────────────▶│ │ Request Pool │ │
│Tokens│ │ │ │ │
└──────┘ │ │ req1: 1 ETH │ │
│ │ req2: 0.5 ETH │ │
│ │ ... │ │
│ └───────┬────────┘ │
│ │ │
│ on completion │
│ │ │
│ ┌───────▼────────┐ │
│ │ Distribution │ │
│ └───────┬────────┘ │
│ │ │
└────────────┼──────────────┘
│
┌────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Compute │ │ Gateway │ │Validators│
│ 0.8 ETH │ │ 0.1 ETH │ │ 0.05 ETH │
└──────────┘ └──────────┘ └──────────┘
│
▼
┌──────────┐
│ Treasury │
│ 0.05 ETH │
└──────────┘
```
***
## Configuration
### Gateway Payment Settings
```bash
# Contract configuration
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
RPC_URL=http://127.0.0.1:8545
# Transaction settings
GAS_LIMIT=500000
GAS_PRICE_MULTIPLIER=1.1
REQUIRED_CONFIRMATIONS=1
CONFIRMATION_TIMEOUT_SECS=300
```
### Pricing Configuration
```bash
# Base pricing
BASE_COMPUTE_PRICE_WEI=1000000000000000 # 0.001 ETH
PRICE_PER_TOKEN_WEI=100000000000 # 0.0001 ETH
# Fee rates
GATEWAY_FEE_RATE=0.10 # 10%
VALIDATOR_FEE_RATE=0.05 # 5%
TREASURY_FEE_RATE=0.05 # 5%
```
***
## Monitoring
### Key Metrics
| Metric | Description |
| ------------------------------ | ------------------------ |
| `payments_initiated_total` | Total payments initiated |
| `payments_completed_total` | Successfully distributed |
| `payments_refunded_total` | Refunded payments |
| `payment_amount_wei_total` | Total wei processed |
| `payment_distribution_time_ms` | Time to distribute |
### Events to Monitor
```javascript
// Listen for payment events
contract.on("RequestInitiated", (requestId, client, gateway, amount) => {
console.log(`Payment initiated: ${requestId} for ${amount} wei`);
});
contract.on("PaymentDistributed", (requestId, compute, computeAmount) => {
console.log(`Payment distributed: ${requestId}`);
});
```
***
## Next Steps
* [Validation & Consensus](/nc/neurochainai-guides/architecture/validation-consensus) - Validator mechanism
* [Smart Contracts](/nc/neurochainai-guides/components/smart-contracts) - Contract details
* [Security Model](/nc/neurochainai-guides/architecture/security-model) - Security architecture
# Validation & Consensus
This document describes the validator consensus mechanism in NCN Network v2, including preprocessing validation, completion validation, and the M-of-N signature scheme.
***
## Overview
Validators provide decentralized verification of inference requests and results, ensuring:
1. **Fair Pricing**: Payment amounts are correctly calculated
2. **Node Selection**: Compute nodes are capable and available
3. **Result Integrity**: Computation results are valid
4. **Payment Security**: Funds are distributed correctly
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Validator Consensus Flow │
│ │
│ Request Preprocessing Completion │
│ ┌─────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Gateway │───────────▶│ Validator │──────────▶│ Validator │ │
│ │ │ │ Consensus │ │ Consensus │ │
│ └─────────┘ │ (M-of-N) │ │ (M-of-N) │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Payment │ │ Payment │ │
│ │ Initiation │ │Distribution │ │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## M-of-N Signature Scheme
### Configuration
| Parameter | Default | Description |
| ---------- | ------- | ------------------------------------- |
| **N** | 5 | Total validators selected per request |
| **M** | 3 | Minimum signatures required |
| **Quorum** | 60% | M/N ratio |
### Why M-of-N?
* **Fault Tolerance**: Network continues if some validators offline
* **Byzantine Resistance**: Requires majority for malicious action
* **Availability**: Doesn't wait for slow validators
* **Decentralization**: No single point of failure
### Signature Aggregation
```
Selected Validators (N=5)
┌───┬───┬───┬───┬───┐
│ V1│ V2│ V3│ V4│ V5│
└─┬─┴─┬─┴─┬─┴─┬─┴─┬─┘
│ │ │ │ │
Sign request │ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌───┬───┬───┬───┬───┐
│ ✓ │ ✓ │ ✗ │ ✓ │ ✗ │ (3 of 5 = valid)
└───┴───┴───┴───┴───┘
│
▼
┌───────────────────┐
│ Aggregated Sigs │
│ [sig1, sig2, sig4]│
└───────────────────┘
```
***
## Validator Pool
### ValidatorInfo Structure
```rust
pub struct ValidatorInfo {
pub wallet_address: String,
pub stake_amount: u128,
pub validations_count: u64,
pub successful_validations: u64,
pub failed_validations: u64,
pub reputation_score: u32, // 0-100
pub is_active: bool,
pub slash_count: u32,
pub last_validation_timestamp: i64,
}
```
### Validator Registration
```
Blockchain P2P Registry
│ │
Stake tokens │ │
────────────────────▶ │
│ │
Register validator │ │
────────────────────────────────────────────────────▶
│ │
│ Sync validators │
│◀────────────────────────────│
│ (periodic) │
```
### Selection Strategies
| Strategy | Description | Use Case |
| --------------- | --------------------------- | ----------------- |
| **Random** | Uniform random selection | Default |
| **Reputation** | Highest reputation first | Quality priority |
| **Stake** | Highest stake first | Economic security |
| **Performance** | Best success rate | Reliability |
| **Weighted** | Stake + reputation weighted | Balanced |
### Selection Algorithm
```rust
fn select_validators(&self, count: usize, strategy: SelectionStrategy) -> Vec {
let active_validators: Vec<_> = self.validators
.values()
.filter(|v| v.is_active && v.reputation_score >= MIN_REPUTATION)
.collect();
match strategy {
SelectionStrategy::Random => {
active_validators.choose_multiple(&mut rng, count).collect()
}
SelectionStrategy::Reputation => {
active_validators
.sorted_by(|a, b| b.reputation_score.cmp(&a.reputation_score))
.take(count)
.collect()
}
SelectionStrategy::WeightedRandom => {
// Weight by stake * reputation
weighted_sample(active_validators, count, |v| {
v.stake_amount * v.reputation_score as u128
})
}
}
}
```
***
## Preprocessing Validation
### Purpose
Verify request setup before client payment:
* Gateway legitimacy
* Compute node availability
* Payment calculation correctness
* Request parameter validity
### Process
```
Gateway P2P Registry Validators
│ │ │
│ 1. RequestPreprocessing │ │
│───────────────────────────▶│ │
│ │ │
│ │ 2. Verify gateway │
│ │ - Registered? │
│ │ - Reputation >= min? │
│ │ │
│ │ 3. Verify compute node │
│ │ - Registered? │
│ │ - Available? │
│ │ - Supports model? │
│ │ │
│ │ 4. Calculate payment │
│ │ - Compute price │
│ │ - Gateway gas │
│ │ - Validator reward │
│ │ │
│ │ 5. Select N validators │
│ │───────────────────────────▶│
│ │ │
│ │ 6. Request signatures │
│ │───────────────────────────▶│
│ │ │
│ │ │ 7. Validate
│ │ │ & Sign
│ │ │
│ │ 8. Collect M signatures │
│ │◀───────────────────────────│
│ │ │
│ 9. PreprocessingValidation │ │
│◀───────────────────────────│ │
```
### Validation Message
Validators sign a deterministic message:
```
message = SHA256(
request_id ||
gateway_wallet ||
compute_node_id ||
compute_node_wallet ||
payment_tree_hash ||
expiry_timestamp
)
```
### PreprocessingValidation Structure
```protobuf
message PreprocessingValidation {
string request_id = 1;
string gateway_wallet = 2;
string compute_node_id = 3;
string compute_node_wallet = 4;
PaymentTree payment_tree = 5;
repeated ValidatorSignature validator_signatures = 6;
int64 expiry_timestamp = 7;
}
```
***
## Completion Validation
### Purpose
Verify computation results after execution:
* Compute node signature validity
* Result format correctness
* Computation time reasonableness
* Result integrity
### Process
```
Gateway P2P Registry Validators
│ │ │
│ 1. RequestCompletion │ │
│───────────────────────────▶│ │
│ (InferenceResponse) │ │
│ │ │
│ │ 2. Verify request exists│
│ │ - In mempool? │
│ │ - Not completed? │
│ │ │
│ │ 3. Verify compute sig │
│ │ - Valid signature? │
│ │ - Correct signer? │
│ │ │
│ │ 4. Verify result │
│ │ - Format valid? │
│ │ - Hash matches? │
│ │ - Time reasonable? │
│ │ │
│ │ 5. Select N validators │
│ │───────────────────────────▶│
│ │ │
│ │ 6. Request signatures │
│ │───────────────────────────▶│
│ │ │
│ │ │ 7. Validate
│ │ │ & Sign
│ │ │
│ │ 8. Collect M signatures │
│ │◀───────────────────────────│
│ │ │
│ 9. CompletionValidation │ │
│◀───────────────────────────│ │
```
### Completion Message
Validators sign:
```
message = SHA256(
request_id ||
compute_node_signature ||
result_hash ||
completion_timestamp ||
computation_time_ms
)
```
### CompletionValidation Structure
```protobuf
message CompletionValidation {
string request_id = 1;
repeated ValidatorSignature validator_signatures = 2;
ComputeCompletion compute_completion = 3;
}
message ComputeCompletion {
string request_id = 1;
string compute_node_signature = 2;
bytes result_hash = 3;
int64 completion_timestamp = 4;
uint64 computation_time_ms = 5;
}
```
***
## Reputation System
### Reputation Score
Each validator has a reputation score (0-100):
```
reputation = base_reputation + performance_bonus - slash_penalty
```
| Factor | Impact |
| ------------------------ | ---------- |
| Successful validation | +1 point |
| Failed validation | -2 points |
| Timeout (no response) | -5 points |
| Slashing event | -20 points |
| Minimum stake maintained | Required |
### Reputation Updates
```rust
fn update_reputation(&mut self, validator: &str, approved: bool) {
if let Some(v) = self.validators.get_mut(validator) {
if approved {
v.successful_validations += 1;
v.reputation_score = min(100, v.reputation_score + 1);
} else {
v.failed_validations += 1;
v.reputation_score = max(0, v.reputation_score.saturating_sub(2));
}
v.validations_count += 1;
v.last_validation_timestamp = current_time();
}
}
```
### Minimum Reputation
Validators below minimum reputation (default: 20) are:
* Excluded from selection
* Must stake more or wait for recovery
* Can appeal through governance
***
## Slashing Conditions
### Slashable Offenses
| Offense | Severity | Penalty |
| ------------------------------- | -------- | ---------- |
| **Invalid signature** | High | 50% stake |
| **Colluding with compute node** | Critical | 100% stake |
| **Approving invalid result** | High | 30% stake |
| **Prolonged downtime** | Medium | 10% stake |
| **Front-running requests** | High | 50% stake |
### Slashing Process
```
Detection Verification Execution
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Monitor │─────────▶│ Committee │─────────▶│ Contract │
│ detects │ │ reviews │ │ slashes │
│ violation │ │ evidence │ │ stake │
└─────────────┘ └─────────────┘ └─────────────┘
```
### Slash Implementation
```rust
fn slash_validator(&mut self, address: &str, reason: &str) -> bool {
if let Some(v) = self.validators.get_mut(address) {
v.slash_count += 1;
v.reputation_score = max(0, v.reputation_score.saturating_sub(20));
if v.slash_count >= MAX_SLASHES {
v.is_active = false;
}
log::warn!("Slashed validator {}: {}", address, reason);
true
} else {
false
}
}
```
***
## Validator Rotation
### Purpose
Prevent validator centralization and ensure fairness.
### Rotation Schedule
```rust
fn rotate_validators(&mut self) {
// Deactivate low-reputation validators
for v in self.validators.values_mut() {
if v.reputation_score < MIN_REPUTATION_THRESHOLD {
v.is_active = false;
}
}
// Reactivate validators with recovered reputation
for v in self.validators.values_mut() {
if !v.is_active && v.reputation_score >= REACTIVATION_THRESHOLD {
v.is_active = true;
}
}
}
```
### Rotation Frequency
| Event | Trigger |
| ------------------- | --------------------- |
| Hourly rotation | Time-based |
| Reputation check | After each validation |
| Stake change | On-chain event |
| Manual intervention | Governance action |
***
## Mempool
### Purpose
Temporary storage for pending validations:
```
┌─────────────────────────────────────────────────────────┐
│ Mempool │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Pending Requests │ │
│ │ req1: { request, timestamp, status } │ │
│ │ req2: { request, timestamp, status } │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Preprocessing Validations │ │
│ │ req1: { validation, signatures[], timestamp } │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Completion Validations │ │
│ │ req1: { completion, signatures[], timestamp } │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### TTL (Time-to-Live)
| Entry Type | Default TTL | Purpose |
| --------------- | ----------- | ------------------- |
| Pending Request | 10 min | Await preprocessing |
| Preprocessing | 15 min | Await payment |
| Completion | 5 min | Await finalization |
### Cleanup
```rust
fn cleanup_expired(&mut self) -> CleanupStats {
let now = current_timestamp();
// Remove expired entries
self.pending_requests.retain(|_, e| !e.is_expired(now, PENDING_TTL));
self.preprocessing_validations.retain(|_, e| !e.is_expired(now, PREPROC_TTL));
self.completion_validations.retain(|_, e| !e.is_expired(now, COMPLETION_TTL));
}
```
***
## Configuration
### Validator Settings
```bash
# Validator identity
VALIDATOR_PRIVATE_KEY=0x...
VALIDATOR_ADDRESS=0x...
# Pool settings
MIN_VALIDATORS_FOR_CONSENSUS=3
MAX_VALIDATORS_TO_SELECT=5
MIN_REPUTATION_THRESHOLD=20
# Timing
VALIDATION_TIMEOUT_SECS=30
SIGNATURE_COLLECTION_TIMEOUT_MS=5000
```
### Sync Settings
```bash
# Blockchain sync
VALIDATOR_SYNC_ENABLED=true
VALIDATOR_SYNC_INTERVAL=60
VALIDATOR_REGISTRY_CONTRACT=0x...
```
***
## Monitoring
### Key Metrics
| Metric | Description |
| --------------------------------- | --------------------------- |
| `validators_active` | Currently active validators |
| `validators_total` | Total registered validators |
| `validations_preprocessing_total` | Preprocessing validations |
| `validations_completion_total` | Completion validations |
| `consensus_reached_total` | Successful consensus |
| `consensus_failed_total` | Failed consensus |
| `average_reputation` | Mean reputation score |
### Health Checks
```bash
# Check validator pool status
curl http://registry:50050/health
# Response
{
"status": "healthy",
"validators": {
"active": 10,
"total": 15,
"average_reputation": 85
},
"mempool": {
"pending_requests": 5,
"preprocessing": 3,
"completion": 1
}
}
```
***
## Next Steps
* [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow) - Payment mechanics
* [Security Model](/nc/neurochainai-guides/architecture/security-model) - Security architecture
* [P2P Registry](/nc/neurochainai-guides/components/p2p-registry) - Registry implementation
# Security Model
This document describes the security architecture of NCN Network v2, including threat modeling, security mechanisms, and trust assumptions.
***
## Security Overview
NCN Network employs a **defense-in-depth** strategy with multiple security layers:
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Security Architecture │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 5: Economic Security │ │
│ │ • Validator staking and slashing │ │
│ │ • Escrow-based payments │ │
│ │ • Economic incentives for honest behavior │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 4: Cryptographic Security │ │
│ │ • secp256k1 ECDSA signatures │ │
│ │ • SHA-256 hashing │ │
│ │ • Signature verification on-chain │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 3: Consensus Security │ │
│ │ • M-of-N validator signatures │ │
│ │ • Distributed validation │ │
│ │ • Byzantine fault tolerance │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 2: Execution Security │ │
│ │ • Sandboxed model execution │ │
│ │ • System call filtering (seccomp) │ │
│ │ • Process isolation (namespaces) │ │
│ │ • Filesystem isolation (Landlock) │ │
│ │ • Resource limits │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 1: Network Security │ │
│ │ • TLS encryption │ │
│ │ • Rate limiting │ │
│ │ • Authentication │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Threat Model
### Assets
| Asset | Criticality | Primary Threats |
| ------------------------- | ----------- | ------------------- |
| **User Funds** | Critical | Theft, double-spend |
| **Private Keys** | Critical | Exposure, theft |
| **Computation Integrity** | High | Manipulation, fraud |
| **Model Data** | High | Theft, tampering |
| **Service Availability** | Medium | DoS attacks |
### Threat Actors
| Actor | Capability | Motivation |
| ----------------------- | ----------------- | -------------------------- |
| **Malicious Model** | Code execution | Data theft, resource abuse |
| **Rogue Compute Node** | Access to data | Payment fraud |
| **Rogue Validator** | Signing authority | Approve invalid results |
| **External Attacker** | Network access | Service disruption, theft |
| **Colluding Operators** | Multiple roles | Payment manipulation |
### Attack Surface
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Attack Surface │
│ │
│ External Internal Blockchain │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ API Abuse │ │ Sandbox │ │ Contract │ │
│ │ DDoS │ │ Escape │ │ Exploits │ │
│ │ MITM │ │ Resource │ │ Front-run │ │
│ │ Auth Bypass │ │ Exhaustion │ │ Reentrancy │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Trust Assumptions
### What We Trust
| Assumption | Justification |
| ---------------------------- | ------------------------------------------------- |
| **Blockchain consensus** | Ethereum security model |
| **Cryptographic primitives** | Standard algorithms (secp256k1, SHA-256) |
| **Linux kernel** | Seccomp, namespaces, Landlock are kernel features |
| **Majority of validators** | M-of-N consensus (Byzantine fault tolerant) |
### What We Don't Trust
| Entity | Mitigation |
| ------------------------ | ---------------------- |
| **Any single validator** | M-of-N consensus |
| **Model code** | Sandbox isolation |
| **Compute nodes** | Signature verification |
| **Network** | TLS encryption |
| **Client input** | Input validation |
***
## Sandbox Security
### Isolation Mechanisms
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Sandbox Isolation │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ seccomp Filter │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Allowed: read, write, mmap, brk, exit, futex, ... │ │ │
│ │ │ Blocked: socket, connect, fork, execve (except Python), ... │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Namespace Isolation │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ PID NS │ │ Network NS │ │ Mount NS │ │ IPC NS │ │ │
│ │ │ (isolated) │ │ (no access) │ │ (private) │ │ (isolated) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Landlock Filesystem Rules │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ /tmp → Read/Write │ │ │
│ │ │ /models → Read only │ │ │
│ │ │ /python/lib → Read only │ │ │
│ │ │ Everything else → Denied │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Resource Limits (rlimit) │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ CPU: X seconds│ │ Memory: Y MB │ │ Files: Z │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Attack Prevention
| Attack | Protection | Mechanism |
| -------------- | ----------------- | ---------------------- |
| Network access | Network namespace | No network interfaces |
| File theft | Landlock | Restricted file access |
| Fork bomb | RLIMIT\_NPROC | Process limit |
| Memory bomb | RLIMIT\_AS | Memory limit |
| CPU exhaustion | RLIMIT\_CPU | CPU time limit |
| Syscall escape | seccomp | Syscall whitelist |
***
## Cryptographic Security
### Signature Scheme
**Algorithm**: secp256k1 ECDSA (Ethereum-compatible)
```
Message → SHA-256 Hash → ECDSA Sign → Signature
│
▼
0x{r}{s}{v} (65 bytes)
```
### Signed Data
| Data | Signer | Purpose |
| ------------------------ | ------------ | ---------------------- |
| Preprocessing validation | Validators | Authorize payment |
| Compute result | Compute node | Attest to computation |
| Completion validation | Validators | Authorize distribution |
| Subnet creation | Gateway | Authorize subnet |
### Verification Flow
```rust
// On-chain verification
function verifySignatures(
bytes32 messageHash,
bytes[] signatures,
address[] validators
) {
for (uint i = 0; i < signatures.length; i++) {
address recovered = ECDSA.recover(messageHash, signatures[i]);
require(isValidator(recovered), "Invalid validator");
}
}
```
***
## Economic Security
### Validator Staking
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Economic Incentives │
│ │
│ Honest Behavior Malicious Behavior │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ + Validation rewards│ │ - Stake slashing │ │
│ │ + Reputation gain │ │ - Reputation loss │ │
│ │ + More selections │ │ - Fewer selections │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
│ Cost of Attack: │
│ • Control M validators × minimum stake │
│ • Risk of detection and slashing │
│ • Reputation loss affects future earnings │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Slashing Conditions
| Offense | Penalty | Detection |
| ---------------------- | ---------- | --------------------- |
| Invalid signature | 50% stake | On-chain verification |
| Approve invalid result | 30% stake | Challenge period |
| Collusion | 100% stake | Governance action |
| Prolonged downtime | 10% stake | Heartbeat monitoring |
### Escrow Protection
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Payment Escrow │
│ │
│ Client Contract Recipients │
│ │ │ │ │
│ │ 1. Deposit │ │ │
│ │───────────────────────▶│ │ │
│ │ │ (Funds locked) │ │
│ │ │ │ │
│ │ │ 2a. Completion │ │
│ │ │ (valid signatures) │ │
│ │ │───────────────────────────▶│ │
│ │ │ │ │
│ │ │ 2b. Expiry │ │
│ │◀───────────────────────│ (auto-refund) │ │
│ │ │ │ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Network Security
### TLS Configuration (Recommended)
```yaml
# Gateway TLS
tls:
cert_file: /etc/ncn/certs/gateway.crt
key_file: /etc/ncn/certs/gateway.key
client_ca: /etc/ncn/certs/ca.crt
min_version: TLS1.3
```
### Rate Limiting
| Endpoint | Limit | Window |
| -------------- | -------------- | -------- |
| HTTP Inference | 100 | 1 minute |
| gRPC Submit | 1000 | 1 minute |
| WebSocket | 10 connections | Per IP |
### Network Isolation
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Network Zones │
│ │
│ Public Zone DMZ Private Zone │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Clients │────▶│ Gateway │───────▶│ Compute │ │
│ │ Internet │ │ (HTTP/ │ │ Nodes │ │
│ │ │ │ gRPC) │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ Registry │◀──────────────┘ │
│ │ (P2P) │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Security Recommendations
### Production Checklist
* [ ] **TLS everywhere**: All connections encrypted
* [ ] **Key management**: Use HSM or secure key storage
* [ ] **Rate limiting**: Enable on all public endpoints
* [ ] **Firewall**: Restrict unnecessary ports
* [ ] **Monitoring**: Set up security alerting
* [ ] **Updates**: Keep dependencies current
* [ ] **Audit**: External security audit before mainnet
### Key Management
| Environment | Recommendation |
| ----------- | --------------------- |
| Development | Environment variables |
| Staging | Secrets manager |
| Production | HSM / Hardware wallet |
### Incident Response
1. **Detection**: Monitor for anomalies
2. **Containment**: Pause affected services
3. **Investigation**: Collect logs and evidence
4. **Remediation**: Fix vulnerability
5. **Recovery**: Restore services
6. **Post-mortem**: Document and improve
***
## Related Documentation
* [Sandbox Security](https://github.com/NeuroChainAi/docs-guides/blob/main/security/sandbox-security.md) - Sandbox details
* [Cryptographic Signing](https://github.com/NeuroChainAi/docs-guides/blob/main/security/cryptographic-signing.md) - Signature verification
* [Payment Security](https://github.com/NeuroChainAi/docs-guides/blob/main/security/payment-security.md) - Payment protection
* [Best Practices](https://github.com/NeuroChainAi/docs-guides/blob/main/security/best-practices.md) - Security recommendations
# 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) - High-level architecture
* [Security Model](/nc/neurochainai-guides/architecture/security-model) - Security architecture
* [Deployment](/nc/neurochainai-guides/deployment/deployment) - Deployment options
# Overview
NCN Network v2 consists of five main components that work together to provide decentralized AI inference.
***
## Component Architecture
```
┌──────────────────────────────────────────────────────────────────────────┐
│ NCN Network v2 │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ User Layer │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ Test Client │ │ │
│ │ │ Example application for testing the network │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Gateway Layer │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ Gateway Node │ │ │
│ │ │ • Routes inference requests │ │ │
│ │ │ • Manages compute reservations │ │ │
│ │ │ • Processes payments │ │ │
│ │ │ • Subnet CLI for management │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Compute Layer │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ Compute Node │ │ │
│ │ │ • Executes AI models │ │ │
│ │ │ • Sandboxed Python execution │ │ │
│ │ │ • Signs computation results │ │ │
│ │ │ • Model caching and management │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Coordination Layer │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ P2P Registry │ │ │
│ │ │ • Node discovery │ │ │
│ │ │ • Validator consensus │ │ │
│ │ │ • Subnet management │ │ │
│ │ │ • DHT-based storage │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Blockchain Layer │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ Smart Contracts │ │ │
│ │ │ • InferencePayment (payment handling) │ │ │
│ │ │ • NCNToken (ERC20 payment token) │ │ │
│ │ │ • ValidatorRegistry (on-chain validators) │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
```
***
## Component Summary
| Component | Purpose | Technology | Documentation |
| --------------------------------------------------------------------- | -------------------------- | ------------------ | --------------------------------------------------------------- |
| [Gateway Node](/nc/neurochainai-guides/components/gateway-node) | Request routing & payments | Rust, Tokio, Tonic | [Details →](/nc/neurochainai-guides/components/gateway-node) |
| [Compute Node](/nc/neurochainai-guides/components/compute-node) | Model execution | Rust, Python | [Details →](/nc/neurochainai-guides/components/compute-node) |
| [P2P Registry](/nc/neurochainai-guides/components/p2p-registry) | Coordination & consensus | Rust, libp2p | [Details →](/nc/neurochainai-guides/components/p2p-registry) |
| [Smart Contracts](/nc/neurochainai-guides/components/smart-contracts) | On-chain payments | Solidity | [Details →](/nc/neurochainai-guides/components/smart-contracts) |
| [Test Client](/nc/neurochainai-guides/components/test-client) | Testing & examples | Rust | [Details →](/nc/neurochainai-guides/components/test-client) |
***
## Communication Protocols
| Source | Destination | Protocol | Port |
| -------- | ----------- | ------------- | -------- |
| Client | Gateway | gRPC | 50051 |
| Client | Gateway | HTTP REST | 8080 |
| Client | Gateway | WebSocket | 9000 |
| Gateway | Compute | gRPC (stream) | 50051 |
| Gateway | Registry | gRPC | 50050 |
| Compute | Registry | gRPC | 50050 |
| Registry | Registry | libp2p | 8828 |
| All | Blockchain | JSON-RPC | External |
***
## Data Flow
### Inference Request Flow
```
1. Client → Gateway (HTTP/gRPC)
Request with model_uuid and input_data
2. Gateway → Registry (gRPC)
Discover available compute nodes
3. Gateway internal
Reserve compute node
4. Gateway → Registry (gRPC)
Request preprocessing validation
5. Client → Blockchain (JSON-RPC)
Submit payment transaction
6. Gateway → Compute (gRPC stream)
Dispatch inference task
7. Compute internal
Execute model in sandbox
8. Compute → Gateway (gRPC stream)
Return signed result
9. Gateway → Registry (gRPC)
Request completion validation
10. Gateway → Blockchain (JSON-RPC)
Finalize payment distribution
11. Gateway → Client (HTTP/gRPC/WS)
Return inference result
```
***
## Build Instructions
### Build All Components
```bash
# Clone repository
git clone https://github.com/your-org/ncn-network-v2-rs.git
cd ncn-network-v2-rs
# Build all components in release mode
cargo build --release
# Binaries available at:
# - target/release/gateway_node
# - target/release/compute_node
# - target/release/p2p_registry_node
# - target/release/test_client
# - target/release/subnet-cli
```
### Build Individual Components
```bash
# Gateway Node
cargo build --release -p gateway_node
# Compute Node
cargo build --release -p compute_node
# P2P Registry
cargo build --release -p p2p_registry_node
# Test Client
cargo build --release -p test_client
```
### Build Smart Contracts
```bash
cd contracts
# Install Foundry (if needed)
curl -L https://foundry.paradigm.xyz | bash
foundryup
# Build contracts
forge build
# Run tests
forge test -vvv
```
***
## Dependencies
### Rust Crates (Workspace)
```toml
# Core async runtime
tokio = { version = "1", features = ["full"] }
# gRPC framework
tonic = "0.14.2"
prost = "0.14.1"
# P2P networking
libp2p = "0.56.0"
# Ethereum integration
ethers = { version = "2.0", features = ["legacy"] }
# CLI
clap = { version = "4.4", features = ["derive", "env"] }
# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
```
### Python Dependencies
```
# Model execution
torch>=2.1.0
transformers>=4.35.0
# Numerical computing
numpy>=1.24.3
scipy>=1.11.3
# Audio processing
soundfile>=0.12.1
librosa>=0.10.1
```
### Smart Contract Dependencies
```
# OpenZeppelin contracts
openzeppelin-contracts = "5.0.0"
# Foundry forge-std
forge-std = "1.8.0"
```
***
## Configuration Quick Reference
| Component | Config File | Key Settings |
| --------- | ------------------- | ------------------------------------------------------ |
| Gateway | `gateway_node/.env` | `GATEWAY_PRIVATE_KEY`, `RPC_URL`, `REGISTRY_GRPC_ADDR` |
| Compute | Environment vars | `GATEWAY_ADDR`, `MODEL_PATH`, `SANDBOX_MODE` |
| Registry | Command line | `--p2p-listen-addr`, `--grpc-listen-addr` |
| Contracts | `contracts/.env` | `PRIVATE_KEY`, `RPC_URL` |
See [Configuration Guide](/nc/neurochainai-guides/configuration/configuration) for complete details.
***
## Quick Start
### 1. Start P2P Registry
```bash
cargo run --release --bin p2p_registry_node
```
### 2. Start Gateway
```bash
cd gateway_node
cp env.example .env
# Edit .env as needed
cargo run --release --bin gateway_node
```
### 3. Start Compute Node
```bash
cargo run --release --bin compute_node -- \
--gateway-addr http://127.0.0.1:50051 \
--model-path ./models
```
### 4. Run Test Client
```bash
cargo run --release --bin test_client
```
***
## Next Steps
Explore each component in detail:
* [Gateway Node](/nc/neurochainai-guides/components/gateway-node) - Request routing and payment processing
* [Compute Node](/nc/neurochainai-guides/components/compute-node) - Model execution and sandboxing
* [P2P Registry](/nc/neurochainai-guides/components/p2p-registry) - Coordination and consensus
* [Smart Contracts](/nc/neurochainai-guides/components/smart-contracts) - On-chain payment logic
* [Test Client](/nc/neurochainai-guides/components/test-client) - Testing and integration examples
# Gateway Node
The Gateway Node is the primary entry point for clients into the NCN Network. It routes inference requests, manages compute node reservations, and handles payment processing.
***
## Overview
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Gateway Node │
│ │
│ External Interfaces Internal Services │
│ ┌─────────────┐ ┌────────────────────┐ │
│ │ gRPC │◀──────────────────────│ Reservation Manager│ │
│ │ (50051) │ └────────────────────┘ │
│ └─────────────┘ │
│ ┌─────────────┐ ┌────────────────────┐ │
│ │ HTTP │◀──────────────────────│ Payment Processor │ │
│ │ (8080) │ └────────────────────┘ │
│ └─────────────┘ │
│ ┌─────────────┐ ┌────────────────────┐ │
│ │ WebSocket │◀──────────────────────│ State Manager │ │
│ │ (9000) │ └────────────────────┘ │
│ └─────────────┘ │
│ ┌────────────────────┐ │
│ Outbound Connections │ Finalizer │ │
│ ┌─────────────┐ └────────────────────┘ │
│ │ Registry │────▶ P2P Registry (50050) │
│ │ Client │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Blockchain │────▶ Ethereum RPC │
│ │ Client │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Compute │◀───▶ Compute Nodes (bidirectional stream) │
│ │ Stream │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
***
## Features
* **Multi-Protocol Support**: gRPC, HTTP REST, and WebSocket interfaces
* **Compute Node Management**: Reservation system for task assignment
* **Payment Processing**: Blockchain payment verification and finalization
* **State Persistence**: Crash recovery with persistent state
* **Subnet Management**: CLI tool for creating and managing subnets
* **Metrics**: Prometheus-compatible metrics endpoint
***
## Quick Start
### Build
```bash
cd gateway_node
cargo build --release
```
### Configure
```bash
# Copy example configuration
cp env.example .env
# Edit configuration (minimum required)
nano .env
```
**Minimum Configuration**:
```bash
# Wallet (generate with: cast wallet new)
GATEWAY_WALLET_PRIVATE_KEY=0x...
# Blockchain
RPC_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
# Network
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050
```
### Run
```bash
cargo run --release --bin gateway_node
```
**Expected Output**:
```
Starting Gateway Node...
Loading configuration from environment...
✓ Wallet loaded: 0x742d35Cc...
✓ Connected to P2P Registry at http://127.0.0.1:50050
gRPC server listening on 127.0.0.1:50051
HTTP server listening on 127.0.0.1:8080
WebSocket server listening on 127.0.0.1:9000
✓ Gateway Node initialized successfully
```
***
## Architecture
### Internal Modules
| Module | File | Purpose |
| ------------------- | --------------------- | --------------------------------------- |
| gRPC Server | `src/grpc.rs` | Compute node and client gRPC interfaces |
| HTTP Server | `src/http.rs` | REST API for clients |
| WebSocket Server | `src/ws.rs` | Real-time updates |
| Reservation Manager | `src/reservation.rs` | Compute node reservations |
| Payment Processor | `src/payment.rs` | Payment handling |
| State Manager | `src/state.rs` | Request lifecycle state |
| Finalization | `src/finalization.rs` | Completion handling |
| Registry Client | `src/registry.rs` | P2P Registry communication |
| Contract Client | `src/contract.rs` | Blockchain interactions |
### Request Flow
```
Client Request
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Receive Request (gRPC/HTTP/WS) │
│ └── Parse InferenceRequest │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Reserve Compute Node │
│ ├── Query Registry for available nodes │
│ └── Reserve best matching node │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Request Preprocessing Validation │
│ ├── Send to P2P Registry │
│ └── Collect M-of-N validator signatures │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Wait for Payment │
│ ├── Return payment info to client │
│ └── Monitor blockchain for transaction │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 5. Dispatch Task │
│ ├── Send to reserved compute node │
│ └── Mark reservation as computing │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 6. Receive Result │
│ ├── Verify compute node signature │
│ └── Request completion validation │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 7. Finalize Payment │
│ ├── Call smart contract │
│ └── Distribute funds │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 8. Return Result │
│ └── Send InferenceResponse to client │
└─────────────────────────────────────────────────────────────┘
```
***
## API Interfaces
### gRPC API
**Service**: `GatewayClientService`
| RPC | Request | Response | Description |
| ------------------------ | ------------------ | -------------------------- | ------------------------ |
| `SubmitInferenceTask` | `InferenceRequest` | `InferenceTaskStatus` | Submit inference request |
| `SubscribeToTaskUpdates` | `RequestID` | `stream InferenceResponse` | Subscribe to results |
**Service**: `GatewayComputeService`
| RPC | Request | Response | Description |
| -------------------- | ------------------- | ------------------------- | --------------------- |
| `ConnectComputeNode` | `stream NodeInfo` | `stream InferenceRequest` | Bidirectional stream |
| `SendResponse` | `InferenceResponse` | `Ack` | Send completed result |
| `SyncModels` | `SyncModelsRequest` | `SyncModelsResponse` | Sync subnet models |
See [gRPC API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/grpc-api.md) for details.
### HTTP API
| Endpoint | Method | Description |
| ------------------------ | ------ | ------------------------ |
| `/api/v1/inference` | POST | Submit inference request |
| `/api/v1/inference/{id}` | GET | Get inference status |
| `/api/v1/health` | GET | Health check |
| `/api/v1/metrics` | GET | Prometheus metrics |
See [HTTP API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/http-api.md) for details.
### WebSocket API
| Event | Direction | Description |
| ------------- | --------------- | ------------------ |
| `task_status` | Server → Client | Task status update |
| `task_result` | Server → Client | Inference result |
| `error` | Server → Client | Error notification |
See [WebSocket API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/websocket-api.md) for details.
***
## Configuration
### Environment Variables
| Variable | Required | Default | Description |
| ---------------------------- | -------- | ----------------- | -------------------------- |
| `GATEWAY_WALLET_PRIVATE_KEY` | Yes | - | Gateway wallet private key |
| `GATEWAY_WALLET_ADDRESS` | No | Derived | Gateway wallet address |
| `RPC_URL` | Yes | - | Blockchain RPC endpoint |
| `CONTRACT_ADDRESS` | Yes | - | InferencePayment contract |
| `REGISTRY_GRPC_ADDR` | Yes | - | P2P Registry address |
| `GRPC_ADDR` | No | `127.0.0.1:50051` | gRPC listen address |
| `HTTP_ADDR` | No | `127.0.0.1:8080` | HTTP listen address |
| `WS_ADDR` | No | `127.0.0.1:9000` | WebSocket listen address |
| `SUBNET_ID` | No | `1` | Gateway's subnet ID |
| `GAS_LIMIT` | No | `500000` | Default gas limit |
| `REQUIRED_CONFIRMATIONS` | No | `1` | Required tx confirmations |
See [Configuration Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/configuration.md) for complete details.
***
## Subnet CLI
The Gateway includes a CLI tool for subnet management:
```bash
# Generate subnet configuration template
subnet-cli template -o my_subnet.json
# Validate configuration
subnet-cli validate -c my_subnet.json
# Estimate creation fee
subnet-cli estimate -c my_subnet.json
# Create subnet (with payment)
export GATEWAY_PRIVATE_KEY="0x..."
subnet-cli create -c my_subnet.json --yes
# List subnets
subnet-cli list
# Get subnet details
subnet-cli get -s 1
```
See [Subnet CLI Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/subnet-cli.md) for complete documentation.
***
## State Management
The Gateway persists state to handle restarts and crashes:
### Persisted Data
* Request lifecycle state
* Payment confirmations
* Compute completions
* Reservation status
### State File
```json
{
"requests": {
"req-123": {
"status": "Computing",
"created_at": 1704067200,
"payment_tx": "0x...",
"reserved_node": "0xCompute..."
}
}
}
```
### Recovery
On startup, the Gateway:
1. Loads persisted state
2. Resumes pending requests
3. Re-establishes compute node connections
4. Continues payment monitoring
***
## Metrics
Prometheus metrics available at `/api/v1/metrics`:
| Metric | Type | Description |
| --------------------------------- | ------- | ------------------------- |
| `gateway_requests_total` | Counter | Total requests received |
| `gateway_requests_active` | Gauge | Currently active requests |
| `gateway_requests_completed` | Counter | Completed requests |
| `gateway_requests_failed` | Counter | Failed requests |
| `gateway_payment_total_wei` | Counter | Total payments processed |
| `gateway_compute_nodes_connected` | Gauge | Connected compute nodes |
| `gateway_reservations_active` | Gauge | Active reservations |
***
## Troubleshooting
### Common Issues
**"Failed to connect to Registry"**
```
Error: Failed to connect to P2P Registry at http://127.0.0.1:50050
```
* Verify P2P Registry is running
* Check `REGISTRY_GRPC_ADDR` configuration
**"No compute nodes available"**
```
Error: No nodes support model semantic.pt
```
* Verify compute nodes are connected and idle
* Check if model is in compute node's supported models
**"Payment verification failed"**
```
Error: Transaction not found or not confirmed
```
* Check blockchain connection (`RPC_URL`)
* Verify transaction has enough confirmations
See [Gateway Troubleshooting](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/gateway-issues.md) for more help.
***
## Related Documentation
* [Architecture](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/architecture.md) - Internal architecture details
* [gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/grpc-api.md) - gRPC API reference
* [HTTP API](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/http-api.md) - HTTP API reference
* [WebSocket API](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/websocket-api.md) - WebSocket API reference
* [Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/configuration.md) - Configuration options
* [Subnet CLI](https://github.com/NeuroChainAi/docs-guides/blob/main/components/gateway-node/subnet-cli.md) - Subnet management CLI
# Compute Node
The Compute Node executes AI models in secure sandboxed environments. It connects to Gateway Nodes, receives inference tasks, and returns signed results.
***
## Overview
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Compute Node │
│ │
│ Gateway Connection │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Bidirectional gRPC Stream │ │
│ │ ◀── Receive InferenceRequest │ │
│ │ ──▶ Send NodeInfo (heartbeat) │ │
│ │ ──▶ Send InferenceResponse │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Execution Manager │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ Model Loader │ │ Executor │ │ Result Signer │ │ │
│ │ │ & Cache │ │ Selector │ │ │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Sandbox Layer │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ OS Sandbox │ │ │
│ │ │ • seccomp (syscall filtering) │ │ │
│ │ │ • Linux namespaces (PID, network, mount, IPC) │ │ │
│ │ │ • Landlock (filesystem isolation) │ │ │
│ │ │ • Resource limits (CPU, memory, time) │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ Python Executor │ │ │
│ │ │ • Isolated Python process │ │ │
│ │ │ • File-based I/O │ │ │
│ │ │ • Timeout enforcement │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Model Storage │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ ./models/ │ │
│ │ ├── bark_semantic_model.pt │ │
│ │ ├── bark_coarse_model.pt │ │
│ │ └── bark_fine_model.pt │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
***
## Features
* **Sandboxed Execution**: Multi-layer security isolation for model execution
* **Python Executor**: Runs PyTorch and Transformers models
* **Cryptographic Signing**: Signs all computation results
* **Model Caching**: Efficient model loading with TTL-based cache
* **Model Sync**: Auto-download models from subnets
* **Resource Limits**: CPU, memory, and time bounds
***
## Quick Start
### Build
```bash
cd ncn-network-v2-rs
cargo build --release -p compute_node
```
### Run
```bash
cargo run --release --bin compute_node -- \
--gateway-addr http://127.0.0.1:50051 \
--model-path ./models
```
**Expected Output**:
```
Starting Compute Node...
Loading wallet from environment...
✓ Wallet initialized: 0x742d35Cc...
Connecting to Gateway at http://127.0.0.1:50051...
✓ Connected to Gateway
✓ Registered with supported models: ["bark_semantic", "bark_coarse"]
✓ Compute Node ready for tasks
```
***
## Configuration
### Command Line Arguments
| Argument | Required | Default | Description |
| ----------------- | -------- | ---------- | ------------------------------- |
| `--gateway-addr` | Yes | - | Gateway gRPC address |
| `--model-path` | No | `./models` | Model files directory |
| `--registry-addr` | No | - | P2P Registry address (for sync) |
| `--subnet-id` | No | `1` | Subnet to join |
| `--sync-models` | No | `false` | Enable model synchronization |
| `--models-dir` | No | `./models` | Download directory |
### Environment Variables
| Variable | Required | Default | Description |
| --------------------------- | -------- | ------------------ | ----------------------------------------- |
| `COMPUTE_NODE_PRIVATE_KEY` | Yes\* | - | Node wallet private key |
| `NODE_WALLET_ADDRESS` | No | Derived | Node wallet address |
| `SANDBOX_MODE` | No | `strict` | Sandbox mode (strict/permissive/disabled) |
| `EXECUTION_TIMEOUT_SECS` | No | `300` | Max execution time |
| `MAX_MEMORY_MB` | No | `4096` | Max memory per execution |
| `ENABLE_EXECUTION_FALLBACK` | No | `false` | Enable fallback execution |
| `REQUIRE_PAYMENT` | No | `false` | Require payment validation |
| `PYTHON_EXECUTOR_PATH` | No | `python_executors` | Path to Python executors |
\*Auto-generated if not provided (development only)
See [Configuration Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/configuration.md) for complete details.
***
## Sandbox Security
The compute node uses multiple layers of security isolation:
### Security Layers
| Layer | Technology | Protection |
| ----- | --------------------- | -------------------------------------- |
| 1 | **seccomp** | Filters dangerous system calls |
| 2 | **PID namespace** | Isolates process visibility |
| 3 | **Network namespace** | No external network access |
| 4 | **Mount namespace** | Isolated filesystem view |
| 5 | **Landlock** | Fine-grained filesystem access control |
| 6 | **Resource limits** | Bounds CPU, memory, time |
### Sandbox Modes
| Mode | seccomp | Namespaces | Landlock | Limits | Use Case |
| ------------ | ------- | ---------- | -------- | ------ | ---------------- |
| `strict` | ✅ | ✅ | ✅ | ✅ | Production |
| `permissive` | ✅ | ⚠️ | ⚠️ | ✅ | Testing |
| `disabled` | ❌ | ❌ | ❌ | ⚠️ | Development only |
### Blocked Operations
| Operation | Protection |
| ---------------------- | --------------------------- |
| Network access | Network namespace isolation |
| Read `/etc/passwd` | Landlock filesystem rules |
| Fork bomb | `RLIMIT_NPROC` limit |
| Memory exhaustion | `RLIMIT_AS` limit |
| CPU exhaustion | `RLIMIT_CPU` limit |
| Access other processes | PID namespace isolation |
See [Sandbox Execution](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/sandbox-execution.md) for deep dive.
***
## Model Execution
### Supported Model Formats
| Format | Extension | Framework | Auto-detect |
| ----------- | -------------- | ------------ | ----------- |
| TorchScript | `.pt`, `.pth` | PyTorch | ✅ |
| ONNX | `.onnx` | ONNX Runtime | ✅ |
| Safetensors | `.safetensors` | Multiple | ✅ |
### Executor Scripts
Located in `compute_node/python_executors/`:
| Script | Purpose |
| ---------------------------- | ------------------------ |
| `generic_model_executor.py` | General-purpose executor |
| `semantic_model_executor.py` | Bark semantic stage |
| `coarse_model_executor.py` | Bark coarse stage |
### Execution Flow
```
1. Receive InferenceRequest
│
▼
2. Determine model type
│
▼
3. Select appropriate executor script
│
▼
4. Prepare sandbox environment
├── Create temp directory
├── Copy executor script
└── Apply security restrictions
│
▼
5. Execute in sandbox
├── Write input to file
├── Run Python process
├── Enforce timeout
└── Read output from file
│
▼
6. Sign result
├── Hash output (SHA256)
└── Sign with node wallet (secp256k1)
│
▼
7. Return InferenceResponse
├── output_data
├── response_hash
├── response_signature
└── completion_validation
```
See [Model Management](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/model-management.md) and [Python Executors](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/python-executors.md) for details.
***
## Signing
All computation results are cryptographically signed:
### Signature Components
| Field | Description |
| ----------------------- | --------------------------- |
| `response_hash` | SHA256 hash of output\_data |
| `response_signature` | secp256k1 signature |
| `completion_validation` | Complete attestation |
### Signed Message Format
```
SHA256(request_id || result_data || timestamp)
```
### Verification
```rust
// On gateway or validator
let message = format!("{}{}{}", request_id, result_data, timestamp);
let message_hash = sha256(&message);
let recovered_address = signature.recover(message_hash)?;
assert_eq!(recovered_address, compute_node_address);
```
***
## Model Synchronization
Compute nodes can auto-download models from subnets:
### Enable Sync
```bash
cargo run --bin compute_node -- \
--gateway-addr http://127.0.0.1:50051 \
--registry-addr http://127.0.0.1:50050 \
--subnet-id 1 \
--sync-models \
--models-dir ./models
```
### Sync Process
1. Query P2P Registry for subnet metadata
2. Compare local models with subnet requirements
3. Download missing models
4. Verify model hashes
5. Extract executor scripts
***
## Metrics & Monitoring
### Execution Statistics
The compute node tracks:
* Total executions
* Successful / failed count
* Average execution time
* Model-specific statistics
### Logging
```bash
# Enable debug logging
RUST_LOG=debug cargo run --bin compute_node -- ...
# Filter to specific modules
RUST_LOG=compute_node::sandbox=trace cargo run --bin compute_node -- ...
```
***
## Troubleshooting
### Common Issues
**"Failed to connect to Gateway"**
```
Error: Failed to connect to Gateway at http://127.0.0.1:50051
```
* Verify Gateway is running
* Check `--gateway-addr` is correct
**"Model not found"**
```
Error: Model bark_semantic_model.pt not found at ./models/bark_semantic_model.pt
```
* Ensure model file exists in `--model-path`
* Enable `--sync-models` for auto-download
**"Sandbox execution failed"**
```
Error: Sandbox execution failed: Timeout after 300s
```
* Increase `EXECUTION_TIMEOUT_SECS`
* Check model complexity
* Use `SANDBOX_MODE=permissive` for debugging
**"Permission denied in sandbox"**
```
Error: Landlock: Access denied to /some/path
```
* Ensure all required files are in allowed paths
* Check Landlock rules in sandbox config
See [Compute Troubleshooting](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/compute-issues.md) for more help.
***
## Python Environment Setup
### Create Virtual Environment
```bash
cd compute_node/python_executors
# Create environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Verify
python verify_environment.py
```
### Requirements
```
torch>=2.1.0
torchaudio>=2.1.0
transformers>=4.35.0
numpy>=1.24.3
scipy>=1.11.3
soundfile>=0.12.1
librosa>=0.10.1
```
***
## Related Documentation
* [Architecture](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/architecture.md) - Internal architecture details
* [Sandbox Execution](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/sandbox-execution.md) - Security isolation deep dive
* [Model Management](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/model-management.md) - Model loading and caching
* [Python Executors](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/python-executors.md) - Executor scripts
* [Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/components/compute-node/configuration.md) - Configuration options
# P2P Registry
The P2P Registry is the decentralized coordination service for NCN Network v2. It handles node discovery, validator consensus, and subnet management using a libp2p-based peer-to-peer network.
***
## Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ P2P Registry Node │
│ │
│ External Interfaces │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ gRPC Server │ │ P2P Node │ │
│ │ (Port 50050) │ │ (Port 8828) │ │
│ │ │ │ │ │
│ │ • Node registration│ │ • Kademlia DHT │ │
│ │ • Validation RPCs │ │ • Peer discovery │ │
│ │ • Subnet mgmt │ │ • Data replication │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
│ Core Services │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ Preprocessing │ │ Completion │ │ Subnet │ │ │
│ │ │ Service │ │ Service │ │ Manager │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ Validator │ │ Mempool │ │ DHT Storage │ │ │
│ │ │ Pool │ │ │ │ │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Blockchain Sync │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Validator Registry Contract Sync (periodic) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Features
* **Node Discovery**: Kademlia DHT-based peer discovery
* **Validator Consensus**: M-of-N signature collection
* **Subnet Management**: Two-phase subnet creation with fee estimation
* **State Persistence**: DHT-based distributed storage
* **Blockchain Sync**: Automatic validator registry synchronization
* **Mempool**: Temporary storage for pending validations
***
## Quick Start
### Build
```bash
cargo build --release -p p2p_registry_node
```
### Run
```bash
cargo run --release --bin p2p_registry_node -- \
--p2p-listen-addr /ip4/0.0.0.0/tcp/8828 \
--grpc-listen-addr 127.0.0.1:50050
```
**Expected Output**:
```
Starting P2P Registry Node...
P2P listening on /ip4/0.0.0.0/tcp/8828
Local peer ID: 12D3KooWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
gRPC server listening on 127.0.0.1:50050
✓ Validator pool initialized (0 validators)
✓ Mempool initialized
✓ Subnet manager initialized
✓ P2P Registry ready
```
***
## Architecture
### Internal Modules
| Module | File | Purpose |
| ---------------- | ------------------------------- | ----------------------- |
| Main Service | `src/main.rs` | Service orchestration |
| P2P Registry | `src/p2p_registry.rs` | libp2p networking |
| Validator Pool | `src/validator_pool.rs` | Validator management |
| Mempool | `src/mempool.rs` | Pending request storage |
| Preprocessing | `src/preprocessing.rs` | Request validation |
| Completion | `src/completion.rs` | Result validation |
| Subnet Manager | `src/subnet_manager.rs` | Subnet CRUD |
| DHT Persistence | `src/dht_persistence.rs` | Distributed storage |
| Validator Signer | `src/validator_signer.rs` | Signature generation |
| Validator Sync | `src/validator_sync_service.rs` | Blockchain sync |
### Service Dependencies
```
┌─────────────────────────────────────────────────────────────────┐
│ P2P Registry │
│ │
│ ┌───────────────┐ │
│ │ gRPC Server │ │
│ └───────┬───────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Request Handler │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ RegisterNode │ DiscoverNodes │ Validation RPCs │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └───────────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ Validator Pool│ │ Mempool │ │Subnet Manager │ │
│ │ │ │ │ │ │ │
│ │ • Selection │ │ • Pending reqs│ │ • Create │ │
│ │ • Reputation │ │ • TTL cleanup │ │ • Get/List │ │
│ │ • Slashing │ │ • Statistics │ │ • Validation │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ DHT Storage │ │
│ │ (Kademlia) │ │
│ └───────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
***
## gRPC API
### P2PRegistryService
#### Node Management
| RPC | Request | Response | Description |
| --------------------- | ---------------------------- | ----------------- | ---------------- |
| `RegisterNode` | `NodeInfo` | `Ack` | Register a node |
| `UpdateNodeHeartbeat` | `UpdateNodeHeartbeatRequest` | `Ack` | Update heartbeat |
| `DeregisterNode` | `WalletAddress` | `Ack` | Remove node |
| `DiscoverNodes` | `DiscoverNodesRequest` | `stream NodeInfo` | Find nodes |
#### Validation
| RPC | Request | Response | Description |
| -------------------------------- | ------------------- | ------------------------- | ---------------------------- |
| `RequestPreprocessingValidation` | `InferenceRequest` | `PreprocessingValidation` | Get preprocessing validation |
| `RequestCompletionValidation` | `InferenceResponse` | `CompletionValidation` | Get completion validation |
#### Subnet Management
| RPC | Request | Response | Description |
| ------------------- | -------------------------- | --------------------------- | --------------------- |
| `EstimateSubnetFee` | `EstimateSubnetFeeRequest` | `EstimateSubnetFeeResponse` | Estimate creation fee |
| `CreateSubnet` | `CreateSubnetRequest` | `CreateSubnetResponse` | Create subnet |
| `GetSubnet` | `GetSubnetRequest` | `GetSubnetResponse` | Get subnet info |
| `ListSubnets` | `Empty` | `stream SubnetMetadata` | List all subnets |
#### Validator Management
| RPC | Request | Response | Description |
| --------------------------- | ---------------------------- | ----------------------------- | ------------------ |
| `RegisterValidator` | `RegisterValidatorRequest` | `RegisterValidatorResponse` | Register validator |
| `UnregisterValidator` | `UnregisterValidatorRequest` | `Ack` | Unregister |
| `GetValidatorInfo` | `ValidatorAddressRequest` | `ValidatorInfoResponse` | Get validator info |
| `ListValidators` | `ListValidatorsRequest` | `stream ValidatorInfoMessage` | List validators |
| `UpdateValidatorReputation` | `UpdateReputationRequest` | `Ack` | Update reputation |
See [gRPC API Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/grpc-api.md) for detailed documentation.
***
## P2P Networking
### Kademlia DHT
The registry uses libp2p's Kademlia DHT for:
* Peer discovery
* Distributed storage
* Network resilience
### Peer Discovery
```
Node A DHT Node B
│ │ │
│ 1. Bootstrap │ │
│───────────────────────▶│ │
│ │ │
│ 2. FIND_NODE │ │
│───────────────────────▶│ │
│ │ │
│ 3. K closest peers │ │
│◀───────────────────────│ │
│ │ │
│ 4. Connect to peers │ │
│─────────────────────────────────────────────────▶│
│ │ │
```
### Bootstrap Nodes
```bash
# Connect to bootstrap nodes
--bootstrap /ip4/192.168.1.100/tcp/8828/p2p/12D3KooW...
--bootstrap /ip4/192.168.1.101/tcp/8828/p2p/12D3KooX...
```
***
## Validator Pool
### Features
* **Registration**: Add/remove validators
* **Selection**: Multiple strategies (random, reputation, stake)
* **Reputation**: Track validation success/failure
* **Slashing**: Penalize misbehavior
* **Rotation**: Periodic validator rotation
### Configuration
```bash
# Validator pool settings
MIN_VALIDATORS_FOR_CONSENSUS=3
MAX_VALIDATORS_TO_SELECT=5
MIN_REPUTATION_THRESHOLD=20
VALIDATOR_ROTATION_INTERVAL_SECS=3600
```
See [Validator Pool](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/validator-pool.md) for details.
***
## Mempool
### Structure
```rust
pub struct Mempool {
pending_requests: HashMap>,
preprocessing_validations: HashMap>,
completion_validations: HashMap>,
}
```
### TTL Configuration
| Entry Type | Default TTL |
| ------------------------- | ----------- |
| Pending requests | 10 minutes |
| Preprocessing validations | 15 minutes |
| Completion validations | 5 minutes |
### Cleanup
Automatic cleanup runs every 60 seconds:
```rust
// Cleanup task
loop {
tokio::time::sleep(Duration::from_secs(60)).await;
let stats = mempool.lock().await.cleanup_expired();
log::info!("Mempool cleanup: {:?}", stats);
}
```
***
## Subnet Manager
### Subnet Creation Flow
```
1. EstimateSubnetFee
├── Calculate fee based on models
├── Generate fee_quote_id (valid 10 min)
└── Return fee + contract address
2. Client pays on-chain
3. CreateSubnet
├── Verify payment_tx on blockchain
├── Verify config_hash matches quote
├── Collect validator signatures
├── Store subnet metadata
└── Return subnet_id
```
### SubnetMetadata
```protobuf
message SubnetMetadata {
uint64 subnet_id = 1;
string gateway_address = 2;
int64 created_at = 3;
repeated ModelDescriptor models = 4;
repeated ValidatorSignature validated_by = 5;
string network_fee_wei = 6;
string payment_tx = 7;
string status = 9; // pending, active, deprecated
}
```
***
## Configuration
### Command Line Arguments
| Argument | Required | Default | Description |
| -------------------- | -------- | ----------------------- | -------------------------- |
| `--p2p-listen-addr` | No | `/ip4/0.0.0.0/tcp/8828` | P2P listen address |
| `--grpc-listen-addr` | No | `127.0.0.1:50050` | gRPC listen address |
| `--bootstrap` | No | - | Bootstrap node addresses |
| `--data-dir` | No | `./data` | Data persistence directory |
### Environment Variables
| Variable | Required | Default | Description |
| ----------------------------- | -------- | ------- | --------------------------- |
| `VALIDATOR_PRIVATE_KEY` | Yes\* | - | Validator signing key |
| `VALIDATOR_SYNC_ENABLED` | No | `true` | Enable blockchain sync |
| `VALIDATOR_SYNC_INTERVAL` | No | `60` | Sync interval (seconds) |
| `VALIDATOR_REGISTRY_CONTRACT` | No | - | On-chain validator registry |
| `FORKNET_RPC_URL` | No | - | Blockchain RPC URL |
| `CHAIN_ID` | No | `828` | Blockchain chain ID |
\*Auto-generated if not provided (development only)
See [Configuration Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/configuration.md) for complete details.
***
## Background Tasks
### Automatic Tasks
| Task | Interval | Purpose |
| ------------------ | -------- | ----------------------- |
| Mempool cleanup | 60s | Remove expired entries |
| Validator rotation | 1 hour | Rotate validators |
| Statistics logging | 5 min | Log pool/mempool stats |
| Blockchain sync | 60s | Sync validator registry |
### Task Implementation
```rust
// Mempool cleanup task
tokio::spawn(async move {
loop {
tokio::time::sleep(Duration::from_secs(60)).await;
let stats = mempool.lock().await.cleanup_expired();
log::info!("Mempool cleanup: removed {} expired entries", stats.total_removed);
}
});
// Validator rotation task
tokio::spawn(async move {
loop {
tokio::time::sleep(Duration::from_secs(3600)).await;
let rotated = validator_pool.lock().await.rotate_validators();
log::info!("Validator rotation: {} validators affected", rotated);
}
});
```
***
## Monitoring
### Metrics
| Metric | Type | Description |
| ---------------------------- | ------- | ----------------- |
| `registry_nodes_registered` | Gauge | Registered nodes |
| `registry_validators_active` | Gauge | Active validators |
| `registry_mempool_size` | Gauge | Mempool entries |
| `registry_subnets_total` | Counter | Total subnets |
| `registry_validations_total` | Counter | Total validations |
| `registry_p2p_peers` | Gauge | Connected peers |
### Health Endpoint
```bash
curl http://127.0.0.1:50050/health
# Response
{
"status": "healthy",
"p2p": {
"peer_id": "12D3KooW...",
"connected_peers": 5
},
"validators": {
"active": 10,
"total": 15
},
"mempool": {
"pending_requests": 3,
"preprocessing": 2,
"completion": 1
}
}
```
***
## Troubleshooting
### Common Issues
**"No validators available"**
```
Error: Insufficient validators for consensus
```
* Check validators are registered and active
* Verify `VALIDATOR_SYNC_ENABLED=true`
* Check blockchain RPC connectivity
**"P2P bootstrap failed"**
```
Error: Failed to connect to bootstrap nodes
```
* Verify bootstrap node addresses
* Check network connectivity
* Ensure ports are open (8828)
**"Mempool full"**
```
Warning: Mempool size exceeds threshold
```
* Increase cleanup frequency
* Check for stuck requests
* Verify downstream services (gateways)
See [Registry Troubleshooting](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/registry-issues.md) for more help.
***
## Related Documentation
* [Architecture](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/architecture.md) - Internal architecture details
* [DHT Persistence](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/dht-persistence.md) - Distributed storage
* [Validator Pool](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/validator-pool.md) - Validator management
* [gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/grpc-api.md) - API reference
* [Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/components/p2p-registry/configuration.md) - Configuration options
# Smart Contracts
NCN Network v2 uses Solidity smart contracts deployed on Ethereum-compatible blockchains for payment handling and validator management.
***
## Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ NCN Smart Contracts │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ InferencePayment Contract │ │
│ │ │ │
│ │ • Escrow-based payment system │ │
│ │ • Validator signature verification │ │
│ │ • Multi-party payment distribution │ │
│ │ • Automatic refunds on expiry │ │
│ │ │ │
│ │ Functions: │ │
│ │ - initiateInferenceRequest() │ │
│ │ - completeInferenceRequest() │ │
│ │ - handleExpiredRequest() │ │
│ │ - markRequestFailed() │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ NCNToken Contract │ │
│ │ │ │
│ │ • ERC20 token for payments │ │
│ │ • Standard transfer/approve functions │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ NCNValidatorRegistry Contract │ │
│ │ │ │
│ │ • On-chain validator registration │ │
│ │ • Stake management │ │
│ │ • Slashing functionality │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Deployed Contracts
### Forknet Testnet
| Contract | Address | Status |
| --------------------- | -------------------------------------------- | ---------- |
| **InferencePayment** | `0x4361115359E5C0a25c9b2f8Bb71184F010b768ea` | ✅ Deployed |
| **NCNToken** | `0x38E2565e8905BeAf83C34b266592465C22A2f108` | ✅ Deployed |
| **ValidatorRegistry** | `0x4F11D4cBE08A5aBa052C368C8477412af63a56f3` | ✅ Deployed |
### Network Configuration
| Setting | Value |
| ------------ | ---------------------------------- |
| **Network** | Forknet Testnet |
| **Chain ID** | 828 (Agglayer connected) |
| **RPC URL** | `https://testnet-rpc-1.forknet.io` |
***
## Contract Documentation
### [Inference Payment](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/inference-payment.md)
Main payment contract:
* Payment initiation with validator signatures
* Payment distribution on completion
* Expiry handling and refunds
* Admin functions
### [NCN Token](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/ncn-token.md)
ERC20 payment token:
* Standard ERC20 interface
* Testnet faucet (if available)
### [Validator Registry](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/validator-registry.md)
On-chain validator management:
* Validator registration with stake
* Slashing mechanism
* Stake withdrawal
### [Deployment](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/deployment.md)
Contract deployment guide:
* Local deployment
* Testnet deployment
* Mainnet considerations
### [ABI Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/abi-reference.md)
Contract ABI documentation:
* Function signatures
* Event definitions
* Type encodings
***
## Quick Start
### Prerequisites
Install Foundry:
```bash
curl -L https://foundry.paradigm.xyz | bash
foundryup
```
### Build Contracts
```bash
cd contracts
# Install dependencies
forge install
# Build
forge build
# Run tests
forge test -vvv
```
### Deploy to Local Network
```bash
# Start local Anvil network
anvil
# Deploy (new terminal)
forge script script/Deploy.s.sol --rpc-url http://127.0.0.1:8545 --broadcast
```
***
## InferencePayment Contract
### Core Functions
#### `initiateInferenceRequest`
Initiates a payment request with escrow.
```solidity
function initiateInferenceRequest(
bytes32 requestId,
address gateway,
address computeNode,
uint256 computePrice,
uint256 gatewayGas,
uint256 validatorReward,
uint256 treasuryFee,
uint256 expiry,
bytes[] calldata validatorSignatures
) external;
```
**Parameters:**
* `requestId` - Unique request identifier
* `gateway` - Gateway address
* `computeNode` - Compute node address
* `computePrice` - Payment to compute node (wei)
* `gatewayGas` - Payment to gateway (wei)
* `validatorReward` - Payment to validators (wei)
* `treasuryFee` - Protocol fee (wei)
* `expiry` - Expiry timestamp
* `validatorSignatures` - M-of-N validator signatures
#### `completeInferenceRequest`
Completes a request and distributes payment.
```solidity
function completeInferenceRequest(
bytes32 requestId,
bytes calldata computeSignature,
bytes32 resultHash,
bytes[] calldata validatorSignatures
) external;
```
**Parameters:**
* `requestId` - Request to complete
* `computeSignature` - Compute node's result signature
* `resultHash` - SHA256 hash of result
* `validatorSignatures` - Completion validator signatures
#### `handleExpiredRequest`
Refunds expired requests.
```solidity
function handleExpiredRequest(bytes32 requestId) external;
```
### Events
```solidity
event RequestInitiated(
bytes32 indexed requestId,
address indexed client,
address indexed gateway,
uint256 totalAmount
);
event PaymentDistributed(
bytes32 indexed requestId,
address computeNode,
uint256 computePayment,
address gateway,
uint256 gatewayPayment
);
event RequestRefunded(
bytes32 indexed requestId,
address indexed client,
uint256 amount
);
event RequestFailed(
bytes32 indexed requestId,
string reason
);
```
***
## Integration
### JavaScript/TypeScript
```typescript
import { ethers } from 'ethers';
const CONTRACT_ADDRESS = '0x4361115359E5C0a25c9b2f8Bb71184F010b768ea';
const CONTRACT_ABI = [...]; // See ABI reference
// Connect to contract
const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
const signer = new ethers.Wallet(PRIVATE_KEY, provider);
const contract = new ethers.Contract(CONTRACT_ADDRESS, CONTRACT_ABI, signer);
// Initiate request
const tx = await contract.initiateInferenceRequest(
requestId,
gateway,
computeNode,
computePrice,
gatewayGas,
validatorReward,
treasuryFee,
expiry,
validatorSignatures
);
await tx.wait();
```
### Rust (ethers-rs)
```rust
use ethers::prelude::*;
// Generate contract bindings
abigen!(
InferencePayment,
"contracts/out/InferencePayment.sol/InferencePayment.json"
);
// Connect to contract
let provider = Provider::::try_from(RPC_URL)?;
let wallet = LocalWallet::from_str(PRIVATE_KEY)?;
let client = SignerMiddleware::new(provider, wallet);
let contract = InferencePayment::new(CONTRACT_ADDRESS.parse()?, Arc::new(client));
// Initiate request
let tx = contract.initiate_inference_request(
request_id,
gateway,
compute_node,
compute_price,
gateway_gas,
validator_reward,
treasury_fee,
expiry,
validator_signatures,
).send().await?.await?;
```
***
## Security
### Implemented Protections
| Protection | Description |
| -------------------------- | --------------------------- |
| **ReentrancyGuard** | Prevents reentrancy attacks |
| **Signature Verification** | ECDSA signature validation |
| **Expiry Checks** | Time-bound requests |
| **Access Control** | Function-level permissions |
| **Pausable** | Emergency pause capability |
### Security Considerations
1. **Private Key Management**: Never expose private keys
2. **Signature Replay**: Unique request IDs prevent replay
3. **Front-running**: Time-bound signatures mitigate
4. **Oracle Dependency**: Validators provide trust
5. **Upgrade Path**: Consider proxy patterns for mainnet
***
## Testing
### Run Tests
```bash
cd contracts
# Run all tests
forge test -vvv
# Run specific test
forge test --match-test testInitiateInferenceRequest -vvv
# Gas report
forge test --gas-report
```
### Test Coverage
```bash
forge coverage
```
### Test Files
| File | Coverage |
| ---------------------------- | ------------ |
| `InferencePayment.t.sol` | 95% |
| `NCNValidatorRegistry.t.sol` | 90% |
| `SignatureDebug.t.sol` | Helper tests |
***
## Gas Costs
### Estimated Gas Usage
| Function | Gas (approx) |
| -------------------------- | ------------ |
| `initiateInferenceRequest` | \~150,000 |
| `completeInferenceRequest` | \~200,000 |
| `handleExpiredRequest` | \~80,000 |
### Optimization Tips
1. Batch multiple requests
2. Use calldata for signatures
3. Minimize storage writes
4. Consider L2 deployment
***
## Contract Verification
### Verify on Etherscan
```bash
forge verify-contract \
--chain-id 42161 \
--compiler-version v0.8.20 \
--constructor-args $(cast abi-encode "constructor(address,address,uint256)" $TOKEN $TREASURY $MIN_SIGS) \
$CONTRACT_ADDRESS \
src/InferencePayment.sol:InferencePayment \
--etherscan-api-key $ETHERSCAN_API_KEY
```
***
## Related Documentation
* [Inference Payment](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/inference-payment.md) - Detailed payment contract docs
* [Deployment](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/deployment.md) - Deployment guide
* [ABI Reference](https://github.com/NeuroChainAi/docs-guides/blob/main/components/smart-contracts/abi-reference.md) - Contract ABIs
* [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow) - Payment architecture
# Test Client
The Test Client is an example application for testing NCN Network functionality, including the complete inference and payment flow.
***
## Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Test Client │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Command Line Interface │ │
│ │ --gateway-addr, --wallet-key, --model-path, --text, etc. │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Inference Pipeline │ │
│ │ 1. Submit request │ │
│ │ 2. Handle payment │ │
│ │ 3. Wait for result │ │
│ │ 4. Verify and display │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Payment Manager │ │
│ │ • Wallet management │ │
│ │ • Balance checking │ │
│ │ • Transaction submission │ │
│ │ • Confirmation waiting │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ Connections: │
│ ├── Gateway (gRPC) ────────────────────▶ :50051 │
│ └── Blockchain (JSON-RPC) ─────────────▶ RPC_URL │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Features
* **Complete Payment Flow**: Handles preprocessing, payment, and completion
* **Multi-Network Support**: Local, forknet, testnet, mainnet
* **Bark Pipeline**: Text-to-audio pipeline testing
* **Dry Run Mode**: Test without actual payments
* **Detailed Logging**: Visual progress indicators
***
## Quick Start
### Build
```bash
cargo build --release -p test_client
```
### Basic Usage
```bash
# Simple test (no payment)
cargo run --release --bin test_client
# With payment
cargo run --release --bin test_client -- \
--wallet-key 0xYOUR_PRIVATE_KEY \
--network forknet
```
### Full Options
```bash
cargo run --release --bin test_client -- \
--gateway-addr http://127.0.0.1:50051 \
--wallet-key 0xYOUR_PRIVATE_KEY \
--network forknet \
--rpc-url http://127.0.0.1:8545 \
--semantic-model-path ./models/semantic.pt \
--coarse-model-path ./models/coarse.pt \
--fine-model-path ./models/fine.pt \
--text "Hello, this is a test"
```
***
## Command Line Options
| Option | Required | Default | Description |
| ----------------------- | -------- | ------------------------ | ------------------------- |
| `--gateway-addr` | No | `http://127.0.0.1:50051` | Gateway gRPC address |
| `--wallet-key` | No\* | - | Client wallet private key |
| `--network` | No | `local` | Network name |
| `--rpc-url` | No | Auto | Blockchain RPC URL |
| `--contract-address` | No | Auto | Payment contract address |
| `--semantic-model-path` | No | - | Semantic model path |
| `--coarse-model-path` | No | - | Coarse model path |
| `--fine-model-path` | No | - | Fine model path |
| `--text` | No | Default | Text input for TTS |
| `--dry-run` | No | `false` | Skip actual payment |
\*Required if network requires payment
***
## Output Examples
### Successful Run
```
╔════════════════════════════════════════╗
║ NCN Network Test Client ║
╚════════════════════════════════════════╝
Connecting to Gateway at http://127.0.0.1:50051...
✓ Connected to Gateway
╔════════════════════════════════════════╗
║ Step: Text to Semantic ║
╚════════════════════════════════════════╝
📤 Submitting inference request...
Task ID: req-abc123
Status: queued
💰 Payment Information:
┌─────────────────────────────────────────────┐
│ Payment Breakdown │
├─────────────────────────────────────────────┤
│ Compute Price: 1000000000000000000 wei │
│ Gateway Gas: 100000000000000000 wei │
│ Validator Reward: 50000000000000000 wei │
│ Treasury Fee: 50000000000000000 wei │
├─────────────────────────────────────────────┤
│ Total: 1200000000000000000 wei │
└─────────────────────────────────────────────┘
≈ 1.200000 ETH
💼 Checking balance...
✓ Balance: 10.0 ETH (sufficient)
💸 Sending payment transaction...
✓ Transaction sent: 0x1234...
⏳ Waiting for confirmation...
✓ Confirmed in block 12345678
📨 Subscribing to results...
✓ Received result in 1.25s
Output: [semantic tokens data]
╔════════════════════════════════════════╗
║ Step: Semantic to Coarse ║
╚════════════════════════════════════════╝
...
✅ All steps completed successfully!
Total time: 5.3s
Output saved to: output.wav
```
### Dry Run Mode
```
╔════════════════════════════════════════╗
║ NCN Network Test Client (DRY RUN) ║
╚════════════════════════════════════════╝
⚠️ Dry run mode - no actual payments will be made
📤 Submitting inference request...
Task ID: req-xyz789
💰 Would pay: 1.2 ETH
(skipping actual payment in dry run mode)
📨 Subscribing to results...
...
```
***
## Configuration
### Environment Variables
```bash
# Optional environment configuration
export GATEWAY_ADDR=http://127.0.0.1:50051
export CLIENT_PRIVATE_KEY=0x...
export NETWORK=forknet
export RPC_URL=http://127.0.0.1:8545
```
### Network Configurations
| Network | RPC URL | Notes |
| --------- | ----------------------- | ------------------- |
| `local` | `http://127.0.0.1:8545` | Local Anvil/Hardhat |
| `forknet` | `http://127.0.0.1:8545` | NCN Forknet |
| `sepolia` | Infura/Alchemy URL | Ethereum testnet |
| `mainnet` | Infura/Alchemy URL | Ethereum mainnet |
***
## Payment Flow
### Without Payment (Development)
```
1. Submit request → Gateway
2. Gateway queues task
3. Compute node executes
4. Result returned
```
### With Payment
```
1. Submit request → Gateway
2. Receive payment info
3. Submit blockchain transaction
4. Wait for confirmation
5. Confirm with gateway
6. Compute node executes
7. Result returned
8. Payment distributed
```
***
## Bark Pipeline
The test client supports the full Bark text-to-audio pipeline:
### Pipeline Stages
```
Text → Semantic → Coarse → Fine → Audio
│ │ │
▼ ▼ ▼
Semantic Coarse Fine
Tokens Tokens Tokens
```
### Usage
```bash
cargo run --bin test_client -- \
--semantic-model-path ./models/bark_semantic_model.pt \
--coarse-model-path ./models/bark_coarse_model.pt \
--fine-model-path ./models/bark_fine_model.pt \
--text "Hello, this is NCN Network speaking."
```
***
## Troubleshooting
### Common Issues
**"Connection refused"**
* Ensure Gateway is running
* Check `--gateway-addr` is correct
**"Insufficient funds"**
* Check wallet balance
* Use faucet to get testnet tokens
* Use `--dry-run` for testing
**"Model not found"**
* Verify model paths are correct
* Ensure compute node has models
**"Payment verification failed"**
* Wait for more confirmations
* Check RPC URL connectivity
* Verify contract address
***
## Related Documentation
* [Usage Examples](https://github.com/NeuroChainAi/docs-guides/blob/main/components/test-client/usage.md) - More detailed examples
* [Payment Integration](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/payment-integration.md) - Payment details
* [Gateway gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/gateway-grpc.md) - API reference
# Common Types
The `common_types` crate provides shared types, utilities, and protocol definitions used across all NCN Network components.
***
## Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ common_types Crate │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Protocol Buffer Types │ │
│ │ Generated from proto/common_types.proto │ │
│ │ • InferenceRequest, InferenceResponse │ │
│ │ • NodeInfo, ModelData, PaymentTree │ │
│ │ • PreprocessingValidation, CompletionValidation │ │
│ │ • SubnetMetadata, ValidatorSignature │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Cryptographic Utilities │ │
│ │ • compute_message_hash() - SHA-256 hashing │ │
│ │ • sign_message() - secp256k1 ECDSA signing │ │
│ │ • verify_signature() - Signature verification │ │
│ │ • recover_signer() - Address recovery │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Payment Utilities │ │
│ │ • PaymentTree calculations │ │
│ │ • Fee estimation │ │
│ │ • Wei/ETH conversions │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Type Conversions │ │
│ │ • Protobuf ↔ Native type conversions │ │
│ │ • Serialization/deserialization │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Crate Structure
```
common_types/
├── Cargo.toml
├── build.rs # Protobuf code generation
└── src/
├── lib.rs # Crate root, re-exports
├── crypto.rs # Cryptographic utilities
├── payment.rs # Payment helpers
└── types.rs # Type definitions
```
***
## Usage
### Add Dependency
```toml
# Cargo.toml
[dependencies]
common_types = { path = "../common_types" }
```
### Import Types
```rust
use common_types::{
// Protobuf types
InferenceRequest,
InferenceResponse,
NodeInfo,
PaymentTree,
PreprocessingValidation,
CompletionValidation,
ValidatorSignature,
// Crypto utilities
crypto::{
compute_message_hash,
sign_message,
verify_signature,
recover_signer,
},
// Payment utilities
payment::{
calculate_payment_tree,
total_payment,
},
};
```
***
## Protobuf Types
### Core Types
```rust
// Inference request
pub struct InferenceRequest {
pub request_id: String,
pub model_uuid: String,
pub input_data: String,
pub originator_client_id: String,
pub preprocessing_validation: Option,
pub transaction_confirmation: Option,
pub assigned_timestamp: Option,
pub assigned_compute_node_id: Option,
}
// Inference response
pub struct InferenceResponse {
pub request_id: String,
pub model_uuid: String,
pub output_data: String,
pub status: String,
pub error_message: String,
pub compute_completion: Option,
pub completion_validation: Option,
}
```
### Payment Types
```rust
// Payment distribution
pub struct PaymentTree {
pub compute_price_wei: String,
pub gateway_gas_wei: String,
pub validator_reward_wei: String,
pub treasury_fee_wei: String,
}
// Validator signature
pub struct ValidatorSignature {
pub validator_address: String,
pub signature: String,
pub timestamp: i64,
}
```
### Node Types
```rust
// Node information
pub struct NodeInfo {
pub node_id: String,
pub node_type: String,
pub ip_address: String,
pub port: u32,
pub capabilities: Vec,
pub wallet_address: String,
pub last_heartbeat: i64,
pub supported_models: Vec,
pub subnet_id: Option,
}
// Model data
pub struct ModelData {
pub model_uuid: String,
pub path: String,
pub name: String,
pub category: String,
}
```
***
## Cryptographic Utilities
### Message Hashing
```rust
use common_types::crypto::compute_message_hash;
// Hash message with Ethereum prefix
let message = "Hello, World!";
let hash = compute_message_hash(message);
// Returns: [u8; 32]
```
### Signing
```rust
use common_types::crypto::sign_message;
let private_key = "0x..."; // Private key hex
let message = "Hello, World!";
let signature = sign_message(private_key, message)?;
// Returns: "0x..." (hex-encoded signature)
```
### Verification
```rust
use common_types::crypto::{verify_signature, recover_signer};
let message = "Hello, World!";
let signature = "0x...";
let expected_address = "0x...";
// Verify signature matches expected address
let valid = verify_signature(message, signature, expected_address)?;
// Or recover the signer address
let recovered = recover_signer(message, signature)?;
assert_eq!(recovered, expected_address);
```
### Preprocessing Message
```rust
use common_types::crypto::compute_preprocessing_message;
let request_id = "req-123";
let gateway_wallet = "0x...";
let compute_node_id = "compute-1";
let compute_wallet = "0x...";
let payment_tree = PaymentTree { /* ... */ };
let expiry = 1704067200;
let message_hash = compute_preprocessing_message(
request_id,
gateway_wallet,
compute_node_id,
compute_wallet,
&payment_tree,
expiry,
);
```
### Completion Message
```rust
use common_types::crypto::compute_completion_message;
let request_id = "req-123";
let compute_signature = "0x...";
let result_hash = [0u8; 32];
let timestamp = 1704067200;
let computation_time = 1500;
let message_hash = compute_completion_message(
request_id,
compute_signature,
&result_hash,
timestamp,
computation_time,
);
```
***
## Payment Utilities
### Calculate Payment Tree
```rust
use common_types::payment::calculate_payment_tree;
let base_price = 1_000_000_000_000_000_000u128; // 1 ETH
let gateway_rate = 0.10; // 10%
let validator_rate = 0.05; // 5%
let treasury_rate = 0.05; // 5%
let tree = calculate_payment_tree(
base_price,
gateway_rate,
validator_rate,
treasury_rate,
);
// tree.compute_price_wei = "800000000000000000"
// tree.gateway_gas_wei = "100000000000000000"
// tree.validator_reward_wei = "50000000000000000"
// tree.treasury_fee_wei = "50000000000000000"
```
### Total Payment
```rust
use common_types::payment::total_payment;
let tree = PaymentTree {
compute_price_wei: "800000000000000000".to_string(),
gateway_gas_wei: "100000000000000000".to_string(),
validator_reward_wei: "50000000000000000".to_string(),
treasury_fee_wei: "50000000000000000".to_string(),
};
let total = total_payment(&tree);
// total = 1000000000000000000 (1 ETH)
```
### Wei/ETH Conversion
```rust
use common_types::payment::{wei_to_eth, eth_to_wei};
let wei = 1_000_000_000_000_000_000u128;
let eth = wei_to_eth(wei);
// eth = 1.0
let eth = 2.5;
let wei = eth_to_wei(eth);
// wei = 2500000000000000000
```
***
## gRPC Services
### GatewayClientService Stub
```rust
use common_types::gateway_client_service_client::GatewayClientServiceClient;
let mut client = GatewayClientServiceClient::connect("http://localhost:50051").await?;
let request = InferenceRequest {
request_id: "req-123".to_string(),
model_uuid: "bark_semantic".to_string(),
input_data: "{\"text\": \"Hello\"}".to_string(),
originator_client_id: "client-1".to_string(),
..Default::default()
};
let response = client.submit_inference_task(request).await?;
```
### P2PRegistryService Stub
```rust
use common_types::p2p_registry_service_client::P2PRegistryServiceClient;
let mut client = P2PRegistryServiceClient::connect("http://localhost:50050").await?;
let request = DiscoverNodesRequest {
node_type: "compute".to_string(),
..Default::default()
};
let mut stream = client.discover_nodes(request).await?.into_inner();
while let Some(node) = stream.next().await {
println!("Found node: {:?}", node?);
}
```
***
## Building
### Build Protobuf
```bash
cargo build -p common_types
```
The `build.rs` script automatically generates Rust code from `proto/common_types.proto`.
### Regenerate Types
```bash
# If proto file changes, rebuild
cargo clean -p common_types
cargo build -p common_types
```
***
## Dependencies
```toml
[dependencies]
prost = "0.12"
tonic = { version = "0.10", features = ["gzip"] }
sha2 = "0.10"
secp256k1 = { version = "0.27", features = ["recovery"] }
hex = "0.4"
[build-dependencies]
tonic-build = "0.10"
```
***
## Related Documentation
* [Protobuf Reference](/nc/neurochainai-guides/api-reference/protobuf) - Proto file documentation
* [Cryptographic Signing](https://github.com/NeuroChainAi/docs-guides/blob/main/security/cryptographic-signing.md) - Signature details
* [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow) - Payment architecture
# Overview
This section contains practical guides for different user roles and tasks.
***
## Guide Categories
### [Development](/nc/neurochainai-guides/development/development)
For developers building or contributing to NCN:
* [Environment Setup](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/environment-setup.md) - Prerequisites and tools
* [Building](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/building.md) - Build from source
* [Running Locally](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/running-locally.md) - Local development
* [Testing](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/testing.md) - Run tests
* [Debugging](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/debugging.md) - Debug tips
### [Deployment](/nc/neurochainai-guides/deployment/deployment)
For deploying NCN to different environments:
* [Docker](/nc/neurochainai-guides/deployment/docker) - Container deployment
* [Manual](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/manual.md) - Manual installation
* [Kubernetes](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/kubernetes.md) - K8s deployment
* [Production](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/production.md) - Production considerations
### [Operators](/nc/neurochainai-guides/operators/operators)
For running NCN infrastructure:
* [Gateway Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/gateway-operator.md) - Run a gateway
* [Compute Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/compute-operator.md) - Provide compute
* [Validator Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/validator-operator.md) - Run a validator
* [Monitoring](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/monitoring.md) - Set up monitoring
### [Clients](/nc/neurochainai-guides/clients/clients)
For integrating with NCN:
* [gRPC Client](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/grpc-client.md) - gRPC integration
* [HTTP Client](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/http-client.md) - REST API integration
* [Payment Integration](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/payment-integration.md) - Payment flow
* [Examples](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/examples.md) - Code examples
***
## Quick Links by Task
### I want to...
| Task | Guide |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Try NCN locally** | [Getting Started](/nc/neurochainai-guides/introduction/getting-started) |
| **Set up development** | [Environment Setup](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/environment-setup.md) |
| **Build from source** | [Building](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/building.md) |
| **Deploy with Docker** | [Docker Deployment](/nc/neurochainai-guides/deployment/docker) |
| **Run a Gateway** | [Gateway Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/gateway-operator.md) |
| **Provide compute** | [Compute Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/compute-operator.md) |
| **Integrate my app** | [Client Guides](/nc/neurochainai-guides/clients/clients) |
| **Debug an issue** | [Debugging](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/debugging.md) |
***
## Guide Conventions
### Prerequisites
Each guide lists prerequisites at the top:
```
Prerequisites:
- Rust 1.70+
- Python 3.8+
- Docker 20.10+
```
### Code Examples
Code blocks show commands to run:
```bash
# This is a command to run
cargo build --release
```
### Placeholders
Placeholders are indicated with `` or `YOUR_VALUE`:
```bash
export PRIVATE_KEY=
export PRIVATE_KEY=YOUR_PRIVATE_KEY
```
### Notes and Warnings
> **Note**: Important information
> **Warning**: Critical information that could cause issues
***
## Feedback
If you find issues with these guides:
* Open a GitHub issue
* Submit a pull request
* Provide feedback via community channels
# Development Guide
This guide covers setting up a development environment for NCN Network v2.
***
## Quick Start
```bash
# Clone repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
# Build all components
cargo build
# Run tests
cargo test --all
# Start services for local development
./scripts/start-local.sh
```
***
## Development Guides
### [Environment Setup](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/environment-setup.md)
Prerequisites and initial setup:
* Installing Rust, Python, and Git
* IDE configuration
* Development tools
### [Building](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/building.md)
Building from source:
* Full workspace build
* Individual component builds
* Docker image builds
* Troubleshooting build issues
### [Running Locally](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/running-locally.md)
Local development workflow:
* Starting all services
* Development mode configuration
* Hot reloading
* Connecting components
### [Testing](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/testing.md)
Test suites and coverage:
* Unit tests
* Integration tests
* Contract tests
* Security tests
* Load testing
### [Debugging](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/debugging.md)
Debug tips and techniques:
* Logging configuration
* Debug builds
* Profiling
* Common issues
***
## Development Workflow
### Typical Development Cycle
```
1. Create feature branch
git checkout -b feature/my-feature
2. Make changes
[edit code]
3. Build and test
cargo build
cargo test
4. Format and lint
cargo fmt
cargo clippy
5. Run locally
cargo run --bin [component]
6. Commit changes
git add .
git commit -m "feat: my feature"
7. Push and create PR
git push origin feature/my-feature
```
### Code Style
* Follow Rust 2021 edition
* Use `cargo fmt` for formatting
* Use `cargo clippy` for linting
* Document public APIs
* Add tests for new features
***
## Quick Reference
### Build Commands
```bash
# Build everything
cargo build
# Build release
cargo build --release
# Build specific component
cargo build -p gateway_node
cargo build -p compute_node
cargo build -p p2p_registry_node
# Build contracts
cd contracts && forge build
```
### Test Commands
```bash
# All tests
cargo test --all
# Specific component
cargo test -p gateway_node
# With logging
RUST_LOG=debug cargo test
# Contract tests
cd contracts && forge test -vvv
```
### Run Commands
```bash
# P2P Registry
cargo run --bin p2p_registry_node
# Gateway
cargo run --bin gateway_node
# Compute Node
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051
# Test Client
cargo run --bin test_client
```
### Useful Environment Variables
```bash
# Logging
export RUST_LOG=debug
export RUST_LOG=gateway_node=trace,compute_node=debug
# Development mode
export REQUIRE_PAYMENT=false
export SANDBOX_MODE=disabled
# Feature flags
export ENABLE_EXECUTION_FALLBACK=true
```
***
## Next Steps
1. [Set up your environment](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/environment-setup.md)
2. [Build the project](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/building.md)
3. [Run locally](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/running-locally.md)
4. [Run tests](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/testing.md)
# Environment Setup
Complete guide for setting up your NCN Network development environment.
***
## Prerequisites
### Required Software
| Software | Version | Purpose |
| ---------- | ------- | ---------------- |
| **Rust** | 1.70+ | Core services |
| **Python** | 3.8+ | Model execution |
| **Git** | 2.0+ | Version control |
| **protoc** | 3.0+ | Protocol buffers |
### Optional Software
| Software | Version | Purpose |
| ----------- | ------- | -------------------------- |
| **Docker** | 20.10+ | Containerized deployment |
| **Foundry** | Latest | Smart contract development |
| **Node.js** | 18+ | Client SDK development |
***
## Install Rust
### Linux/macOS
```bash
# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Follow the prompts, then reload your shell
source $HOME/.cargo/env
# Verify installation
rustc --version
cargo --version
```
### Windows
Download and run [rustup-init.exe](https://win.rustup.rs/).
### Additional Components
```bash
# Add clippy for linting
rustup component add clippy
# Add rustfmt for formatting
rustup component add rustfmt
```
***
## Install Python
### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv
```
### macOS
```bash
# Using Homebrew
brew install python@3.11
# Or use pyenv for version management
brew install pyenv
pyenv install 3.11
pyenv global 3.11
```
### Python Dependencies
```bash
# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate
# Install ML dependencies
pip install torch transformers numpy scipy
```
***
## Install Protocol Buffers
### Linux (Ubuntu/Debian)
```bash
sudo apt install protobuf-compiler libprotobuf-dev
```
### macOS
```bash
brew install protobuf
```
### Verify Installation
```bash
protoc --version
# Should output: libprotoc 3.x.x or higher
```
***
## Install System Dependencies
### Linux (Ubuntu/Debian)
```bash
# Build essentials
sudo apt install build-essential pkg-config
# OpenSSL development headers
sudo apt install libssl-dev
# Additional dependencies
sudo apt install cmake clang
```
### macOS
```bash
# Xcode command line tools
xcode-select --install
# OpenSSL (if needed)
brew install openssl
```
***
## Clone the Repository
```bash
# Clone the repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
```
***
## Build the Project
```bash
# Build all components in debug mode
cargo build
# Build all components in release mode
cargo build --release
# Build specific component
cargo build -p gateway_node
cargo build -p compute_node
cargo build -p p2p_registry_node
cargo build -p test_client
```
### Expected Output
```
Compiling common_types v0.1.0
Compiling p2p_registry_node v0.1.0
Compiling gateway_node v0.1.0
Compiling compute_node v0.1.0
Compiling test_client v0.1.0
Finished dev [unoptimized + debuginfo] target(s) in X.XXs
```
***
## Verify Installation
### Run Tests
```bash
# Run all tests
cargo test --all
# Run tests with output
cargo test --all -- --nocapture
```
### Check Linting
```bash
# Run clippy
cargo clippy --all
# Run format check
cargo fmt --all -- --check
```
***
## Optional: Docker Setup
### Install Docker
```bash
# Linux
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# macOS
brew install --cask docker
```
### Build Docker Images
```bash
# Build all images
docker-compose build
# Or build individual images
docker build -t ncn-gateway -f gateway_node/Dockerfile .
docker build -t ncn-compute -f compute_node/Dockerfile .
docker build -t ncn-registry -f p2p_registry_node/Dockerfile .
```
***
## Optional: Foundry Setup
For smart contract development:
```bash
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup
# Verify
forge --version
cast --version
anvil --version
```
***
## IDE Setup
### VS Code
Recommended extensions:
```json
{
"recommendations": [
"rust-lang.rust-analyzer",
"tamasfe.even-better-toml",
"serayuzgur.crates",
"vadimcn.vscode-lldb",
"ms-python.python"
]
}
```
### JetBrains (IntelliJ/CLion)
* Install Rust plugin
* Install Python plugin
* Configure Cargo toolchain
***
## Environment Variables
Create a `.env` file or export variables:
```bash
# Logging
export RUST_LOG=info
export RUST_BACKTRACE=1
# Development mode
export REQUIRE_PAYMENT=false
export SANDBOX_MODE=disabled
# Network (local development)
export RPC_URL=http://127.0.0.1:8545
```
***
## Troubleshooting
### "linker not found"
```bash
# Install build essentials
sudo apt install build-essential
```
### "protoc not found"
```bash
# Install protobuf compiler
sudo apt install protobuf-compiler
```
### "OpenSSL not found"
```bash
# Linux
sudo apt install libssl-dev pkg-config
# macOS
brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)
```
### "Python not found" during build
```bash
# Ensure Python is in PATH
which python3
# Or set explicitly
export PYTHON_SYS_EXECUTABLE=$(which python3)
```
***
## Next Steps
* [Building](/nc/neurochainai-guides/development/building) - Detailed build instructions
* [Running Locally](/nc/neurochainai-guides/development/running-locally) - Start local development
* [Testing](/nc/neurochainai-guides/development/testing) - Run the test suite
# Building
Complete guide for building NCN Network components from source.
***
## Quick Build
```bash
# Build all components (debug)
cargo build
# Build all components (release)
cargo build --release
```
***
## Build Individual Components
### Gateway Node
```bash
cargo build -p gateway_node
cargo build --release -p gateway_node
# Binary location
./target/debug/gateway_node
./target/release/gateway_node
```
### Compute Node
```bash
cargo build -p compute_node
cargo build --release -p compute_node
# Binary location
./target/debug/compute_node
./target/release/compute_node
```
### P2P Registry Node
```bash
cargo build -p p2p_registry_node
cargo build --release -p p2p_registry_node
# Binary location
./target/debug/p2p_registry_node
./target/release/p2p_registry_node
```
### Test Client
```bash
cargo build -p test_client
cargo build --release -p test_client
# Binary location
./target/debug/test_client
./target/release/test_client
```
### Common Types Library
```bash
cargo build -p common_types
```
***
## Build Features
### Gateway Features
```bash
# With all features
cargo build -p gateway_node --all-features
# Specific features
cargo build -p gateway_node --features "metrics"
```
### Compute Node Features
```bash
# Without sandbox (for development)
cargo build -p compute_node --no-default-features
# With full sandbox
cargo build -p compute_node --features "sandbox"
```
***
## Build Profiles
### Debug Build
```bash
cargo build
```
* Includes debug symbols
* No optimizations
* Faster compilation
* Larger binaries
* Better for debugging
### Release Build
```bash
cargo build --release
```
* Optimized for performance
* Smaller binaries
* Slower compilation
* Better for production
### Custom Profile
```toml
# Cargo.toml - already configured
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
```
***
## Cross-Compilation
### Linux Target from macOS
```bash
# Add target
rustup target add x86_64-unknown-linux-gnu
# Build
cargo build --target x86_64-unknown-linux-gnu --release
```
### ARM64 Target
```bash
# Add target
rustup target add aarch64-unknown-linux-gnu
# Build
cargo build --target aarch64-unknown-linux-gnu --release
```
***
## Build Smart Contracts
```bash
cd contracts
# Install dependencies
forge install
# Build contracts
forge build
# Output location
ls -la out/
```
### Contract Artifacts
```
out/
├── InferencePayment.sol/
│ └── InferencePayment.json
├── NCNToken.sol/
│ └── NCNToken.json
└── NCNValidatorRegistry.sol/
└── NCNValidatorRegistry.json
```
***
## Build Docker Images
### All Images
```bash
docker-compose build
```
### Individual Images
```bash
# Gateway
docker build -t ncn-gateway -f gateway_node/Dockerfile .
# Compute
docker build -t ncn-compute -f compute_node/Dockerfile .
# Registry
docker build -t ncn-registry -f p2p_registry_node/Dockerfile .
# Test Client
docker build -t ncn-test-client -f test_client/Dockerfile .
```
### Multi-stage Build
Docker images use multi-stage builds for smaller images:
```dockerfile
# Build stage
FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release
# Runtime stage
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/gateway_node /usr/local/bin/
CMD ["gateway_node"]
```
***
## Protocol Buffer Generation
Protobuf code is auto-generated during build via `build.rs`:
```bash
# Regenerate if proto changes
cargo clean -p common_types
cargo build -p common_types
# Generated code location
target/debug/build/common_types-*/out/
```
### Manual Generation
```bash
# If needed manually
protoc --rust_out=src/generated \
--tonic_out=src/generated \
proto/common_types.proto
```
***
## Build Verification
### Check Build
```bash
# Verify binaries exist
ls -la target/release/gateway_node
ls -la target/release/compute_node
ls -la target/release/p2p_registry_node
ls -la target/release/test_client
# Check binary version (if implemented)
./target/release/gateway_node --version
```
### Run Tests
```bash
# All tests
cargo test --all
# Specific package tests
cargo test -p gateway_node
cargo test -p compute_node
# With logging
RUST_LOG=debug cargo test --all -- --nocapture
```
### Lint Check
```bash
# Clippy
cargo clippy --all -- -D warnings
# Format
cargo fmt --all -- --check
```
***
## Build Troubleshooting
### Out of Memory
```bash
# Reduce parallelism
cargo build -j 2
# Or build one package at a time
cargo build -p common_types
cargo build -p gateway_node
```
### Slow Builds
```bash
# Use sccache
cargo install sccache
export RUSTC_WRAPPER=sccache
# Or use mold linker (Linux)
sudo apt install mold
export RUSTFLAGS="-C link-arg=-fuse-ld=mold"
```
### Dependency Conflicts
```bash
# Clean and rebuild
cargo clean
cargo build
# Update dependencies
cargo update
cargo build
```
### Protobuf Errors
```bash
# Ensure protoc is installed
protoc --version
# Regenerate
cargo clean -p common_types
cargo build
```
***
## Build Artifacts
### Binary Locations
| Component | Debug | Release |
| ----------- | -------------------------------- | ---------------------------------- |
| Gateway | `target/debug/gateway_node` | `target/release/gateway_node` |
| Compute | `target/debug/compute_node` | `target/release/compute_node` |
| Registry | `target/debug/p2p_registry_node` | `target/release/p2p_registry_node` |
| Test Client | `target/debug/test_client` | `target/release/test_client` |
### Binary Sizes (Release)
| Binary | Approximate Size |
| ------------------- | ---------------- |
| gateway\_node | \~25 MB |
| compute\_node | \~20 MB |
| p2p\_registry\_node | \~18 MB |
| test\_client | \~15 MB |
***
## Next Steps
* [Running Locally](/nc/neurochainai-guides/development/running-locally) - Start the services
* [Testing](/nc/neurochainai-guides/development/testing) - Run the test suite
* [Docker Deployment](/nc/neurochainai-guides/deployment/docker) - Deploy with containers
# Running Locally
Guide for running NCN Network services on your local machine for development.
***
## Quick Start
```bash
# Terminal 1: Start P2P Registry
cargo run --bin p2p_registry_node
# Terminal 2: Start Gateway
cargo run --bin gateway_node
# Terminal 3: Start Compute Node
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051
# Terminal 4: Run Test Client
cargo run --bin test_client
```
***
## Prerequisites
* [Environment Setup](/nc/neurochainai-guides/development/environment-setup) completed
* [Project Built](/nc/neurochainai-guides/development/building) successfully
* 4 terminal windows available
***
## Step 1: Start P2P Registry
The P2P Registry must start first as other services depend on it.
```bash
# Start with default settings
cargo run --bin p2p_registry_node
# Or with custom settings
cargo run --bin p2p_registry_node -- \
--grpc-listen-addr 127.0.0.1:50050 \
--p2p-listen-addr /ip4/0.0.0.0/tcp/8828
```
### Expected Output
```
Starting P2P Registry Node...
P2P listening on /ip4/0.0.0.0/tcp/8828
Local peer ID: 12D3KooW...
gRPC server listening on 127.0.0.1:50050
✓ Validator pool initialized
✓ Mempool initialized
✓ P2P Registry ready
```
### Verify Registry
```bash
# Check gRPC is responding
grpcurl -plaintext localhost:50050 list
```
***
## Step 2: Start Gateway Node
Open a new terminal:
```bash
# Navigate to project root
cd ncn-network-v2-rs
# Copy example environment file
cp gateway_node/env.example gateway_node/.env
# Edit configuration if needed
nano gateway_node/.env
# Start Gateway
cargo run --bin gateway_node
```
### Environment Variables
Create or edit `gateway_node/.env`:
```bash
# Required
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050
# Optional (defaults shown)
GRPC_ADDR=127.0.0.1:50051
HTTP_ADDR=127.0.0.1:8080
WS_ADDR=127.0.0.1:9000
# Development mode
REQUIRE_PAYMENT=false
ENABLE_PAYMENT_VERIFICATION=false
# Logging
RUST_LOG=info
```
### Expected Output
```
Starting Gateway Node...
Connecting to Registry at http://127.0.0.1:50050
✓ Connected to Registry
gRPC server listening on 127.0.0.1:50051
HTTP server listening on 127.0.0.1:8080
WebSocket server listening on 127.0.0.1:9000
✓ Gateway ready
```
### Verify Gateway
```bash
# Check HTTP health
curl http://localhost:8080/health
# Check gRPC
grpcurl -plaintext localhost:50051 list
```
***
## Step 3: Start Compute Node
Open a new terminal:
```bash
# Navigate to project root
cd ncn-network-v2-rs
# Start Compute Node
cargo run --bin compute_node -- \
--gateway-addr http://127.0.0.1:50051 \
--model-path ./models
```
### Configuration Options
```bash
cargo run --bin compute_node -- \
--gateway-addr http://127.0.0.1:50051 \
--model-path ./models \
--sandbox-mode disabled \
--execution-timeout 300
```
### Environment Variables
```bash
export SANDBOX_MODE=disabled # For development
export REQUIRE_PAYMENT=false # Skip payment verification
export RUST_LOG=info
```
### Expected Output
```
Starting Compute Node...
Connecting to Gateway at http://127.0.0.1:50051
✓ Registered with Gateway
Waiting for tasks...
```
### Verify Compute Node
The Gateway logs should show:
```
Compute node registered: compute-xxx (wallet: 0x...)
```
***
## Step 4: Run Test Client
Open a new terminal:
```bash
# Navigate to project root
cd ncn-network-v2-rs
# Run test client
cargo run --bin test_client
```
### Expected Output
```
╔════════════════════════════════════════╗
║ NCN Network Test Client ║
╚════════════════════════════════════════╝
Connecting to Gateway at http://127.0.0.1:50051...
✓ Connected to Gateway
📤 Submitting inference request...
Task ID: req-abc123
Status: queued
⏳ Waiting for result...
✓ Received result
Output: [model output data]
✅ Test completed successfully!
```
***
## Local Development Workflow
### Full Stack Command Reference
```bash
# Terminal 1 - Registry
cargo run --bin p2p_registry_node
# Terminal 2 - Gateway
REQUIRE_PAYMENT=false cargo run --bin gateway_node
# Terminal 3 - Compute
SANDBOX_MODE=disabled cargo run --bin compute_node -- \
--gateway-addr http://127.0.0.1:50051
# Terminal 4 - Test Client
cargo run --bin test_client
```
### Using cargo-watch (Auto-Restart)
```bash
# Install cargo-watch
cargo install cargo-watch
# Auto-restart on file changes
cargo watch -x "run --bin gateway_node"
```
***
## Local Blockchain (Optional)
For testing with payments:
### Start Anvil
```bash
# Start local Ethereum node
anvil
# Expected output:
# Available Accounts (10)
# Private Keys (10)
# Listening on 127.0.0.1:8545
```
### Deploy Contracts
```bash
cd contracts
# Deploy to local Anvil
forge script script/Deploy.s.sol \
--rpc-url http://127.0.0.1:8545 \
--broadcast
```
### Configure Gateway for Payments
```bash
# gateway_node/.env
RPC_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x... # From deployment output
REQUIRE_PAYMENT=true
ENABLE_PAYMENT_VERIFICATION=true
GATEWAY_WALLET_PRIVATE_KEY=0x... # Anvil account
```
***
## Port Reference
| Service | Port | Protocol |
| ----------------- | ----- | --------- |
| P2P Registry gRPC | 50050 | gRPC |
| P2P Registry P2P | 8828 | libp2p |
| Gateway gRPC | 50051 | gRPC |
| Gateway HTTP | 8080 | HTTP |
| Gateway WebSocket | 9000 | WebSocket |
| Anvil (optional) | 8545 | JSON-RPC |
***
## Debugging Tips
### Enable Debug Logging
```bash
# All components
export RUST_LOG=debug
# Specific component
export RUST_LOG=gateway_node=debug
# Trace level
export RUST_LOG=trace
```
### Check Service Connectivity
```bash
# Registry health
grpcurl -plaintext localhost:50050 list
# Gateway health
curl http://localhost:8080/health
# Gateway gRPC
grpcurl -plaintext localhost:50051 list
```
### View Active Connections
```bash
# Check listening ports
netstat -tlnp | grep -E "(50050|50051|8080|9000|8828)"
# Or using lsof
lsof -i :50051
```
***
## Common Issues
### "Connection refused" to Registry
```bash
# Ensure Registry is running first
ps aux | grep p2p_registry
# Check port is listening
netstat -tlnp | grep 50050
```
### "No compute nodes available"
* Ensure Compute Node is running
* Check Gateway logs for registration
* Verify model paths exist
### "Sandbox failed" on Compute
```bash
# Disable sandbox for development
export SANDBOX_MODE=disabled
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051
```
### Changes not taking effect
```bash
# Rebuild after changes
cargo build
# Or use cargo-watch
cargo watch -x "run --bin gateway_node"
```
***
## Next Steps
* [Testing](/nc/neurochainai-guides/development/testing) - Run the test suite
* [Debugging](/nc/neurochainai-guides/development/debugging) - Debug issues
* [Docker Deployment](/nc/neurochainai-guides/deployment/docker) - Deploy with Docker
# Testing
Complete guide for running tests in NCN Network v2.
***
## Quick Start
```bash
# Run all tests
cargo test --all
# Run tests with output
cargo test --all -- --nocapture
# Run specific package tests
cargo test -p gateway_node
```
***
## Test Categories
### Unit Tests
Located alongside source code in `src/` directories:
```bash
# Run all unit tests
cargo test --lib --all
# Run specific module tests
cargo test -p gateway_node payment::tests
```
### Integration Tests
Located in `tests/` directories:
```bash
# Run integration tests
cargo test --test '*'
# Run specific integration test
cargo test --test integration_test
```
### Contract Tests
Located in `contracts/test/`:
```bash
cd contracts
# Run all contract tests
forge test -vvv
# Run specific test
forge test --match-test testInitiateInferenceRequest -vvv
# With gas report
forge test --gas-report
```
***
## Running Tests
### All Tests
```bash
# Standard run
cargo test --all
# With verbose output
cargo test --all -- --nocapture
# With logging enabled
RUST_LOG=debug cargo test --all -- --nocapture
```
### By Package
```bash
# Common Types
cargo test -p common_types
# Gateway Node
cargo test -p gateway_node
# Compute Node
cargo test -p compute_node
# P2P Registry
cargo test -p p2p_registry_node
# Test Client
cargo test -p test_client
```
### By Test Name
```bash
# Tests containing "payment"
cargo test payment
# Tests containing "signature"
cargo test signature
# Exact test name
cargo test test_payment_tree_calculation
```
### Ignored Tests
```bash
# Run ignored tests only
cargo test --all -- --ignored
# Run all including ignored
cargo test --all -- --include-ignored
```
***
## Test Configuration
### Environment Variables
```bash
# Enable test logging
export RUST_LOG=debug
export RUST_BACKTRACE=1
# Disable parallelism (for debugging)
export RUST_TEST_THREADS=1
# Run tests
cargo test --all
```
### Test Filters
```bash
# Run tests matching pattern
cargo test payment
# Exclude tests matching pattern
cargo test -- --skip slow_test
# Run only tests in specific module
cargo test gateway_node::payment::
```
***
## Smart Contract Tests
### Foundry Tests
```bash
cd contracts
# Run all tests
forge test
# Verbose output
forge test -vvv
# Very verbose (shows traces)
forge test -vvvv
# Gas report
forge test --gas-report
```
### Specific Contract Tests
```bash
# InferencePayment tests
forge test --match-contract InferencePaymentTest
# Specific test function
forge test --match-test testInitiateInferenceRequest
# With fork
forge test --fork-url $RPC_URL
```
### Test Coverage
```bash
forge coverage
# Output to file
forge coverage --report lcov
```
***
## Integration Testing
### End-to-End Tests
```bash
# Start services first (see running-locally.md)
# Run E2E test script
./scripts/run_e2e_tests.sh
# Or manual E2E test
cargo run --bin test_client
```
### Test with Docker
```bash
# Start test environment
docker-compose -f docker-compose.test.yml up -d
# Run tests against Docker services
TEST_GATEWAY_URL=http://localhost:8080 cargo test --test integration
# Cleanup
docker-compose -f docker-compose.test.yml down
```
***
## Test Writing Guidelines
### Unit Test Example
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_payment_tree_calculation() {
let base_price = 1_000_000_000_000_000_000u128;
let tree = calculate_payment_tree(base_price, 0.10, 0.05, 0.05);
assert_eq!(tree.compute_price_wei, "800000000000000000");
assert_eq!(tree.gateway_gas_wei, "100000000000000000");
}
#[test]
fn test_signature_verification() {
let message = "test message";
let private_key = "0x...";
let signature = sign_message(private_key, message).unwrap();
let valid = verify_signature(message, &signature, expected_address).unwrap();
assert!(valid);
}
#[tokio::test]
async fn test_async_operation() {
let result = async_function().await;
assert!(result.is_ok());
}
}
```
### Integration Test Example
```rust
// tests/integration_test.rs
use common_types::*;
#[tokio::test]
async fn test_full_inference_flow() {
// Setup
let gateway = start_test_gateway().await;
let compute = start_test_compute().await;
// Test
let request = InferenceRequest {
request_id: "test-123".to_string(),
model_uuid: "test_model".to_string(),
input_data: "{}".to_string(),
..Default::default()
};
let response = gateway.submit_task(request).await.unwrap();
// Assert
assert_eq!(response.status, "completed");
// Cleanup
gateway.stop().await;
compute.stop().await;
}
```
### Contract Test Example
```solidity
// contracts/test/InferencePayment.t.sol
contract InferencePaymentTest is Test {
InferencePayment payment;
NCNToken token;
function setUp() public {
token = new NCNToken();
payment = new InferencePayment(address(token), treasury, 3);
}
function testInitiateInferenceRequest() public {
// Setup
bytes32 requestId = keccak256("test");
uint256 amount = 1 ether;
token.approve(address(payment), amount);
// Test
payment.initiateInferenceRequest(
requestId,
gateway,
computeNode,
computePrice,
gatewayGas,
validatorReward,
treasuryFee,
block.timestamp + 1 hours,
signatures
);
// Assert
assertTrue(payment.requestExists(requestId));
}
}
```
***
## Test Utilities
### Test Helpers
```rust
// Common test utilities
#[cfg(test)]
mod test_utils {
pub fn create_test_request() -> InferenceRequest {
InferenceRequest {
request_id: uuid::Uuid::new_v4().to_string(),
model_uuid: "test_model".to_string(),
input_data: "{}".to_string(),
..Default::default()
}
}
pub fn generate_test_wallet() -> (String, String) {
let wallet = LocalWallet::new(&mut rand::thread_rng());
(format!("{:?}", wallet.address()), format!("{:x}", wallet))
}
}
```
### Mock Services
```rust
#[cfg(test)]
pub struct MockGateway {
responses: HashMap,
}
impl MockGateway {
pub fn new() -> Self {
Self { responses: HashMap::new() }
}
pub fn with_response(mut self, request_id: &str, response: InferenceResponse) -> Self {
self.responses.insert(request_id.to_string(), response);
self
}
}
```
***
## CI/CD Testing
### GitHub Actions Example
```yaml
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install protoc
run: sudo apt-get install -y protobuf-compiler
- name: Run tests
run: cargo test --all --verbose
- name: Run clippy
run: cargo clippy --all -- -D warnings
```
***
## Test Coverage
### Generate Coverage Report
```bash
# Install cargo-tarpaulin
cargo install cargo-tarpaulin
# Generate coverage
cargo tarpaulin --all --out Html
# View report
open tarpaulin-report.html
```
### Coverage Targets
| Component | Target Coverage |
| --------------- | --------------- |
| Common Types | 90% |
| Gateway Node | 80% |
| Compute Node | 75% |
| P2P Registry | 80% |
| Smart Contracts | 95% |
***
## Debugging Failed Tests
### Enable Backtrace
```bash
RUST_BACKTRACE=1 cargo test test_name
```
### Run Single Test Verbose
```bash
cargo test test_name -- --nocapture
```
### Run with Logging
```bash
RUST_LOG=trace cargo test test_name -- --nocapture
```
### Debug in IDE
Configure VS Code launch.json:
```json
{
"type": "lldb",
"request": "launch",
"name": "Debug test",
"cargo": {
"args": ["test", "--no-run", "-p", "gateway_node"],
"filter": {
"kind": "test"
}
}
}
```
***
## Next Steps
* [Debugging](/nc/neurochainai-guides/development/debugging) - Debug issues
* [Running Locally](/nc/neurochainai-guides/development/running-locally) - Local development
* [Contributing](/nc/neurochainai-guides/contributing/contributing) - Contribute to tests
# Debugging
Complete guide for debugging NCN Network services and issues.
***
## Quick Reference
```bash
# Enable debug logging
export RUST_LOG=debug
export RUST_BACKTRACE=1
# Run with debug output
cargo run --bin gateway_node
```
***
## Logging
### Log Levels
| Level | Use For |
| ------- | ---------------------------------- |
| `error` | Critical failures |
| `warn` | Warnings, non-critical issues |
| `info` | General operational info (default) |
| `debug` | Detailed debugging info |
| `trace` | Very detailed tracing |
### Configure Logging
```bash
# All components at debug
export RUST_LOG=debug
# Specific component
export RUST_LOG=gateway_node=debug
# Multiple components
export RUST_LOG=gateway_node=debug,compute_node=info
# Specific module
export RUST_LOG=gateway_node::payment=trace
# With dependencies
export RUST_LOG=debug,hyper=warn,tonic=warn
```
### Logging in Code
```rust
use log::{debug, info, warn, error, trace};
fn process_request(req: &InferenceRequest) {
debug!("Processing request: {:?}", req);
if let Err(e) = validate(&req) {
error!("Validation failed: {}", e);
return;
}
info!("Request {} processed successfully", req.request_id);
}
```
***
## Backtraces
### Enable Backtraces
```bash
# Basic backtrace
export RUST_BACKTRACE=1
# Full backtrace
export RUST_BACKTRACE=full
```
### Example Backtrace
```
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value'
stack backtrace:
0: std::panicking::begin_panic
1: core::option::Option::unwrap
2: gateway_node::payment::process_payment
at ./src/payment.rs:42
3: gateway_node::handler::handle_request
at ./src/handler.rs:88
```
***
## Debugging Tools
### GDB/LLDB
```bash
# Build with debug symbols
cargo build
# Run with LLDB (macOS)
lldb ./target/debug/gateway_node
# Run with GDB (Linux)
gdb ./target/debug/gateway_node
# Set breakpoint
(lldb) b gateway_node::payment::process_payment
(lldb) run
```
### VS Code Debugging
`.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"type": "lldb",
"request": "launch",
"name": "Debug Gateway",
"cargo": {
"args": ["build", "--bin=gateway_node"]
},
"args": [],
"cwd": "${workspaceFolder}",
"env": {
"RUST_LOG": "debug",
"RUST_BACKTRACE": "1"
}
},
{
"type": "lldb",
"request": "launch",
"name": "Debug Tests",
"cargo": {
"args": ["test", "--no-run", "-p", "gateway_node"],
"filter": {
"kind": "test"
}
}
}
]
}
```
### rust-analyzer
Enable in VS Code for inline error checking:
```json
{
"rust-analyzer.checkOnSave.command": "clippy"
}
```
***
## Network Debugging
### gRPC Debugging
```bash
# List services
grpcurl -plaintext localhost:50051 list
# Describe service
grpcurl -plaintext localhost:50051 describe common_types.GatewayClientService
# Call method
grpcurl -plaintext \
-d '{"model_uuid": "test", "input_data": "{}"}' \
localhost:50051 common_types.GatewayClientService/SubmitInferenceTask
```
### HTTP Debugging
```bash
# Verbose curl
curl -v http://localhost:8080/health
# With request body
curl -v -X POST http://localhost:8080/api/v1/inference \
-H "Content-Type: application/json" \
-d '{"model_uuid": "test", "input_data": "{}"}'
```
### WebSocket Debugging
```bash
# Install wscat
npm install -g wscat
# Connect
wscat -c ws://localhost:9000
# Send message
{"type": "subscribe", "request_id": "test-123"}
```
### Network Capture
```bash
# Capture gRPC traffic
tcpdump -i lo -w grpc.pcap port 50051
# Analyze with Wireshark
wireshark grpc.pcap
```
***
## Component-Specific Debugging
### Gateway Debugging
```bash
# Full debug logging
RUST_LOG=gateway_node=trace cargo run --bin gateway_node
# Payment module only
RUST_LOG=gateway_node::payment=trace cargo run --bin gateway_node
# Check connections
curl http://localhost:8080/health
```
**Common Issues:**
* Registry connection failed → Check registry is running
* No compute nodes → Check compute node registration
* Payment failed → Check blockchain RPC connectivity
### Compute Node Debugging
```bash
# Full debug with sandbox disabled
RUST_LOG=compute_node=trace \
SANDBOX_MODE=disabled \
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051
# Model execution only
RUST_LOG=compute_node::executor=trace cargo run --bin compute_node
```
**Common Issues:**
* Sandbox failed → Use `SANDBOX_MODE=disabled`
* Model not found → Check `--model-path`
* Gateway connection → Verify gateway is running
### Registry Debugging
```bash
# Full debug logging
RUST_LOG=p2p_registry_node=trace cargo run --bin p2p_registry_node
# P2P networking
RUST_LOG=libp2p=debug,p2p_registry_node=trace cargo run --bin p2p_registry_node
```
**Common Issues:**
* No validators → Check validator registration
* P2P bootstrap → Verify bootstrap node addresses
* Consensus failed → Check minimum validators
***
## Memory Debugging
### Detect Memory Issues
```bash
# Install valgrind (Linux)
sudo apt install valgrind
# Run with valgrind
valgrind --leak-check=full ./target/debug/gateway_node
```
### Heap Profiling
```bash
# Install heaptrack
sudo apt install heaptrack
# Profile
heaptrack ./target/release/gateway_node
# Analyze
heaptrack_gui heaptrack.gateway_node.*.gz
```
***
## Performance Debugging
### CPU Profiling
```bash
# Using perf (Linux)
perf record -g ./target/release/gateway_node
perf report
# Using flamegraph
cargo install flamegraph
cargo flamegraph --bin gateway_node
```
### Timing Analysis
```rust
use std::time::Instant;
fn process_request(req: &InferenceRequest) {
let start = Instant::now();
// ... processing ...
let duration = start.elapsed();
debug!("Request {} processed in {:?}", req.request_id, duration);
}
```
***
## Contract Debugging
### Foundry Debugging
```bash
cd contracts
# Verbose test output
forge test -vvvv
# Debug specific test
forge test --debug testInitiateInferenceRequest
# Gas profiling
forge test --gas-report
```
### Trace Transactions
```bash
# Trace a transaction
cast run --rpc-url $RPC_URL
# Decode call data
cast 4byte-decode
```
***
## Log Analysis
### Search Logs
```bash
# Find errors
grep -i error logs/gateway.log
# Find specific request
grep "req-123" logs/gateway.log
# Tail with filter
tail -f logs/gateway.log | grep -i payment
```
### Structured Logging
Enable JSON logging for analysis:
```bash
export RUST_LOG_FORMAT=json
cargo run --bin gateway_node 2>&1 | jq .
```
***
## Common Debug Scenarios
### Connection Issues
```bash
# Check ports
netstat -tlnp | grep -E "(50050|50051|8080)"
# Check process
ps aux | grep gateway
# Test connectivity
nc -zv localhost 50051
```
### Request Not Processing
```bash
# Enable request tracing
RUST_LOG=gateway_node::handler=trace cargo run --bin gateway_node
# Check request flow
curl -v -X POST http://localhost:8080/api/v1/inference \
-H "Content-Type: application/json" \
-d '{"model_uuid": "test", "input_data": "{}"}'
```
### Signature Verification Failures
```bash
# Enable crypto debugging
RUST_LOG=common_types::crypto=trace cargo run --bin gateway_node
# Check signature format
# Ensure 0x prefix, 65 bytes (130 hex chars + 0x)
```
### Blockchain Issues
```bash
# Test RPC connection
curl -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
# Check contract
cast call $CONTRACT_ADDRESS "minValidatorSignatures()" --rpc-url $RPC_URL
```
***
## Debug Checklist
### Before Reporting Issues
* [ ] Enable debug logging (`RUST_LOG=debug`)
* [ ] Enable backtraces (`RUST_BACKTRACE=1`)
* [ ] Reproduce the issue consistently
* [ ] Capture relevant logs
* [ ] Note environment details (OS, versions)
* [ ] Check for existing issues
### Information to Collect
1. Full error message and backtrace
2. Relevant log output
3. Steps to reproduce
4. Configuration (sanitized)
5. Environment details
***
## Next Steps
* [Testing](/nc/neurochainai-guides/development/testing) - Run tests
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
* [FAQ](/nc/neurochainai-guides/troubleshooting/faq) - Frequently asked questions
# Deployment Overview
Guides for deploying NCN Network in different environments.
***
## Deployment Options
| Option | Best For | Complexity |
| --------------------------------------------------------------------------------------------------- | -------------------- | ---------- |
| [Docker Compose](/nc/neurochainai-guides/deployment/docker) | Development, testing | Low |
| [Manual](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/manual.md) | Custom setups | Medium |
| [Kubernetes](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/kubernetes.md) | Production, scale | High |
***
## Quick Comparison
### Docker Compose
```bash
# Quick start
docker-compose up -d
```
**Pros:**
* Easiest setup
* Good for development
* All services orchestrated
**Cons:**
* Single machine only
* Limited scaling
### Manual Deployment
```bash
# Build and run each component
cargo build --release
./target/release/gateway_node &
./target/release/compute_node &
./target/release/p2p_registry_node &
```
**Pros:**
* Full control
* Custom configuration
**Cons:**
* More setup work
* Manual orchestration
### Kubernetes
```bash
# Deploy with Helm
helm install ncn ./charts/ncn
```
**Pros:**
* Production ready
* Auto-scaling
* High availability
**Cons:**
* Complex setup
* Kubernetes knowledge required
***
## Deployment Guides
### [Docker](/nc/neurochainai-guides/deployment/docker)
Container-based deployment:
* Prerequisites
* Docker Compose setup
* Configuration
* Monitoring
* Troubleshooting
### [Manual](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/manual.md)
Manual deployment on bare metal or VMs:
* System requirements
* Building from source
* Service configuration
* Process management
### [Kubernetes](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/kubernetes.md)
Production deployment on K8s:
* Helm charts
* Resource configuration
* Scaling
* Monitoring
### [Production](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/production.md)
Production considerations:
* Security hardening
* High availability
* Backup/recovery
* Monitoring & alerting
***
## Architecture by Deployment Type
### Development (Single Machine)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Single Machine │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ Registry │ │ Gateway │ │ Compute │ │
│ │ :50050 │ │ :50051/:8080 │ │ │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐│
│ │ Local Blockchain (Anvil) ││
│ └───────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Production (Distributed)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Distributed Setup │
│ │
│ Load Balancer │
│ ┌───────────────────────────────────────────────────────────────────────┐│
│ │ HAProxy/NGINX ││
│ └───────────────────────────────────┬───────────────────────────────────┘│
│ │ │
│ Gateway Cluster │ │
│ ┌───────────────┐ ┌───────────────▼───┐ ┌───────────────┐ │
│ │ Gateway 1 │ │ Gateway 2 │ │ Gateway 3 │ │
│ └───────────────┘ └───────────────────┘ └───────────────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────────┘ │
│ │ │
│ Registry Cluster │ │
│ ┌───────────────┐ ┌───────▼───────────┐ ┌───────────────┐ │
│ │ Registry 1 │◀──│ Registry 2 │──▶│ Registry 3 │ │
│ └───────────────┘ └───────────────────┘ └───────────────┘ │
│ │ │
│ Compute Pool │ │
│ ┌───────────────┐ ┌───────▼───────────┐ ┌───────────────┐ │
│ │ Compute 1 │ │ Compute 2 │ │ Compute N │ │
│ │ (GPU) │ │ (GPU) │ │ (GPU) │ │
│ └───────────────┘ └───────────────────┘ └───────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Prerequisites by Role
### Gateway Server
| Resource | Minimum | Recommended |
| -------- | --------- | ----------- |
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB |
| Storage | 50 GB SSD | 100 GB SSD |
| Network | 100 Mbps | 1 Gbps |
### Compute Server
| Resource | Minimum | Recommended |
| -------- | ---------- | ---------------- |
| CPU | 4 cores | 8+ cores |
| RAM | 8 GB | 32+ GB |
| GPU | Optional | NVIDIA RTX 3080+ |
| Storage | 100 GB SSD | 500 GB NVMe |
| Network | 100 Mbps | 1 Gbps |
### Registry Server
| Resource | Minimum | Recommended |
| -------- | --------- | ----------- |
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB |
| Storage | 50 GB SSD | 100 GB SSD |
| Network | 100 Mbps | 1 Gbps |
***
## Next Steps
Choose your deployment method:
* [Docker Compose](/nc/neurochainai-guides/deployment/docker) - Start here for testing
* [Manual](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/manual.md) - For custom setups
* [Kubernetes](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/kubernetes.md) - For production scale
# Docker Deployment
This guide covers deploying NCN Network v2 using Docker and Docker Compose.
***
## Prerequisites
* Docker 20.10+
* Docker Compose 2.0+
* 8 GB RAM minimum
* 20 GB disk space
### Verify Installation
```bash
docker --version
# Docker version 20.10.x or higher
docker compose version
# Docker Compose version 2.x.x
```
***
## Quick Start
### Start All Services
```bash
cd ncn-network-v2-rs
# Start all services
docker compose up -d
# View logs
docker compose logs -f
# Check status
docker compose ps
```
**Services Started**:
* `ncn-p2p-registry` - P2P Registry on port 50050, 8828
* `ncn-gateway` - Gateway on ports 50051, 8080, 9000
* `ncn-compute-node` - Compute Node
### Stop Services
```bash
# Stop all services
docker compose down
# Stop and remove volumes
docker compose down -v
```
***
## Docker Compose Configuration
### `docker-compose.yml`
```yaml
version: '3.8'
services:
# P2P Registry Node
p2p-registry:
build:
context: .
dockerfile: p2p_registry_node/Dockerfile
container_name: ncn-p2p-registry
ports:
- "50050:50050" # gRPC
- "8828:8828" # P2P
environment:
- RUST_LOG=info,p2p_registry_node=debug
- P2P_LISTEN_ADDR=/ip4/0.0.0.0/tcp/8828
- GRPC_LISTEN_ADDR=0.0.0.0:50050
volumes:
- p2p-data:/data
healthcheck:
test: ["CMD", "nc", "-z", "localhost", "50050"]
interval: 10s
timeout: 5s
retries: 5
# Gateway Node
gateway:
build:
context: .
dockerfile: gateway_node/Dockerfile
container_name: ncn-gateway
ports:
- "50051:50051" # gRPC
- "8080:8080" # HTTP
- "9000:9000" # WebSocket
environment:
- RUST_LOG=info,gateway_node=debug
- GRPC_LISTEN_ADDR=0.0.0.0:50051
- HTTP_LISTEN_ADDR=0.0.0.0:8080
- WS_LISTEN_ADDR=0.0.0.0:9000
- REGISTRY_GRPC_ADDR=http://p2p-registry:50050
- GATEWAY_PRIVATE_KEY=${GATEWAY_PRIVATE_KEY}
- RPC_URL=${RPC_URL:-http://localhost:8545}
- CONTRACT_ADDRESS=${CONTRACT_ADDRESS}
depends_on:
p2p-registry:
condition: service_healthy
volumes:
- gateway-data:/data
# Compute Node
compute-node:
build:
context: .
dockerfile: compute_node/Dockerfile
container_name: ncn-compute-node
environment:
- RUST_LOG=info,compute_node=debug
- GATEWAY_ADDR=http://gateway:50051
- SANDBOX_MODE=${SANDBOX_MODE:-disabled}
- COMPUTE_PRIVATE_KEY=${COMPUTE_PRIVATE_KEY}
volumes:
- compute-models:/models
depends_on:
gateway:
condition: service_healthy
volumes:
p2p-data:
gateway-data:
compute-models:
```
***
## Configuration
### Environment Variables
Create a `.env` file in the project root:
```bash
# Blockchain Configuration
RPC_URL=http://localhost:8545
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
# Gateway Configuration
GATEWAY_PRIVATE_KEY=0x...
# Compute Node Configuration
COMPUTE_PRIVATE_KEY=0x...
SANDBOX_MODE=disabled
# Optional
RUST_LOG=info
```
### Using Environment File
```bash
# Start with custom .env file
docker compose --env-file production.env up -d
```
***
## Building Images
### Build All Images
```bash
docker compose build
```
### Build Individual Images
```bash
# P2P Registry
docker build -t ncn-p2p-registry -f p2p_registry_node/Dockerfile .
# Gateway
docker build -t ncn-gateway -f gateway_node/Dockerfile .
# Compute Node
docker build -t ncn-compute-node -f compute_node/Dockerfile .
```
### Build Arguments
```bash
docker build \
--build-arg RUST_VERSION=1.75 \
--build-arg PROFILE=release \
-t ncn-gateway \
-f gateway_node/Dockerfile .
```
***
## Scaling
### Scale Compute Nodes
```bash
# Run 3 compute nodes
docker compose up -d --scale compute-node=3
# Check all instances
docker compose ps
```
### Using Docker Swarm
```bash
# Initialize swarm
docker swarm init
# Deploy stack
docker stack deploy -c docker-compose.yml ncn
# Scale services
docker service scale ncn_compute-node=5
```
***
## Volumes and Persistence
### Data Volumes
| Volume | Purpose | Location |
| ---------------- | -------------- | --------- |
| `p2p-data` | Registry state | `/data` |
| `gateway-data` | Gateway state | `/data` |
| `compute-models` | AI models | `/models` |
### Mount Models Directory
```yaml
compute-node:
volumes:
- ./local-models:/models:ro
```
### Backup Data
```bash
# Backup p2p data
docker run --rm -v ncn-network-v2-rs_p2p-data:/data -v $(pwd):/backup alpine \
tar -czf /backup/p2p-data-backup.tar.gz /data
# Restore
docker run --rm -v ncn-network-v2-rs_p2p-data:/data -v $(pwd):/backup alpine \
tar -xzf /backup/p2p-data-backup.tar.gz -C /
```
***
## Networking
### Default Network
Docker Compose creates a bridge network:
* Subnet: `172.20.0.0/16`
* Services communicate via service names
### Port Mapping
| Service | Internal | External |
| ----------------- | -------- | -------- |
| P2P Registry gRPC | 50050 | 50050 |
| P2P Registry P2P | 8828 | 8828 |
| Gateway gRPC | 50051 | 50051 |
| Gateway HTTP | 8080 | 8080 |
| Gateway WebSocket | 9000 | 9000 |
### Custom Network
```yaml
networks:
ncn-network:
driver: bridge
ipam:
config:
- subnet: 10.10.0.0/16
```
***
## Health Checks
### Built-in Health Checks
```yaml
healthcheck:
test: ["CMD", "nc", "-z", "localhost", "50050"]
interval: 10s
timeout: 5s
retries: 5
start_period: 15s
```
### Manual Health Check
```bash
# Check gateway health
curl http://localhost:8080/health
# Check container status
docker inspect --format='{{.State.Health.Status}}' ncn-gateway
```
***
## Logging
### View Logs
```bash
# All services
docker compose logs -f
# Specific service
docker compose logs -f gateway
# Last N lines
docker compose logs --tail=100 gateway
```
### Log Configuration
```yaml
gateway:
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "3"
```
### Ship Logs to External Service
```yaml
gateway:
logging:
driver: "fluentd"
options:
fluentd-address: "localhost:24224"
```
***
## Resource Limits
### Set Resource Constraints
```yaml
compute-node:
deploy:
resources:
limits:
cpus: '2'
memory: 4G
reservations:
cpus: '1'
memory: 2G
```
***
## GPU Support
### Enable GPU Access
```yaml
compute-node:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
```
### Verify GPU
```bash
docker exec ncn-compute-node nvidia-smi
```
***
## Monitoring
### Add Prometheus Metrics
```yaml
prometheus:
image: prom/prometheus
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
```
### Prometheus Configuration
```yaml
# prometheus.yml
scrape_configs:
- job_name: 'gateway'
static_configs:
- targets: ['gateway:8080']
```
***
## Troubleshooting
### Container Won't Start
```bash
# View container logs
docker compose logs gateway
# Check container status
docker compose ps -a
# Inspect container
docker inspect ncn-gateway
```
### Network Issues
```bash
# Test connectivity
docker exec ncn-gateway ping p2p-registry
# Check DNS resolution
docker exec ncn-gateway nslookup p2p-registry
```
### Permission Issues
```bash
# Fix volume permissions
sudo chown -R 1000:1000 ./data
```
***
## Production Checklist
* [ ] Use specific image tags, not `latest`
* [ ] Set resource limits
* [ ] Configure logging
* [ ] Enable health checks
* [ ] Use secrets management for private keys
* [ ] Set up monitoring
* [ ] Configure backup strategy
* [ ] Enable TLS for external access
* [ ] Review security settings
***
## Next Steps
* [Production Deployment](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/production.md) - Production considerations
* [Kubernetes Deployment](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/kubernetes.md) - K8s deployment
* [Monitoring Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/monitoring.md) - Set up monitoring
# Manual Deployment
Guide for deploying NCN Network manually on servers without containers.
***
## Prerequisites
* Linux server (Ubuntu 22.04 LTS recommended)
* Root or sudo access
* [Environment setup](/nc/neurochainai-guides/development/environment-setup) completed
* Network access between servers
***
## System Preparation
### Install Dependencies
```bash
# Update system
sudo apt update && sudo apt upgrade -y
# Install build dependencies
sudo apt install -y \
build-essential \
pkg-config \
libssl-dev \
protobuf-compiler \
git \
curl
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source $HOME/.cargo/env
```
### Install Python (for Compute Node)
```bash
sudo apt install -y python3 python3-pip python3-venv
# Create venv
python3 -m venv /opt/ncn/venv
# Install ML dependencies
/opt/ncn/venv/bin/pip install torch transformers numpy scipy
```
***
## Build Binaries
```bash
# Clone repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
# Build release binaries
cargo build --release
# Copy binaries to /opt
sudo mkdir -p /opt/ncn/bin
sudo cp target/release/gateway_node /opt/ncn/bin/
sudo cp target/release/compute_node /opt/ncn/bin/
sudo cp target/release/p2p_registry_node /opt/ncn/bin/
```
***
## Configure Services
### Create Configuration Directory
```bash
sudo mkdir -p /opt/ncn/config
sudo mkdir -p /opt/ncn/data
sudo mkdir -p /opt/ncn/logs
sudo mkdir -p /opt/ncn/models
```
### P2P Registry Configuration
Create `/opt/ncn/config/registry.env`:
```bash
# Listening addresses
GRPC_LISTEN_ADDR=0.0.0.0:50050
P2P_LISTEN_ADDR=/ip4/0.0.0.0/tcp/8828
# Validator settings
VALIDATOR_PRIVATE_KEY=
MIN_VALIDATORS_FOR_CONSENSUS=3
# Blockchain sync
VALIDATOR_SYNC_ENABLED=true
FORKNET_RPC_URL=https://testnet-rpc-1.forknet.io
CHAIN_ID=828
# Logging
RUST_LOG=info
```
### Gateway Configuration
Create `/opt/ncn/config/gateway.env`:
```bash
# Listening addresses
GRPC_ADDR=0.0.0.0:50051
HTTP_ADDR=0.0.0.0:8080
WS_ADDR=0.0.0.0:9000
# Registry connection
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050
# Wallet
GATEWAY_WALLET_PRIVATE_KEY=
GATEWAY_WALLET_ADDRESS=
# Blockchain
RPC_URL=https://testnet-rpc-1.forknet.io
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
CHAIN_ID=828
# Payment settings
REQUIRE_PAYMENT=true
ENABLE_PAYMENT_VERIFICATION=true
# Logging
RUST_LOG=info
```
### Compute Node Configuration
Create `/opt/ncn/config/compute.env`:
```bash
# Gateway connection
GATEWAY_ADDR=http://127.0.0.1:50051
# Node identity
COMPUTE_NODE_PRIVATE_KEY=
NODE_WALLET_ADDRESS=
# Model configuration
MODEL_PATH=/opt/ncn/models
# Execution settings
SANDBOX_MODE=strict
EXECUTION_TIMEOUT_SECS=300
MAX_MEMORY_MB=8192
# Python
PYTHON_PATH=/opt/ncn/venv/bin/python3
PYTHON_VENV_PATH=/opt/ncn/venv
# Logging
RUST_LOG=info
```
***
## Create Systemd Services
### P2P Registry Service
Create `/etc/systemd/system/ncn-registry.service`:
```ini
[Unit]
Description=NCN P2P Registry Node
After=network.target
[Service]
Type=simple
User=ncn
Group=ncn
WorkingDirectory=/opt/ncn
EnvironmentFile=/opt/ncn/config/registry.env
ExecStart=/opt/ncn/bin/p2p_registry_node
Restart=always
RestartSec=10
# Logging
StandardOutput=append:/opt/ncn/logs/registry.log
StandardError=append:/opt/ncn/logs/registry.log
# Security
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/ncn/data /opt/ncn/logs
[Install]
WantedBy=multi-user.target
```
### Gateway Service
Create `/etc/systemd/system/ncn-gateway.service`:
```ini
[Unit]
Description=NCN Gateway Node
After=network.target ncn-registry.service
Wants=ncn-registry.service
[Service]
Type=simple
User=ncn
Group=ncn
WorkingDirectory=/opt/ncn
EnvironmentFile=/opt/ncn/config/gateway.env
ExecStart=/opt/ncn/bin/gateway_node
Restart=always
RestartSec=10
# Logging
StandardOutput=append:/opt/ncn/logs/gateway.log
StandardError=append:/opt/ncn/logs/gateway.log
# Security
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/ncn/data /opt/ncn/logs
[Install]
WantedBy=multi-user.target
```
### Compute Node Service
Create `/etc/systemd/system/ncn-compute.service`:
```ini
[Unit]
Description=NCN Compute Node
After=network.target ncn-gateway.service
Wants=ncn-gateway.service
[Service]
Type=simple
User=ncn
Group=ncn
WorkingDirectory=/opt/ncn
EnvironmentFile=/opt/ncn/config/compute.env
ExecStart=/opt/ncn/bin/compute_node --gateway-addr ${GATEWAY_ADDR} --model-path ${MODEL_PATH}
Restart=always
RestartSec=10
# Logging
StandardOutput=append:/opt/ncn/logs/compute.log
StandardError=append:/opt/ncn/logs/compute.log
# Security (less restrictive for sandbox)
NoNewPrivileges=false
ProtectSystem=false
[Install]
WantedBy=multi-user.target
```
***
## Create Service User
```bash
# Create system user
sudo useradd -r -s /bin/false ncn
# Set ownership
sudo chown -R ncn:ncn /opt/ncn
```
***
## Start Services
```bash
# Reload systemd
sudo systemctl daemon-reload
# Enable services
sudo systemctl enable ncn-registry ncn-gateway ncn-compute
# Start services
sudo systemctl start ncn-registry
sudo systemctl start ncn-gateway
sudo systemctl start ncn-compute
# Check status
sudo systemctl status ncn-registry
sudo systemctl status ncn-gateway
sudo systemctl status ncn-compute
```
***
## Firewall Configuration
```bash
# UFW example
sudo ufw allow 50050/tcp # Registry gRPC
sudo ufw allow 8828/tcp # Registry P2P
sudo ufw allow 50051/tcp # Gateway gRPC
sudo ufw allow 8080/tcp # Gateway HTTP
sudo ufw allow 9000/tcp # Gateway WebSocket
# Or iptables
sudo iptables -A INPUT -p tcp --dport 50050 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8828 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 50051 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 9000 -j ACCEPT
```
***
## Log Management
### View Logs
```bash
# Registry logs
sudo tail -f /opt/ncn/logs/registry.log
# Gateway logs
sudo tail -f /opt/ncn/logs/gateway.log
# Compute logs
sudo tail -f /opt/ncn/logs/compute.log
# Or via journalctl
sudo journalctl -u ncn-gateway -f
```
### Log Rotation
Create `/etc/logrotate.d/ncn`:
```
/opt/ncn/logs/*.log {
daily
rotate 7
compress
delaycompress
missingok
notifempty
create 640 ncn ncn
postrotate
systemctl reload ncn-gateway ncn-registry ncn-compute 2>/dev/null || true
endscript
}
```
***
## Health Checks
### Check Services
```bash
# Service status
sudo systemctl status ncn-registry ncn-gateway ncn-compute
# Health endpoints
curl http://localhost:8080/health
# gRPC connectivity
grpcurl -plaintext localhost:50050 list
grpcurl -plaintext localhost:50051 list
```
***
## Updating
```bash
# Stop services
sudo systemctl stop ncn-compute ncn-gateway ncn-registry
# Update code
cd /path/to/ncn-network-v2-rs
git pull
# Rebuild
cargo build --release
# Copy new binaries
sudo cp target/release/gateway_node /opt/ncn/bin/
sudo cp target/release/compute_node /opt/ncn/bin/
sudo cp target/release/p2p_registry_node /opt/ncn/bin/
# Restart services
sudo systemctl start ncn-registry ncn-gateway ncn-compute
```
***
## Troubleshooting
### Service Won't Start
```bash
# Check logs
sudo journalctl -u ncn-gateway -n 50
# Check permissions
ls -la /opt/ncn/
# Verify binary
/opt/ncn/bin/gateway_node --help
```
### Connection Issues
```bash
# Check ports
sudo netstat -tlnp | grep -E "(50050|50051|8080)"
# Test connectivity
nc -zv localhost 50051
```
***
## Next Steps
* [Production Deployment](/nc/neurochainai-guides/deployment/production) - Production hardening
* [Monitoring](/nc/neurochainai-guides/operators/monitoring) - Set up monitoring
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
# Kubernetes Deployment
Guide for deploying NCN Network on Kubernetes for production scale.
***
## Prerequisites
* Kubernetes cluster (1.25+)
* kubectl configured
* Helm 3.x installed
* Container registry access
***
## Architecture on Kubernetes
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Kubernetes Cluster │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Ingress │ │
│ │ (nginx/traefik) │ │
│ └───────────────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────▼───────────────────────────────────┐ │
│ │ Gateway Service │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Gateway Pod │ │ Gateway Pod │ │ Gateway Pod │ │ │
│ │ │ (replica) │ │ (replica) │ │ (replica) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Registry StatefulSet │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Registry Pod │ │Registry Pod │ │Registry Pod │ │ │
│ │ │ + PVC │ │ + PVC │ │ + PVC │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Compute DaemonSet/Deployment │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Compute Pod │ │Compute Pod │ │Compute Pod │ │ │
│ │ │ (GPU) │ │ (GPU) │ │ (CPU) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Namespace Setup
```yaml
# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: ncn-network
labels:
name: ncn-network
```
```bash
kubectl apply -f namespace.yaml
```
***
## Secrets
```yaml
# secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: ncn-secrets
namespace: ncn-network
type: Opaque
stringData:
gateway-private-key: "0x..."
compute-private-key: "0x..."
validator-private-key: "0x..."
```
```bash
kubectl apply -f secrets.yaml
```
***
## ConfigMaps
```yaml
# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: ncn-config
namespace: ncn-network
data:
RPC_URL: "https://testnet-rpc-1.forknet.io"
CHAIN_ID: "828"
CONTRACT_ADDRESS: "0x4361115359E5C0a25c9b2f8Bb71184F010b768ea"
RUST_LOG: "info"
REQUIRE_PAYMENT: "true"
SANDBOX_MODE: "strict"
```
```bash
kubectl apply -f configmap.yaml
```
***
## P2P Registry StatefulSet
```yaml
# registry-statefulset.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: ncn-registry
namespace: ncn-network
spec:
serviceName: ncn-registry
replicas: 3
selector:
matchLabels:
app: ncn-registry
template:
metadata:
labels:
app: ncn-registry
spec:
containers:
- name: registry
image: your-registry/ncn-registry:latest
ports:
- containerPort: 50050
name: grpc
- containerPort: 8828
name: p2p
env:
- name: GRPC_LISTEN_ADDR
value: "0.0.0.0:50050"
- name: P2P_LISTEN_ADDR
value: "/ip4/0.0.0.0/tcp/8828"
- name: VALIDATOR_PRIVATE_KEY
valueFrom:
secretKeyRef:
name: ncn-secrets
key: validator-private-key
envFrom:
- configMapRef:
name: ncn-config
volumeMounts:
- name: data
mountPath: /data
resources:
requests:
memory: "2Gi"
cpu: "500m"
limits:
memory: "4Gi"
cpu: "2000m"
livenessProbe:
tcpSocket:
port: 50050
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
tcpSocket:
port: 50050
initialDelaySeconds: 5
periodSeconds: 5
volumeClaimTemplates:
- metadata:
name: data
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 10Gi
---
apiVersion: v1
kind: Service
metadata:
name: ncn-registry
namespace: ncn-network
spec:
selector:
app: ncn-registry
ports:
- port: 50050
name: grpc
- port: 8828
name: p2p
clusterIP: None # Headless service for StatefulSet
```
***
## Gateway Deployment
```yaml
# gateway-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ncn-gateway
namespace: ncn-network
spec:
replicas: 3
selector:
matchLabels:
app: ncn-gateway
template:
metadata:
labels:
app: ncn-gateway
spec:
containers:
- name: gateway
image: your-registry/ncn-gateway:latest
ports:
- containerPort: 50051
name: grpc
- containerPort: 8080
name: http
- containerPort: 9000
name: websocket
env:
- name: GRPC_ADDR
value: "0.0.0.0:50051"
- name: HTTP_ADDR
value: "0.0.0.0:8080"
- name: WS_ADDR
value: "0.0.0.0:9000"
- name: REGISTRY_GRPC_ADDR
value: "http://ncn-registry:50050"
- name: GATEWAY_WALLET_PRIVATE_KEY
valueFrom:
secretKeyRef:
name: ncn-secrets
key: gateway-private-key
envFrom:
- configMapRef:
name: ncn-config
resources:
requests:
memory: "2Gi"
cpu: "500m"
limits:
memory: "4Gi"
cpu: "2000m"
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 5
periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
name: ncn-gateway
namespace: ncn-network
spec:
selector:
app: ncn-gateway
ports:
- port: 50051
name: grpc
- port: 8080
name: http
- port: 9000
name: websocket
```
***
## Compute Node Deployment
```yaml
# compute-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ncn-compute
namespace: ncn-network
spec:
replicas: 5
selector:
matchLabels:
app: ncn-compute
template:
metadata:
labels:
app: ncn-compute
spec:
containers:
- name: compute
image: your-registry/ncn-compute:latest
env:
- name: GATEWAY_ADDR
value: "http://ncn-gateway:50051"
- name: MODEL_PATH
value: "/models"
- name: COMPUTE_NODE_PRIVATE_KEY
valueFrom:
secretKeyRef:
name: ncn-secrets
key: compute-private-key
envFrom:
- configMapRef:
name: ncn-config
volumeMounts:
- name: models
mountPath: /models
resources:
requests:
memory: "8Gi"
cpu: "2000m"
nvidia.com/gpu: 1 # For GPU nodes
limits:
memory: "16Gi"
cpu: "4000m"
nvidia.com/gpu: 1
securityContext:
privileged: true # Required for sandbox
volumes:
- name: models
persistentVolumeClaim:
claimName: ncn-models
nodeSelector:
gpu: "true" # Schedule on GPU nodes
tolerations:
- key: nvidia.com/gpu
operator: Exists
effect: NoSchedule
```
***
## Ingress
```yaml
# ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ncn-ingress
namespace: ncn-network
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "100m"
cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
tls:
- hosts:
- api.ncn-network.io
secretName: ncn-tls
rules:
- host: api.ncn-network.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: ncn-gateway
port:
number: 8080
- path: /grpc
pathType: Prefix
backend:
service:
name: ncn-gateway
port:
number: 50051
```
***
## Horizontal Pod Autoscaler
```yaml
# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: ncn-gateway-hpa
namespace: ncn-network
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: ncn-gateway
minReplicas: 3
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: 80
```
***
## Deploy All Resources
```bash
# Apply all manifests
kubectl apply -f namespace.yaml
kubectl apply -f secrets.yaml
kubectl apply -f configmap.yaml
kubectl apply -f registry-statefulset.yaml
kubectl apply -f gateway-deployment.yaml
kubectl apply -f compute-deployment.yaml
kubectl apply -f ingress.yaml
kubectl apply -f hpa.yaml
# Check status
kubectl get pods -n ncn-network
kubectl get services -n ncn-network
kubectl get ingress -n ncn-network
```
***
## Monitoring
### Prometheus ServiceMonitor
```yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: ncn-gateway
namespace: ncn-network
spec:
selector:
matchLabels:
app: ncn-gateway
endpoints:
- port: http
path: /metrics
interval: 30s
```
***
## Helm Chart (Alternative)
If a Helm chart is available:
```bash
# Add repository
helm repo add ncn https://charts.ncn-network.io
helm repo update
# Install
helm install ncn-network ncn/ncn-network \
--namespace ncn-network \
--create-namespace \
--values values.yaml
```
***
## Troubleshooting
### View Logs
```bash
kubectl logs -f deployment/ncn-gateway -n ncn-network
kubectl logs -f statefulset/ncn-registry -n ncn-network
```
### Exec into Pod
```bash
kubectl exec -it deployment/ncn-gateway -n ncn-network -- /bin/bash
```
### Check Events
```bash
kubectl get events -n ncn-network --sort-by='.lastTimestamp'
```
***
## Next Steps
* [Production Deployment](/nc/neurochainai-guides/deployment/production) - Production hardening
* [Monitoring](/nc/neurochainai-guides/operators/monitoring) - Set up monitoring
# Production Deployment
Best practices and considerations for deploying NCN Network in production.
***
## Production Checklist
### Security
* [ ] TLS certificates configured for all endpoints
* [ ] Private keys stored in secure vault (HSM recommended)
* [ ] Firewall rules configured
* [ ] Rate limiting enabled
* [ ] Security audit completed
### Infrastructure
* [ ] High availability setup (multiple replicas)
* [ ] Load balancer configured
* [ ] Auto-scaling enabled
* [ ] Persistent storage for data
* [ ] Backup strategy implemented
### Monitoring
* [ ] Prometheus metrics enabled
* [ ] Grafana dashboards configured
* [ ] Alerting rules set up
* [ ] Log aggregation configured
* [ ] Health checks implemented
### Operations
* [ ] Runbooks documented
* [ ] Incident response plan
* [ ] Update/rollback procedures
* [ ] On-call rotation established
***
## TLS Configuration
### Generate Certificates
```bash
# Using Let's Encrypt with certbot
sudo apt install certbot
sudo certbot certonly --standalone -d api.ncn-network.io
# Certificates will be at:
# /etc/letsencrypt/live/api.ncn-network.io/fullchain.pem
# /etc/letsencrypt/live/api.ncn-network.io/privkey.pem
```
### Configure Gateway TLS
```bash
# gateway.env
TLS_ENABLED=true
TLS_CERT_PATH=/etc/ncn/certs/fullchain.pem
TLS_KEY_PATH=/etc/ncn/certs/privkey.pem
```
### Certificate Renewal
```bash
# Add to crontab
0 0 1 * * certbot renew --quiet && systemctl reload ncn-gateway
```
***
## High Availability
### Gateway HA
```
Load Balancer
┌───────────────────┐
│ HAProxy/NGINX │
│ (health checks) │
└─────────┬─────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Gateway 1 │ │Gateway 2 │ │Gateway 3 │
│ Server A │ │ Server B │ │ Server C │
└──────────┘ └──────────┘ └──────────┘
```
### HAProxy Configuration
```haproxy
# /etc/haproxy/haproxy.cfg
frontend ncn-http
bind *:80
bind *:443 ssl crt /etc/haproxy/certs/ncn.pem
default_backend ncn-gateway
backend ncn-gateway
balance roundrobin
option httpchk GET /health
server gateway1 10.0.1.1:8080 check
server gateway2 10.0.1.2:8080 check
server gateway3 10.0.1.3:8080 check
frontend ncn-grpc
bind *:50051
mode tcp
default_backend ncn-gateway-grpc
backend ncn-gateway-grpc
mode tcp
balance roundrobin
server gateway1 10.0.1.1:50051 check
server gateway2 10.0.1.2:50051 check
server gateway3 10.0.1.3:50051 check
```
***
## Security Hardening
### Firewall Rules
```bash
# Public-facing (Gateway only)
sudo ufw allow 443/tcp # HTTPS
sudo ufw allow 50051/tcp # gRPC (if public)
# Internal only
sudo ufw deny 50050/tcp # Registry gRPC (internal)
sudo ufw deny 8828/tcp # Registry P2P (internal)
# Block all other inbound
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable
```
### Rate Limiting (NGINX)
```nginx
# /etc/nginx/conf.d/rate-limit.conf
limit_req_zone $binary_remote_addr zone=api:10m rate=100r/m;
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
proxy_pass http://ncn-gateway;
}
}
```
### Key Management
**Development:**
* Environment variables (acceptable)
**Staging:**
* Secrets manager (AWS Secrets Manager, HashiCorp Vault)
**Production:**
* Hardware Security Module (HSM)
* Key Management Service (AWS KMS, GCP KMS)
```bash
# Using AWS Secrets Manager
GATEWAY_WALLET_PRIVATE_KEY=$(aws secretsmanager get-secret-value \
--secret-id ncn/gateway-key \
--query SecretString \
--output text)
```
***
## Monitoring Setup
### Prometheus Configuration
```yaml
# prometheus.yml
scrape_configs:
- job_name: 'ncn-gateway'
static_configs:
- targets: ['gateway1:8080', 'gateway2:8080', 'gateway3:8080']
metrics_path: /metrics
- job_name: 'ncn-registry'
static_configs:
- targets: ['registry1:50050', 'registry2:50050', 'registry3:50050']
```
### Key Metrics to Monitor
| Metric | Alert Threshold |
| ------------------- | --------------- |
| Request latency p99 | > 5s |
| Error rate | > 5% |
| CPU usage | > 80% |
| Memory usage | > 85% |
| Disk usage | > 90% |
| Active connections | > 1000 |
### Alerting Rules
```yaml
# alerts.yml
groups:
- name: ncn-alerts
rules:
- alert: HighErrorRate
expr: rate(ncn_requests_failed_total[5m]) / rate(ncn_requests_total[5m]) > 0.05
for: 5m
labels:
severity: critical
annotations:
summary: "High error rate on NCN Gateway"
- alert: HighLatency
expr: histogram_quantile(0.99, rate(ncn_request_duration_seconds_bucket[5m])) > 5
for: 5m
labels:
severity: warning
annotations:
summary: "High latency on NCN Gateway"
```
***
## Backup Strategy
### What to Backup
| Data | Frequency | Retention |
| ------------------- | --------------------- | --------- |
| Configuration files | Daily | 30 days |
| Registry DHT data | Every 6 hours | 7 days |
| Logs | Daily | 90 days |
| Wallet keys | Once (secure offsite) | Forever |
### Backup Script
```bash
#!/bin/bash
# /opt/ncn/scripts/backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/backup/ncn/$DATE
mkdir -p $BACKUP_DIR
# Backup configuration
cp -r /opt/ncn/config $BACKUP_DIR/
# Backup data
tar -czf $BACKUP_DIR/data.tar.gz /opt/ncn/data/
# Upload to S3
aws s3 sync $BACKUP_DIR s3://ncn-backups/$DATE/
# Cleanup old backups
find /backup/ncn -type d -mtime +30 -exec rm -rf {} \;
```
***
## Disaster Recovery
### Recovery Time Objective (RTO)
| Component | RTO |
| --------- | ---------- |
| Gateway | 5 minutes |
| Registry | 15 minutes |
| Compute | 30 minutes |
### Recovery Procedures
**Gateway Failure:**
1. Health check detects failure
2. Load balancer removes from pool
3. Alert sent to ops team
4. Auto-restart or manual intervention
5. Verify health, add back to pool
**Registry Failure:**
1. P2P network continues with remaining nodes
2. Failed node restarts automatically
3. DHT data syncs from peers
4. Verify consensus capability
**Full Cluster Recovery:**
```bash
# 1. Start infrastructure
systemctl start ncn-registry
sleep 30
# 2. Start gateways
systemctl start ncn-gateway
sleep 10
# 3. Start compute nodes
systemctl start ncn-compute
# 4. Verify health
curl http://localhost:8080/health
```
***
## Performance Tuning
### System Limits
```bash
# /etc/security/limits.conf
ncn soft nofile 65535
ncn hard nofile 65535
ncn soft nproc 32768
ncn hard nproc 32768
```
### Kernel Parameters
```bash
# /etc/sysctl.conf
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.ip_local_port_range = 1024 65535
net.ipv4.tcp_tw_reuse = 1
```
### Application Tuning
```bash
# Gateway tuning
TOKIO_WORKER_THREADS=4
HTTP_KEEP_ALIVE_TIMEOUT=60
GRPC_MAX_CONNECTIONS=1000
```
***
## Update Procedures
### Rolling Update
```bash
# 1. Update one gateway at a time
for host in gateway1 gateway2 gateway3; do
ssh $host "systemctl stop ncn-gateway"
ssh $host "cp /tmp/gateway_node /opt/ncn/bin/"
ssh $host "systemctl start ncn-gateway"
sleep 30
# Verify health before continuing
curl -f http://$host:8080/health || exit 1
done
```
### Rollback Procedure
```bash
# Keep previous version
cp /opt/ncn/bin/gateway_node /opt/ncn/bin/gateway_node.backup
# Rollback if needed
systemctl stop ncn-gateway
cp /opt/ncn/bin/gateway_node.backup /opt/ncn/bin/gateway_node
systemctl start ncn-gateway
```
***
## Compliance Considerations
### Data Handling
* Minimize data retention
* Encrypt data at rest
* Log access to sensitive data
* GDPR compliance for EU users
### Audit Logging
```bash
# Enable audit logging
AUDIT_LOG_ENABLED=true
AUDIT_LOG_PATH=/var/log/ncn/audit.log
```
***
## Next Steps
* [Monitoring](/nc/neurochainai-guides/operators/monitoring) - Detailed monitoring setup
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
* [Security](/nc/neurochainai-guides/security/security) - Security documentation
# Operator Guide
Guides for running NCN Network infrastructure nodes.
***
## Overview
NCN Network has three main operator roles:
| Role | Responsibility | Earnings | Requirements |
| ---------------------- | ------------------------------ | --------------- | --------------- |
| **Gateway Operator** | Route requests, manage subnets | Routing fees | Server, wallet |
| **Compute Operator** | Execute AI models | Compute fees | GPU/CPU, models |
| **Validator Operator** | Validate requests | Validation fees | Stake, server |
***
## Operator Guides
### [Gateway Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/gateway-operator.md)
Run a Gateway node:
* Hardware requirements
* Setup and configuration
* Subnet creation
* Monitoring and maintenance
### [Compute Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/compute-operator.md)
Provide compute resources:
* Hardware requirements (GPU/CPU)
* Model preparation
* Joining subnets
* Performance optimization
### [Validator Operator](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/validator-operator.md)
Participate in validation:
* Staking requirements
* Node setup
* Key management
* Slashing avoidance
### [Monitoring](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/monitoring.md)
Set up monitoring:
* Prometheus metrics
* Grafana dashboards
* Alerting
* Log aggregation
***
## Choosing a Role
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Which operator role is right for you? │
│ │
│ Do you have GPU/ML hardware? │
│ │ │
│ ├── Yes ──▶ Consider: Compute Operator │
│ │ Earn fees by executing AI models │
│ │ │
│ └── No │
│ │ │
│ ├── Do you want to curate models? │
│ │ │ │
│ │ ├── Yes ──▶ Consider: Gateway Operator │
│ │ │ Create subnets, route requests │
│ │ │ │
│ │ └── No ──▶ Consider: Validator Operator │
│ │ Stake tokens, validate requests │
│ │ │
│ └── Do you have capital to stake? │
│ │ │
│ ├── Yes ──▶ Validator Operator │
│ │ │
│ └── No ──▶ Start with development/testing │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Requirements Summary
### Gateway Operator
```
Hardware:
├── CPU: 2+ cores
├── RAM: 4 GB
├── Storage: 50 GB
└── Network: 100 Mbps
Software:
├── Linux (recommended)
├── Rust runtime
└── Blockchain access
Capital:
├── Subnet creation fee
└── Gas for transactions
```
### Compute Operator
```
Hardware:
├── CPU: 4+ cores
├── RAM: 8 GB (16 GB recommended)
├── GPU: Optional but recommended
├── Storage: 100 GB
└── Network: 100 Mbps
Software:
├── Linux (required for sandbox)
├── Rust runtime
├── Python 3.8+
└── PyTorch/ML libraries
Capital:
└── None required (optional stake for priority)
```
### Validator Operator
```
Hardware:
├── CPU: 2+ cores
├── RAM: 4 GB
├── Storage: 50 GB
└── Network: 100 Mbps, low latency
Software:
├── Linux (recommended)
├── Rust runtime
└── Blockchain access
Capital:
├── Minimum stake (TBD)
└── Gas for transactions
```
***
## Earnings Potential
| Role | Revenue Source | Typical Earnings\* |
| --------- | ------------------------- | ----------------------------- |
| Gateway | 10% of request fee | Variable by volume |
| Compute | 80% of request fee | Variable by usage |
| Validator | 5% split among validators | Proportional to participation |
\*Actual earnings depend on network activity, pricing, and competition.
***
## Getting Started
### Step 1: Choose Your Role
Review the requirements and choose based on your resources.
### Step 2: Set Up Infrastructure
Follow the appropriate guide:
* [Gateway Setup](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/gateway-operator.md)
* [Compute Setup](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/compute-operator.md)
* [Validator Setup](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/validator-operator.md)
### Step 3: Configure Monitoring
Set up [monitoring](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/monitoring.md) to track performance.
### Step 4: Join the Network
* Connect to testnet first
* Test your setup
* Graduate to mainnet when ready
***
## Common Operations
### All Operators
```bash
# Check status
curl http://localhost:PORT/health
# View logs
tail -f logs/NODE.log
# Update software
git pull && cargo build --release
```
### Gateway Operators
```bash
# Create subnet
subnet-cli create -c subnet_config.json
# List subnets
subnet-cli list
# Check compute nodes
# (via API or logs)
```
### Compute Operators
```bash
# Sync models
cargo run --bin compute_node -- --sync-models
# Check model status
ls -la ./models/
```
### Validator Operators
```bash
# Check stake
cast call $REGISTRY "getValidatorStake(address)" $YOUR_ADDRESS
# Check reputation
# (via API)
```
***
## Support
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
* [FAQ](/nc/neurochainai-guides/troubleshooting/faq) - Frequently asked questions
* Community channels for operator support
# Gateway Operator
Complete guide for running a Gateway node on NCN Network.
***
## Overview
Gateway nodes are the entry points for clients. They:
* Accept inference requests from clients
* Route tasks to compute nodes
* Coordinate payments
* Manage subnet configurations
**Earnings**: \~10% of each inference fee (routing fee)
***
## Requirements
### Hardware
| Resource | Minimum | Recommended |
| -------- | --------- | ----------- |
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB |
| Storage | 50 GB SSD | 100 GB SSD |
| Network | 100 Mbps | 1 Gbps |
### Software
* Linux (Ubuntu 22.04 recommended)
* Rust 1.70+ (for building)
* Network connectivity to blockchain RPC
### Capital
* Subnet creation fee (varies by models)
* Gas for blockchain transactions
* Reserve for operational costs
***
## Setup
### 1. Install Dependencies
```bash
# Update system
sudo apt update && sudo apt upgrade -y
# Install build tools
sudo apt install -y build-essential pkg-config libssl-dev git
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```
### 2. Build Gateway
```bash
# Clone repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
# Build release
cargo build --release -p gateway_node
# Copy binary
sudo cp target/release/gateway_node /usr/local/bin/
```
### 3. Generate Wallet
```bash
# Generate new wallet (or use existing)
# Save the private key securely!
# Using cast (Foundry)
cast wallet new
# Output:
# Address: 0x...
# Private Key: 0x...
```
### 4. Configure Gateway
Create `/etc/ncn/gateway.env`:
```bash
# Network Configuration
REGISTRY_GRPC_ADDR=http://registry.ncn-network.io:50050
RPC_URL=https://testnet-rpc-1.forknet.io
CHAIN_ID=828
# Contract Addresses
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
TOKEN_ADDRESS=0x38E2565e8905BeAf83C34b266592465C22A2f108
# Wallet (SECURE THIS!)
GATEWAY_WALLET_PRIVATE_KEY=0x...
GATEWAY_WALLET_ADDRESS=0x...
# Server Addresses
GRPC_ADDR=0.0.0.0:50051
HTTP_ADDR=0.0.0.0:8080
WS_ADDR=0.0.0.0:9000
# Payment Settings
REQUIRE_PAYMENT=true
ENABLE_PAYMENT_VERIFICATION=true
REQUIRED_CONFIRMATIONS=1
# Transaction Settings
GAS_LIMIT=500000
GAS_PRICE_MULTIPLIER=1.1
# Logging
RUST_LOG=info
```
### 5. Create Systemd Service
Create `/etc/systemd/system/ncn-gateway.service`:
```ini
[Unit]
Description=NCN Gateway Node
After=network.target
[Service]
Type=simple
User=ncn
EnvironmentFile=/etc/ncn/gateway.env
ExecStart=/usr/local/bin/gateway_node
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
### 6. Start Gateway
```bash
# Create service user
sudo useradd -r -s /bin/false ncn
# Set permissions
sudo chown ncn:ncn /etc/ncn/gateway.env
sudo chmod 600 /etc/ncn/gateway.env
# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable ncn-gateway
sudo systemctl start ncn-gateway
# Check status
sudo systemctl status ncn-gateway
```
***
## Create a Subnet
### 1. Prepare Subnet Configuration
Create `subnet_config.json`:
```json
{
"models": [
{
"model_uuid": "bark_semantic",
"source": "huggingface",
"path": "suno/bark",
"name": "Bark Semantic Model",
"category": "audio",
"description": "Text to semantic tokens",
"max_tokens": 1024,
"version": "1.0.0",
"input_format": "json",
"output_format": "json"
},
{
"model_uuid": "bark_coarse",
"source": "huggingface",
"path": "suno/bark",
"name": "Bark Coarse Model",
"category": "audio",
"description": "Semantic to coarse tokens",
"max_tokens": 1024,
"version": "1.0.0",
"input_format": "json",
"output_format": "json"
}
]
}
```
### 2. Estimate Fee
```bash
# Using subnet CLI
cargo run --bin subnet-cli -- estimate -c subnet_config.json
# Output:
# Estimated fee: 0.05 ETH
# Fee quote ID: quote-123
# Valid until: 2024-01-15 10:00:00 UTC
```
### 3. Create Subnet
```bash
# Create subnet (will prompt for payment)
cargo run --bin subnet-cli -- create \
-c subnet_config.json \
--gateway-addr http://127.0.0.1:50051 \
--wallet-key $GATEWAY_WALLET_PRIVATE_KEY
# Output:
# Subnet created!
# Subnet ID: 1
# Models: bark_semantic, bark_coarse
```
***
## Operations
### Monitor Gateway
```bash
# View logs
sudo journalctl -u ncn-gateway -f
# Check health
curl http://localhost:8080/health
# View metrics (if enabled)
curl http://localhost:8080/metrics
```
### View Connected Compute Nodes
```bash
# Check logs for registrations
grep "registered" /var/log/ncn/gateway.log
# Or via API (if implemented)
curl http://localhost:8080/api/v1/nodes
```
### Check Subnet Status
```bash
cargo run --bin subnet-cli -- list --gateway-addr http://127.0.0.1:50051
```
***
## Earnings
### Fee Distribution
For each inference request:
* **10%** goes to Gateway (you)
* **80%** goes to Compute Node
* **5%** goes to Validators
* **5%** goes to Treasury
### Track Earnings
```bash
# Check wallet balance
cast balance $GATEWAY_WALLET_ADDRESS --rpc-url $RPC_URL
# View transaction history
cast logs --from-block latest-1000 \
--address $CONTRACT_ADDRESS \
--rpc-url $RPC_URL
```
***
## Maintenance
### Update Gateway
```bash
# Stop service
sudo systemctl stop ncn-gateway
# Pull updates
cd ncn-network-v2-rs
git pull
# Rebuild
cargo build --release -p gateway_node
# Update binary
sudo cp target/release/gateway_node /usr/local/bin/
# Restart
sudo systemctl start ncn-gateway
```
### Backup Configuration
```bash
# Backup configuration and keys
sudo tar -czf gateway-backup.tar.gz /etc/ncn/
# Store securely offsite
```
### Rotate Keys
```bash
# Generate new wallet
cast wallet new
# Update configuration
sudo nano /etc/ncn/gateway.env
# Restart service
sudo systemctl restart ncn-gateway
```
***
## Troubleshooting
### Gateway Won't Start
```bash
# Check logs
sudo journalctl -u ncn-gateway -n 100
# Common issues:
# - Registry not reachable
# - Invalid private key
# - Port already in use
```
### No Compute Nodes
* Check compute nodes are running
* Verify they're targeting your gateway address
* Check network connectivity
### Payment Issues
* Verify RPC URL is correct
* Check wallet has sufficient balance
* Verify contract address
***
## Security Best Practices
1. **Secure Private Key**
* Use hardware wallet or HSM in production
* Never commit keys to version control
2. **Firewall**
* Only expose necessary ports
* Use TLS for production
3. **Monitoring**
* Set up alerts for anomalies
* Monitor for unauthorized access
***
## Next Steps
* [Monitoring](/nc/neurochainai-guides/operators/monitoring) - Set up monitoring
* [Production Deployment](/nc/neurochainai-guides/deployment/production) - Production hardening
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
# Compute Operator
Complete guide for running a Compute node on NCN Network.
***
## Overview
Compute nodes execute AI models for inference requests. They:
* Execute models in secure sandboxes
* Sign computation results
* Receive payment for completed tasks
**Earnings**: \~80% of each inference fee
***
## Requirements
### Hardware
| Resource | Minimum | Recommended |
| -------- | ---------- | ---------------- |
| CPU | 4 cores | 8+ cores |
| RAM | 8 GB | 32 GB |
| GPU | Optional | NVIDIA RTX 3080+ |
| Storage | 100 GB SSD | 500 GB NVMe |
| Network | 100 Mbps | 1 Gbps |
### Software
* Linux (Ubuntu 22.04 required for sandbox)
* Rust 1.70+
* Python 3.8+
* PyTorch / Transformers
### GPU Setup (Optional but Recommended)
```bash
# Install NVIDIA drivers
sudo apt install nvidia-driver-535
# Install CUDA toolkit
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.0-1_all.deb
sudo dpkg -i cuda-keyring_1.0-1_all.deb
sudo apt update
sudo apt install cuda
# Verify
nvidia-smi
```
***
## Setup
### 1. Install Dependencies
```bash
# Update system
sudo apt update && sudo apt upgrade -y
# Install build tools
sudo apt install -y \
build-essential \
pkg-config \
libssl-dev \
git \
python3 \
python3-pip \
python3-venv
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```
### 2. Build Compute Node
```bash
# Clone repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
# Build release
cargo build --release -p compute_node
# Copy binary
sudo cp target/release/compute_node /usr/local/bin/
```
### 3. Set Up Python Environment
```bash
# Create virtual environment
sudo mkdir -p /opt/ncn
python3 -m venv /opt/ncn/venv
# Install dependencies
/opt/ncn/venv/bin/pip install --upgrade pip
/opt/ncn/venv/bin/pip install torch transformers numpy scipy
```
### 4. Generate Wallet
```bash
# Generate new wallet (or use existing)
cast wallet new
# Output:
# Address: 0x...
# Private Key: 0x...
```
### 5. Configure Compute Node
Create `/etc/ncn/compute.env`:
```bash
# Gateway Connection
GATEWAY_ADDR=http://gateway.ncn-network.io:50051
# Wallet
COMPUTE_NODE_PRIVATE_KEY=0x...
NODE_WALLET_ADDRESS=0x...
# Model Configuration
MODEL_PATH=/opt/ncn/models
# Python Configuration
PYTHON_PATH=/opt/ncn/venv/bin/python3
PYTHON_VENV_PATH=/opt/ncn/venv
# Sandbox Settings
SANDBOX_MODE=strict
EXECUTION_TIMEOUT_SECS=300
MAX_MEMORY_MB=8192
# Logging
RUST_LOG=info
```
### 6. Create Systemd Service
Create `/etc/systemd/system/ncn-compute.service`:
```ini
[Unit]
Description=NCN Compute Node
After=network.target
[Service]
Type=simple
User=root # Required for sandbox
EnvironmentFile=/etc/ncn/compute.env
ExecStart=/usr/local/bin/compute_node --gateway-addr ${GATEWAY_ADDR} --model-path ${MODEL_PATH}
Restart=always
RestartSec=10
# Sandbox requires elevated privileges
AmbientCapabilities=CAP_SYS_ADMIN CAP_NET_ADMIN
[Install]
WantedBy=multi-user.target
```
### 7. Start Compute Node
```bash
# Set permissions
sudo chmod 600 /etc/ncn/compute.env
# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable ncn-compute
sudo systemctl start ncn-compute
# Check status
sudo systemctl status ncn-compute
```
***
## Download Models
### Manual Download
```bash
# Create models directory
sudo mkdir -p /opt/ncn/models
# Download from Hugging Face
/opt/ncn/venv/bin/python3 << 'EOF'
from transformers import AutoModel, AutoTokenizer
import torch
# Download Bark models (example)
model = AutoModel.from_pretrained("suno/bark")
model.save_pretrained("/opt/ncn/models/bark")
EOF
```
### Using sync-models (Automatic)
```bash
# Enable model sync in config
SYNC_MODELS=true
# Start compute node with sync
cargo run --bin compute_node -- \
--gateway-addr http://gateway:50051 \
--sync-models
```
### Model Directory Structure
```
/opt/ncn/models/
├── bark_semantic/
│ ├── config.json
│ ├── model.pt
│ └── tokenizer.json
├── bark_coarse/
│ └── ...
└── bark_fine/
└── ...
```
***
## Operations
### Monitor Compute Node
```bash
# View logs
sudo journalctl -u ncn-compute -f
# Check if registered with gateway
grep "registered" /var/log/ncn/compute.log
```
### View Task Execution
```bash
# Watch for tasks
sudo journalctl -u ncn-compute -f | grep -E "(task|execution)"
```
### Check Resource Usage
```bash
# CPU/Memory
htop
# GPU usage
nvidia-smi -l 1
# Disk usage
df -h /opt/ncn/models
```
***
## Sandbox Configuration
### Sandbox Modes
| Mode | Description | Use Case |
| ------------ | -------------- | ---------------- |
| `strict` | Full isolation | Production |
| `permissive` | Relaxed rules | Testing |
| `disabled` | No sandbox | Development only |
### Strict Mode Features
* **seccomp**: Syscall filtering
* **Namespaces**: PID, network, mount isolation
* **Landlock**: Filesystem access control
* **Resource limits**: CPU, memory, time
### Troubleshooting Sandbox
```bash
# Run with permissive mode for debugging
SANDBOX_MODE=permissive cargo run --bin compute_node
# Check kernel features
cat /boot/config-$(uname -r) | grep -E "(SECCOMP|LANDLOCK|NAMESPACES)"
```
***
## Earnings
### Fee Distribution
For each completed inference:
* **80%** goes to Compute Node (you)
* **10%** goes to Gateway
* **5%** goes to Validators
* **5%** goes to Treasury
### Track Earnings
```bash
# Check wallet balance
cast balance $NODE_WALLET_ADDRESS --rpc-url https://testnet-rpc-1.forknet.io
# View completed tasks (from logs)
grep "completed" /var/log/ncn/compute.log | wc -l
```
***
## Performance Optimization
### GPU Optimization
```bash
# Set CUDA visible devices
export CUDA_VISIBLE_DEVICES=0
# Use TensorFloat-32
export TF32_OVERRIDE=1
```
### CPU Optimization
```bash
# Set thread affinity
taskset -c 0-7 compute_node ...
# Increase file descriptors
ulimit -n 65535
```
### Memory Management
```bash
# Monitor memory usage
watch -n 1 "free -h && nvidia-smi"
# Set memory limits
MAX_MEMORY_MB=16384
```
***
## Maintenance
### Update Compute Node
```bash
# Stop service
sudo systemctl stop ncn-compute
# Pull updates
cd ncn-network-v2-rs
git pull
# Rebuild
cargo build --release -p compute_node
# Update binary
sudo cp target/release/compute_node /usr/local/bin/
# Restart
sudo systemctl start ncn-compute
```
### Update Python Dependencies
```bash
/opt/ncn/venv/bin/pip install --upgrade torch transformers
```
### Update Models
```bash
# Manually or with sync
cargo run --bin compute_node -- --sync-models --gateway-addr ...
```
***
## Troubleshooting
### "Sandbox execution failed"
```bash
# Check kernel support
uname -r # Must be 5.13+ for Landlock
# Try permissive mode
SANDBOX_MODE=permissive
# Check logs for specific error
journalctl -u ncn-compute -n 50
```
### "Model not found"
* Verify model path exists
* Check file permissions
* Ensure model is downloaded
### "Gateway connection failed"
* Check gateway address
* Verify network connectivity
* Check firewall rules
### "Out of memory"
* Increase MAX\_MEMORY\_MB
* Reduce model batch size
* Add more RAM/swap
***
## Security Best Practices
1. **Keep Sandbox Enabled**
* Always use `strict` mode in production
2. **Secure Private Key**
* Store in secure location
* Use different key than personal wallet
3. **Monitor for Anomalies**
* Watch for unusual resource usage
* Alert on failed executions
4. **Regular Updates**
* Keep system packages updated
* Update models regularly
***
## Next Steps
* [Monitoring](/nc/neurochainai-guides/operators/monitoring) - Set up monitoring
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
* [Security](/nc/neurochainai-guides/security/security) - Security documentation
# Validator Operator
Complete guide for running a Validator on NCN Network.
***
## Overview
Validators participate in the consensus mechanism by:
* Validating preprocessing requests
* Validating completion results
* Signing consensus messages
* Maintaining network integrity
**Earnings**: Share of \~5% validator fee per inference
***
## Requirements
### Hardware
| Resource | Minimum | Recommended |
| -------- | --------------------- | ----------- |
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB |
| Storage | 50 GB SSD | 100 GB SSD |
| Network | 100 Mbps, low latency | 1 Gbps |
### Capital
* Minimum stake (configurable, check network)
* Gas for registration transactions
### Network
* Stable, low-latency connection
* P2P port (8828) accessible
***
## Setup
### 1. Install Dependencies
```bash
# Update system
sudo apt update && sudo apt upgrade -y
# Install build tools
sudo apt install -y build-essential pkg-config libssl-dev git
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```
### 2. Build Registry Node
```bash
# Clone repository
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
# Build release
cargo build --release -p p2p_registry_node
# Copy binary
sudo cp target/release/p2p_registry_node /usr/local/bin/
```
### 3. Generate Validator Key
```bash
# Generate new wallet for validation
cast wallet new
# Output:
# Address: 0x...
# Private Key: 0x...
# IMPORTANT: Save this key securely!
```
### 4. Stake Tokens (On-Chain)
```bash
# Approve tokens for staking
cast send $TOKEN_ADDRESS \
"approve(address,uint256)" \
$VALIDATOR_REGISTRY_ADDRESS \
$STAKE_AMOUNT \
--private-key $YOUR_KEY \
--rpc-url $RPC_URL
# Register as validator
cast send $VALIDATOR_REGISTRY_ADDRESS \
"registerValidator(uint256)" \
$STAKE_AMOUNT \
--private-key $YOUR_KEY \
--rpc-url $RPC_URL
```
### 5. Configure Validator
Create `/etc/ncn/validator.env`:
```bash
# Validator Identity
VALIDATOR_PRIVATE_KEY=0x...
VALIDATOR_ADDRESS=0x...
# Network Addresses
GRPC_LISTEN_ADDR=0.0.0.0:50050
P2P_LISTEN_ADDR=/ip4/0.0.0.0/tcp/8828
# Bootstrap Nodes (get from network)
BOOTSTRAP_NODES=/ip4/x.x.x.x/tcp/8828/p2p/12D3KooW...
# Blockchain Configuration
FORKNET_RPC_URL=https://testnet-rpc-1.forknet.io
CHAIN_ID=828
VALIDATOR_REGISTRY_CONTRACT=0x4F11D4cBE08A5aBa052C368C8477412af63a56f3
# Sync Settings
VALIDATOR_SYNC_ENABLED=true
VALIDATOR_SYNC_INTERVAL=60
# Consensus Settings
MIN_VALIDATORS_FOR_CONSENSUS=3
# Logging
RUST_LOG=info
```
### 6. Create Systemd Service
Create `/etc/systemd/system/ncn-validator.service`:
```ini
[Unit]
Description=NCN Validator (P2P Registry) Node
After=network.target
[Service]
Type=simple
User=ncn
EnvironmentFile=/etc/ncn/validator.env
ExecStart=/usr/local/bin/p2p_registry_node \
--grpc-listen-addr ${GRPC_LISTEN_ADDR} \
--p2p-listen-addr ${P2P_LISTEN_ADDR}
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
### 7. Start Validator
```bash
# Create service user
sudo useradd -r -s /bin/false ncn
# Set permissions
sudo mkdir -p /etc/ncn
sudo chown ncn:ncn /etc/ncn/validator.env
sudo chmod 600 /etc/ncn/validator.env
# Create data directory
sudo mkdir -p /opt/ncn/data
sudo chown ncn:ncn /opt/ncn/data
# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable ncn-validator
sudo systemctl start ncn-validator
# Check status
sudo systemctl status ncn-validator
```
***
## Validator Registration Flow
```
1. Generate validator wallet
│
▼
2. Acquire NCN tokens (testnet faucet or purchase)
│
▼
3. Approve tokens for registry contract
│
▼
4. Call registerValidator() with stake amount
│
▼
5. Start validator node with same private key
│
▼
6. Node syncs with network and joins validator pool
│
▼
7. Start receiving validation requests
```
***
## Operations
### Monitor Validator
```bash
# View logs
sudo journalctl -u ncn-validator -f
# Check peer connections
grep "peer" /var/log/ncn/validator.log
# Check validation activity
grep "validation" /var/log/ncn/validator.log
```
### Check Validator Status
```bash
# On-chain status
cast call $VALIDATOR_REGISTRY_CONTRACT \
"getValidatorInfo(address)" \
$VALIDATOR_ADDRESS \
--rpc-url $RPC_URL
# Check if active
cast call $VALIDATOR_REGISTRY_CONTRACT \
"isActiveValidator(address)" \
$VALIDATOR_ADDRESS \
--rpc-url $RPC_URL
```
### View Reputation
```bash
# Check reputation score
cast call $VALIDATOR_REGISTRY_CONTRACT \
"getValidatorReputation(address)" \
$VALIDATOR_ADDRESS \
--rpc-url $RPC_URL
```
***
## Earnings
### Fee Distribution
For each validated inference:
* **5%** total goes to validators
* Split among participating validators
* More validations = more earnings
### Track Earnings
```bash
# Check wallet balance
cast balance $VALIDATOR_ADDRESS --rpc-url $RPC_URL
# View validation count (from logs)
grep "validation successful" /var/log/ncn/validator.log | wc -l
```
***
## Reputation System
### How Reputation Works
| Action | Impact |
| --------------------- | ---------- |
| Successful validation | +1 point |
| Failed validation | -2 points |
| Timeout (no response) | -5 points |
| Slashing event | -20 points |
### Maintain High Reputation
1. **Stay Online**: Maximize uptime
2. **Fast Response**: Low-latency connection
3. **Honest Behavior**: Never sign invalid results
4. **Regular Updates**: Keep software current
### Check Reputation
```bash
# Minimum reputation required
MIN_REPUTATION=20
# Your reputation
cast call $VALIDATOR_REGISTRY_CONTRACT \
"getValidatorReputation(address)" \
$VALIDATOR_ADDRESS \
--rpc-url $RPC_URL
```
***
## Avoiding Slashing
### Slashable Offenses
| Offense | Penalty |
| ------------------------ | ---------- |
| Invalid signature | 50% stake |
| Approving invalid result | 30% stake |
| Collusion | 100% stake |
| Prolonged downtime | 10% stake |
### Best Practices
1. **Secure Key**: Protect validator private key
2. **Monitor Health**: Set up alerting
3. **Redundancy**: Consider backup infrastructure
4. **Stay Updated**: Apply security patches
***
## Network Participation
### Bootstrap Nodes
Connect to existing validators:
```bash
# In validator.env
BOOTSTRAP_NODES=/ip4/192.168.1.100/tcp/8828/p2p/12D3KooWA...
```
### Peer Discovery
The P2P network uses Kademlia DHT:
* Automatic peer discovery
* Distributed state replication
* Fault-tolerant messaging
### Check Peers
```bash
# In logs
grep "Connected to peer" /var/log/ncn/validator.log
# Expected: 5-10+ peers for healthy network
```
***
## Maintenance
### Update Validator
```bash
# Stop service
sudo systemctl stop ncn-validator
# Pull updates
cd ncn-network-v2-rs
git pull
# Rebuild
cargo build --release -p p2p_registry_node
# Update binary
sudo cp target/release/p2p_registry_node /usr/local/bin/
# Restart
sudo systemctl start ncn-validator
```
### Add/Withdraw Stake
```bash
# Add more stake
cast send $VALIDATOR_REGISTRY_CONTRACT \
"addStake(uint256)" \
$ADDITIONAL_AMOUNT \
--private-key $YOUR_KEY \
--rpc-url $RPC_URL
# Withdraw (may have cooldown)
cast send $VALIDATOR_REGISTRY_CONTRACT \
"withdrawStake(uint256)" \
$WITHDRAW_AMOUNT \
--private-key $YOUR_KEY \
--rpc-url $RPC_URL
```
### Unregister Validator
```bash
# Unregister and withdraw all stake
cast send $VALIDATOR_REGISTRY_CONTRACT \
"unregisterValidator()" \
--private-key $YOUR_KEY \
--rpc-url $RPC_URL
```
***
## Troubleshooting
### "No peers found"
* Check bootstrap nodes are correct
* Verify P2P port (8828) is open
* Check network connectivity
### "Consensus failed"
* Not enough validators online
* Check minimum validators setting
* Verify network health
### "Slashed"
* Review logs for violation
* May need to add more stake
* Contact community for appeal
***
## Security Best Practices
1. **Secure Validator Key**
* Use HSM for production
* Never share private key
2. **Firewall**
* Only expose necessary ports (8828, 50050)
* Use fail2ban for brute force protection
3. **Monitoring**
* Alert on reputation drops
* Monitor for slashing events
4. **Redundancy**
* Consider backup node
* Document recovery procedures
***
## Next Steps
* [Monitoring](/nc/neurochainai-guides/operators/monitoring) - Set up monitoring
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
* [Security](/nc/neurochainai-guides/security/security) - Security documentation
# Monitoring
Complete guide for monitoring NCN Network services.
***
## Overview
Effective monitoring includes:
* **Metrics**: Numerical data (latency, throughput, errors)
* **Logs**: Event records and debugging info
* **Alerts**: Notifications for issues
* **Dashboards**: Visual status overview
***
## Prometheus Setup
### Install Prometheus
```bash
# Download Prometheus
wget https://github.com/prometheus/prometheus/releases/download/v2.48.0/prometheus-2.48.0.linux-amd64.tar.gz
tar xvfz prometheus-*.tar.gz
sudo mv prometheus-*/prometheus /usr/local/bin/
sudo mv prometheus-*/promtool /usr/local/bin/
```
### Configure Prometheus
Create `/etc/prometheus/prometheus.yml`:
```yaml
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'ncn-gateway'
static_configs:
- targets: ['localhost:8080']
metrics_path: /metrics
- job_name: 'ncn-registry'
static_configs:
- targets: ['localhost:50050']
metrics_path: /metrics
- job_name: 'node-exporter'
static_configs:
- targets: ['localhost:9100']
alerting:
alertmanagers:
- static_configs:
- targets: ['localhost:9093']
rule_files:
- /etc/prometheus/rules/*.yml
```
### Start Prometheus
```bash
prometheus --config.file=/etc/prometheus/prometheus.yml
```
***
## Key Metrics
### Gateway Metrics
| Metric | Type | Description |
| ------------------------------ | --------- | ------------------------ |
| `ncn_requests_total` | Counter | Total requests |
| `ncn_requests_failed_total` | Counter | Failed requests |
| `ncn_request_duration_seconds` | Histogram | Request latency |
| `ncn_active_connections` | Gauge | Active connections |
| `ncn_compute_nodes_registered` | Gauge | Registered compute nodes |
### Registry Metrics
| Metric | Type | Description |
| ----------------------------- | ------- | -------------------- |
| `ncn_validators_active` | Gauge | Active validators |
| `ncn_validations_total` | Counter | Total validations |
| `ncn_consensus_reached_total` | Counter | Successful consensus |
| `ncn_mempool_size` | Gauge | Pending requests |
| `ncn_p2p_peers` | Gauge | Connected peers |
### Compute Metrics
| Metric | Type | Description |
| --------------------------- | --------- | ------------------- |
| `ncn_tasks_completed_total` | Counter | Completed tasks |
| `ncn_task_duration_seconds` | Histogram | Task execution time |
| `ncn_gpu_utilization` | Gauge | GPU usage |
| `ncn_memory_used_bytes` | Gauge | Memory usage |
***
## Grafana Dashboards
### Install Grafana
```bash
# Add repository
sudo apt-get install -y software-properties-common
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main"
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
sudo apt-get update
sudo apt-get install grafana
# Start Grafana
sudo systemctl start grafana-server
sudo systemctl enable grafana-server
```
### Access Grafana
* URL:
* Default credentials: admin/admin
### NCN Dashboard JSON
Create dashboard with panels:
```json
{
"title": "NCN Network Overview",
"panels": [
{
"title": "Request Rate",
"type": "graph",
"targets": [
{
"expr": "rate(ncn_requests_total[5m])",
"legendFormat": "{{instance}}"
}
]
},
{
"title": "Error Rate",
"type": "graph",
"targets": [
{
"expr": "rate(ncn_requests_failed_total[5m]) / rate(ncn_requests_total[5m]) * 100",
"legendFormat": "Error %"
}
]
},
{
"title": "P99 Latency",
"type": "graph",
"targets": [
{
"expr": "histogram_quantile(0.99, rate(ncn_request_duration_seconds_bucket[5m]))",
"legendFormat": "p99"
}
]
},
{
"title": "Active Validators",
"type": "stat",
"targets": [
{
"expr": "ncn_validators_active"
}
]
},
{
"title": "Compute Nodes",
"type": "stat",
"targets": [
{
"expr": "ncn_compute_nodes_registered"
}
]
}
]
}
```
***
## Alerting
### Alert Rules
Create `/etc/prometheus/rules/ncn-alerts.yml`:
```yaml
groups:
- name: ncn-critical
rules:
- alert: HighErrorRate
expr: rate(ncn_requests_failed_total[5m]) / rate(ncn_requests_total[5m]) > 0.05
for: 5m
labels:
severity: critical
annotations:
summary: "High error rate on NCN Gateway"
description: "Error rate is {{ $value | humanizePercentage }}"
- alert: GatewayDown
expr: up{job="ncn-gateway"} == 0
for: 1m
labels:
severity: critical
annotations:
summary: "NCN Gateway is down"
- alert: NoComputeNodes
expr: ncn_compute_nodes_registered == 0
for: 5m
labels:
severity: critical
annotations:
summary: "No compute nodes registered"
- name: ncn-warning
rules:
- alert: HighLatency
expr: histogram_quantile(0.99, rate(ncn_request_duration_seconds_bucket[5m])) > 5
for: 5m
labels:
severity: warning
annotations:
summary: "High latency on NCN Gateway"
description: "P99 latency is {{ $value }}s"
- alert: LowValidators
expr: ncn_validators_active < 5
for: 10m
labels:
severity: warning
annotations:
summary: "Low number of active validators"
- alert: HighMemoryUsage
expr: (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes > 0.85
for: 5m
labels:
severity: warning
annotations:
summary: "High memory usage"
```
### Alertmanager Configuration
Create `/etc/alertmanager/alertmanager.yml`:
```yaml
global:
resolve_timeout: 5m
route:
group_by: ['alertname', 'severity']
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
receiver: 'default'
routes:
- match:
severity: critical
receiver: 'critical'
receivers:
- name: 'default'
email_configs:
- to: 'ops@example.com'
from: 'alerts@ncn-network.io'
smarthost: 'smtp.example.com:587'
- name: 'critical'
slack_configs:
- api_url: 'https://hooks.slack.com/services/xxx'
channel: '#alerts-critical'
pagerduty_configs:
- service_key: 'xxx'
```
***
## Log Aggregation
### Using Loki + Promtail
```yaml
# promtail-config.yml
server:
http_listen_port: 9080
positions:
filename: /tmp/positions.yaml
clients:
- url: http://loki:3100/loki/api/v1/push
scrape_configs:
- job_name: ncn-gateway
static_configs:
- targets:
- localhost
labels:
job: ncn-gateway
__path__: /var/log/ncn/gateway.log
- job_name: ncn-registry
static_configs:
- targets:
- localhost
labels:
job: ncn-registry
__path__: /var/log/ncn/registry.log
- job_name: ncn-compute
static_configs:
- targets:
- localhost
labels:
job: ncn-compute
__path__: /var/log/ncn/compute.log
```
### Log Queries (LogQL)
```logql
# Error logs
{job="ncn-gateway"} |= "error"
# Slow requests
{job="ncn-gateway"} | json | duration > 5s
# Failed validations
{job="ncn-registry"} |= "validation failed"
```
***
## Health Checks
### HTTP Health Check
```bash
# Gateway health
curl -f http://localhost:8080/health || echo "Gateway unhealthy"
# Expected response
{
"status": "healthy",
"version": "0.1.0",
"uptime_seconds": 3600
}
```
### Custom Health Script
Create `/opt/ncn/health-check.sh`:
```bash
#!/bin/bash
# Check gateway
if ! curl -sf http://localhost:8080/health > /dev/null; then
echo "Gateway unhealthy"
exit 1
fi
# Check registry
if ! nc -z localhost 50050; then
echo "Registry unhealthy"
exit 1
fi
# Check compute (optional)
if systemctl is-active --quiet ncn-compute; then
echo "All services healthy"
exit 0
else
echo "Compute node not running"
exit 1
fi
```
### Systemd Health Integration
```ini
[Service]
ExecStartPost=/opt/ncn/health-check.sh
```
***
## Uptime Monitoring
### External Monitoring
Use services like:
* Uptime Robot
* Pingdom
* Better Uptime
Configure to monitor:
* `https://api.ncn-network.io/health`
* Expected response code: 200
* Check interval: 1 minute
***
## Resource Monitoring
### Node Exporter
```bash
# Install node exporter
wget https://github.com/prometheus/node_exporter/releases/download/v1.7.0/node_exporter-1.7.0.linux-amd64.tar.gz
tar xvfz node_exporter-*.tar.gz
sudo mv node_exporter-*/node_exporter /usr/local/bin/
# Run as service
sudo systemctl start node_exporter
```
### GPU Monitoring (NVIDIA)
```bash
# Install DCGM exporter for GPU metrics
docker run -d --gpus all \
-p 9400:9400 \
nvidia/dcgm-exporter
```
***
## Dashboard Examples
### Key Dashboard Panels
1. **Overview**
* Request rate
* Error rate
* Active nodes
2. **Performance**
* Latency percentiles
* Throughput
* Queue depth
3. **Resources**
* CPU usage
* Memory usage
* Disk I/O
* Network I/O
4. **Validators**
* Active validators
* Consensus success rate
* Reputation distribution
***
## Best Practices
1. **Retention**
* Metrics: 15-30 days
* Logs: 90 days
* Alerts history: 1 year
2. **Alerting**
* Alert on symptoms, not causes
* Have actionable runbooks
* Avoid alert fatigue
3. **Dashboards**
* Start with high-level overview
* Drill-down capability
* Include links to runbooks
4. **On-Call**
* Define escalation paths
* Regular rotation
* Post-incident reviews
***
## Next Steps
* [Production Deployment](/nc/neurochainai-guides/deployment/production) - Production setup
* [Troubleshooting](/nc/neurochainai-guides/troubleshooting/troubleshooting) - Common issues
# Client Integration
Guides for integrating applications with NCN Network.
***
## Overview
NCN Network provides multiple interfaces for client integration:
| Interface | Best For | Documentation |
| ------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **gRPC** | High-performance, streaming | [gRPC Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/grpc-client.md) |
| **HTTP REST** | Simple integrations, web apps | [HTTP Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/http-client.md) |
| **WebSocket** | Real-time updates | [WebSocket Events](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/websocket-events.md) |
***
## Client Guides
### [gRPC Client](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/grpc-client.md)
High-performance gRPC integration:
* Protobuf code generation
* Connection setup
* Request submission
* Streaming responses
### [HTTP Client](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/http-client.md)
Simple REST API integration:
* Endpoint reference
* Request/response formats
* Error handling
### [Payment Integration](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/payment-integration.md)
Blockchain payment flow:
* Wallet setup
* Payment submission
* Confirmation handling
### [Examples](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/examples.md)
Complete code examples:
* Python client
* JavaScript client
* Rust client
***
## Quick Start
### Simplest Integration (HTTP)
```bash
# Submit inference request
curl -X POST http://gateway.example.com/api/v1/inference \
-H "Content-Type: application/json" \
-d '{
"model_uuid": "bark_semantic",
"input_data": "{\"text\": \"Hello world\"}"
}'
# Response
{
"request_id": "req-abc123",
"status": "queued"
}
# Poll for result
curl http://gateway.example.com/api/v1/inference/req-abc123
```
### With gRPC (Higher Performance)
```python
import grpc
from common_types_pb2 import InferenceRequest
from common_types_pb2_grpc import GatewayClientServiceStub
# Connect
channel = grpc.insecure_channel('gateway.example.com:50051')
stub = GatewayClientServiceStub(channel)
# Submit request
request = InferenceRequest(
model_uuid="bark_semantic",
input_data='{"text": "Hello world"}'
)
status = stub.SubmitInferenceTask(request)
print(f"Request ID: {status.request_id}")
# Subscribe to results
for response in stub.SubscribeToTaskUpdates(RequestID(id=status.request_id)):
print(f"Result: {response.output_data}")
```
***
## Integration Flow
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Client Integration Flow │
│ │
│ 1. Setup │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Generate gRPC client code (if using gRPC) │ │
│ │ • Configure gateway endpoint │ │
│ │ • Set up wallet (if using payments) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ 2. Submit Request │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Prepare input data (JSON format) │ │
│ │ • Specify model_uuid │ │
│ │ • Call SubmitInferenceTask / POST /api/v1/inference │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ 3. Handle Payment (if required) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Receive payment info from status │ │
│ │ • Submit blockchain transaction │ │
│ │ • Confirm with gateway │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ 4. Receive Result │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Poll status endpoint, or │ │
│ │ • Subscribe to gRPC stream, or │ │
│ │ • Listen to WebSocket events │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ 5. Process Result │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Parse output_data (JSON) │ │
│ │ • Verify signatures (optional) │ │
│ │ • Handle errors │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Choosing an Interface
| Use Case | Recommended | Reason |
| --------------- | ----------- | ------------------------- |
| Web application | HTTP | Simple, CORS support |
| Backend service | gRPC | Performance, streaming |
| Real-time app | WebSocket | Live updates |
| Mobile app | HTTP | Wide library support |
| High-throughput | gRPC | Efficient binary protocol |
| Quick prototype | HTTP | No code generation needed |
***
## Input/Output Formats
### Input Data
All input data is JSON-encoded:
```json
{
"text": "Hello world",
"parameters": {
"temperature": 0.7,
"max_tokens": 100
}
}
```
### Output Data
Output is also JSON-encoded:
```json
{
"tokens": [1, 2, 3, 4, 5],
"metadata": {
"inference_time_ms": 1250
}
}
```
***
## Error Handling
### HTTP Errors
| Status | Meaning | Action |
| ------ | ------------ | ------------------------- |
| 400 | Bad request | Check input format |
| 404 | Not found | Check request\_id |
| 429 | Rate limited | Retry with backoff |
| 500 | Server error | Retry or report |
| 503 | Unavailable | Service down, retry later |
### gRPC Errors
| Code | Meaning | Action |
| ------------------- | --------------- | -------------------- |
| INVALID\_ARGUMENT | Bad input | Check request format |
| NOT\_FOUND | Unknown request | Check request\_id |
| RESOURCE\_EXHAUSTED | Rate limited | Retry with backoff |
| UNAVAILABLE | Service down | Retry with backoff |
| INTERNAL | Server error | Report issue |
***
## SDKs and Libraries
### Available
| Language | Status | Usage |
| -------- | ---------- | ------------------- |
| Rust | ✅ Built-in | `test_client` crate |
### Planned
| Language | Status |
| ---------- | -------------- |
| Python | 🚧 In progress |
| JavaScript | 🚧 Planned |
| Go | 🚧 Planned |
### Generate Your Own
```bash
# Python
pip install grpcio-tools
python -m grpc_tools.protoc -I./proto --python_out=. --grpc_python_out=. proto/common_types.proto
# Go
protoc --go_out=. --go-grpc_out=. proto/common_types.proto
# JavaScript
npm install grpc-tools
grpc_tools_node_protoc --js_out=. --grpc_out=. proto/common_types.proto
```
***
## Testing Your Integration
### Local Testing
1. Start local NCN network (see [Running Locally](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/running-locally.md))
2. Configure client to use `localhost`
3. Submit test requests
4. Verify responses
### Testnet Testing
1. Configure client for testnet endpoints
2. Get testnet tokens from faucet
3. Submit requests with payment
4. Verify full payment flow
***
## Next Steps
* [gRPC Client Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/grpc-client.md) - Detailed gRPC integration
* [HTTP Client Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/http-client.md) - REST API integration
* [Payment Integration](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/payment-integration.md) - Blockchain payments
* [Examples](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/clients/examples.md) - Complete code examples
# gRPC Client
Complete guide for integrating with NCN Network using gRPC.
***
## Overview
gRPC provides:
* High performance binary protocol
* Streaming support
* Strong typing via Protocol Buffers
* Auto-generated client code
***
## Generate Client Code
### Python
```bash
# Install dependencies
pip install grpcio grpcio-tools
# Generate Python code
python -m grpc_tools.protoc \
-I./proto \
--python_out=./client \
--grpc_python_out=./client \
proto/common_types.proto
```
### Go
```bash
# Install protoc-gen-go
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
# Generate Go code
protoc \
--go_out=./client \
--go-grpc_out=./client \
proto/common_types.proto
```
### JavaScript/TypeScript
```bash
# Install dependencies
npm install @grpc/grpc-js @grpc/proto-loader
# Or generate static code
npm install grpc-tools
grpc_tools_node_protoc \
--js_out=import_style=commonjs:./client \
--grpc_out=./client \
proto/common_types.proto
```
### Rust
Rust clients are built-in. Use the `common_types` crate:
```toml
[dependencies]
common_types = { path = "../common_types" }
tonic = "0.10"
tokio = { version = "1", features = ["full"] }
```
***
## Connection Setup
### Python
```python
import grpc
from common_types_pb2 import InferenceRequest, TaskID
from common_types_pb2_grpc import GatewayClientServiceStub
# Create channel
channel = grpc.insecure_channel('localhost:50051')
# Or with TLS
credentials = grpc.ssl_channel_credentials()
channel = grpc.secure_channel('gateway.ncn-network.io:443', credentials)
# Create stub
stub = GatewayClientServiceStub(channel)
```
### Go
```go
import (
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
pb "your-module/proto"
)
// Insecure connection
conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
if err != nil {
log.Fatal(err)
}
defer conn.Close()
// Or with TLS
creds, _ := credentials.NewClientTLSFromFile("ca.crt", "")
conn, err := grpc.Dial("gateway.ncn-network.io:443", grpc.WithTransportCredentials(creds))
// Create client
client := pb.NewGatewayClientServiceClient(conn)
```
### JavaScript
```javascript
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
// Load proto
const packageDef = protoLoader.loadSync('./proto/common_types.proto');
const proto = grpc.loadPackageDefinition(packageDef);
// Create client
const client = new proto.common_types.GatewayClientService(
'localhost:50051',
grpc.credentials.createInsecure()
);
```
### Rust
```rust
use common_types::gateway_client_service_client::GatewayClientServiceClient;
use tonic::transport::Channel;
// Connect
let channel = Channel::from_static("http://localhost:50051")
.connect()
.await?;
// Create client
let mut client = GatewayClientServiceClient::new(channel);
```
***
## Submit Inference Request
### Python
```python
import uuid
# Create request
request = InferenceRequest(
request_id=str(uuid.uuid4()),
model_uuid="bark_semantic",
input_data='{"text": "Hello, world!"}',
originator_client_id="client-123"
)
# Submit task
status = stub.SubmitInferenceTask(request)
print(f"Task ID: {status.request_id}")
print(f"Status: {status.status}")
```
### Go
```go
import (
"context"
"github.com/google/uuid"
)
ctx := context.Background()
request := &pb.InferenceRequest{
RequestId: uuid.New().String(),
ModelUuid: "bark_semantic",
InputData: `{"text": "Hello, world!"}`,
OriginatorClientId: "client-123",
}
status, err := client.SubmitInferenceTask(ctx, request)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Task ID: %s, Status: %s\n", status.RequestId, status.Status)
```
### JavaScript
```javascript
const { v4: uuidv4 } = require('uuid');
const request = {
request_id: uuidv4(),
model_uuid: 'bark_semantic',
input_data: JSON.stringify({ text: 'Hello, world!' }),
originator_client_id: 'client-123'
};
client.SubmitInferenceTask(request, (err, status) => {
if (err) {
console.error(err);
return;
}
console.log(`Task ID: ${status.request_id}, Status: ${status.status}`);
});
```
### Rust
```rust
use common_types::InferenceRequest;
use uuid::Uuid;
let request = InferenceRequest {
request_id: Uuid::new_v4().to_string(),
model_uuid: "bark_semantic".to_string(),
input_data: r#"{"text": "Hello, world!"}"#.to_string(),
originator_client_id: "client-123".to_string(),
..Default::default()
};
let status = client.submit_inference_task(request).await?.into_inner();
println!("Task ID: {}, Status: {}", status.request_id, status.status);
```
***
## Subscribe to Results (Streaming)
### Python
```python
# Subscribe to updates
task_id = TaskID(id=status.request_id)
for response in stub.SubscribeToTaskUpdates(task_id):
print(f"Status: {response.status}")
if response.status == "completed":
print(f"Output: {response.output_data}")
break
elif response.status == "failed":
print(f"Error: {response.error_message}")
break
```
### Go
```go
stream, err := client.SubscribeToTaskUpdates(ctx, &pb.TaskID{Id: status.RequestId})
if err != nil {
log.Fatal(err)
}
for {
response, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
log.Fatal(err)
}
fmt.Printf("Status: %s\n", response.Status)
if response.Status == "completed" {
fmt.Printf("Output: %s\n", response.OutputData)
break
} else if response.Status == "failed" {
fmt.Printf("Error: %s\n", response.ErrorMessage)
break
}
}
```
### JavaScript
```javascript
const call = client.SubscribeToTaskUpdates({ id: status.request_id });
call.on('data', (response) => {
console.log(`Status: ${response.status}`);
if (response.status === 'completed') {
console.log(`Output: ${response.output_data}`);
call.cancel();
} else if (response.status === 'failed') {
console.log(`Error: ${response.error_message}`);
call.cancel();
}
});
call.on('end', () => {
console.log('Stream ended');
});
call.on('error', (err) => {
console.error(err);
});
```
### Rust
```rust
use common_types::TaskId;
use tokio_stream::StreamExt;
let task_id = TaskId { id: status.request_id.clone() };
let mut stream = client.subscribe_to_task_updates(task_id).await?.into_inner();
while let Some(response) = stream.next().await {
let response = response?;
println!("Status: {}", response.status);
if response.status == "completed" {
println!("Output: {}", response.output_data);
break;
} else if response.status == "failed" {
println!("Error: {}", response.error_message);
break;
}
}
```
***
## Error Handling
### gRPC Status Codes
| Code | Name | Description |
| ---- | ------------------- | ------------------- |
| 0 | OK | Success |
| 1 | CANCELLED | Operation cancelled |
| 3 | INVALID\_ARGUMENT | Bad request |
| 5 | NOT\_FOUND | Resource not found |
| 8 | RESOURCE\_EXHAUSTED | Rate limited |
| 13 | INTERNAL | Server error |
| 14 | UNAVAILABLE | Service unavailable |
### Python Error Handling
```python
import grpc
try:
status = stub.SubmitInferenceTask(request)
except grpc.RpcError as e:
if e.code() == grpc.StatusCode.UNAVAILABLE:
print("Service unavailable, retrying...")
elif e.code() == grpc.StatusCode.INVALID_ARGUMENT:
print(f"Invalid request: {e.details()}")
else:
print(f"Error: {e.code()} - {e.details()}")
```
### Go Error Handling
```go
import "google.golang.org/grpc/status"
status, err := client.SubmitInferenceTask(ctx, request)
if err != nil {
st, ok := status.FromError(err)
if ok {
switch st.Code() {
case codes.Unavailable:
log.Println("Service unavailable, retrying...")
case codes.InvalidArgument:
log.Printf("Invalid request: %s", st.Message())
default:
log.Printf("Error: %s - %s", st.Code(), st.Message())
}
}
}
```
***
## Retry Logic
### Python with Retry
```python
import time
from functools import wraps
def retry(max_retries=3, delay=1.0):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
for attempt in range(max_retries):
try:
return func(*args, **kwargs)
except grpc.RpcError as e:
if e.code() in [grpc.StatusCode.UNAVAILABLE, grpc.StatusCode.RESOURCE_EXHAUSTED]:
if attempt < max_retries - 1:
time.sleep(delay * (2 ** attempt))
continue
raise
return wrapper
return decorator
@retry(max_retries=3, delay=1.0)
def submit_task(stub, request):
return stub.SubmitInferenceTask(request)
```
***
## Connection Pooling
### Python
```python
# Use channel pool for high throughput
class ChannelPool:
def __init__(self, target, pool_size=10):
self.channels = [
grpc.insecure_channel(target)
for _ in range(pool_size)
]
self.index = 0
def get_stub(self):
channel = self.channels[self.index]
self.index = (self.index + 1) % len(self.channels)
return GatewayClientServiceStub(channel)
pool = ChannelPool('localhost:50051', pool_size=10)
stub = pool.get_stub()
```
***
## Full Example
### Python Complete Client
```python
#!/usr/bin/env python3
import grpc
import uuid
import json
from common_types_pb2 import InferenceRequest, TaskID
from common_types_pb2_grpc import GatewayClientServiceStub
class NCNClient:
def __init__(self, gateway_url='localhost:50051'):
self.channel = grpc.insecure_channel(gateway_url)
self.stub = GatewayClientServiceStub(self.channel)
def inference(self, model_uuid, input_data, timeout=60):
"""Submit inference and wait for result."""
# Create request
request = InferenceRequest(
request_id=str(uuid.uuid4()),
model_uuid=model_uuid,
input_data=json.dumps(input_data) if isinstance(input_data, dict) else input_data,
originator_client_id="python-client"
)
# Submit
status = self.stub.SubmitInferenceTask(request)
print(f"Submitted: {status.request_id}")
# Wait for result
for response in self.stub.SubscribeToTaskUpdates(
TaskID(id=status.request_id),
timeout=timeout
):
if response.status == "completed":
return json.loads(response.output_data)
elif response.status == "failed":
raise Exception(response.error_message)
raise TimeoutError("Request timed out")
def close(self):
self.channel.close()
# Usage
if __name__ == "__main__":
client = NCNClient()
try:
result = client.inference(
model_uuid="bark_semantic",
input_data={"text": "Hello, world!"}
)
print(f"Result: {result}")
finally:
client.close()
```
***
## Next Steps
* [HTTP Client](/nc/neurochainai-guides/clients/http-client) - REST API integration
* [Payment Integration](/nc/neurochainai-guides/clients/payment-integration) - Handle payments
* [Examples](/nc/neurochainai-guides/clients/examples) - More code examples
# HTTP Client
Complete guide for integrating with NCN Network using HTTP REST API.
***
## Overview
The HTTP API provides:
* Simple REST interface
* JSON request/response format
* Easy integration with any language
* Web browser compatibility
***
## Base URL
| Environment | URL |
| ----------- | ------------------------------------ |
| Local | `http://localhost:8080` |
| Testnet | `https://api.testnet.ncn-network.io` |
| Mainnet | `https://api.ncn-network.io` |
***
## Endpoints
### Health Check
```http
GET /health
```
**Response:**
```json
{
"status": "healthy",
"version": "0.1.0",
"uptime_seconds": 3600
}
```
### Submit Inference
```http
POST /api/v1/inference
Content-Type: application/json
{
"model_uuid": "bark_semantic",
"input_data": "{\"text\": \"Hello, world!\"}"
}
```
**Response:**
```json
{
"request_id": "req-abc123",
"status": "queued",
"payment_required": false
}
```
### Get Task Status
```http
GET /api/v1/inference/{request_id}
```
**Response:**
```json
{
"request_id": "req-abc123",
"status": "completed",
"output_data": "{\"tokens\": [1, 2, 3]}",
"error_message": null
}
```
### List Models
```http
GET /api/v1/models
```
**Response:**
```json
{
"models": [
{
"model_uuid": "bark_semantic",
"name": "Bark Semantic Model",
"category": "audio",
"description": "Text to semantic tokens"
}
]
}
```
***
## Client Examples
### cURL
```bash
# Submit inference
curl -X POST http://localhost:8080/api/v1/inference \
-H "Content-Type: application/json" \
-d '{
"model_uuid": "bark_semantic",
"input_data": "{\"text\": \"Hello, world!\"}"
}'
# Get status
curl http://localhost:8080/api/v1/inference/req-abc123
# Health check
curl http://localhost:8080/health
```
### Python (requests)
```python
import requests
import json
import time
class NCNHttpClient:
def __init__(self, base_url='http://localhost:8080'):
self.base_url = base_url
self.session = requests.Session()
def submit_inference(self, model_uuid, input_data):
"""Submit an inference request."""
response = self.session.post(
f"{self.base_url}/api/v1/inference",
json={
"model_uuid": model_uuid,
"input_data": json.dumps(input_data) if isinstance(input_data, dict) else input_data
}
)
response.raise_for_status()
return response.json()
def get_status(self, request_id):
"""Get task status."""
response = self.session.get(
f"{self.base_url}/api/v1/inference/{request_id}"
)
response.raise_for_status()
return response.json()
def inference(self, model_uuid, input_data, timeout=60, poll_interval=1):
"""Submit inference and wait for result."""
# Submit
result = self.submit_inference(model_uuid, input_data)
request_id = result['request_id']
# Poll for result
start_time = time.time()
while time.time() - start_time < timeout:
status = self.get_status(request_id)
if status['status'] == 'completed':
return json.loads(status['output_data'])
elif status['status'] == 'failed':
raise Exception(status.get('error_message', 'Unknown error'))
time.sleep(poll_interval)
raise TimeoutError(f"Request {request_id} timed out")
def health_check(self):
"""Check if gateway is healthy."""
response = self.session.get(f"{self.base_url}/health")
response.raise_for_status()
return response.json()
# Usage
client = NCNHttpClient()
result = client.inference(
model_uuid="bark_semantic",
input_data={"text": "Hello, world!"}
)
print(result)
```
### JavaScript (fetch)
```javascript
class NCNHttpClient {
constructor(baseUrl = 'http://localhost:8080') {
this.baseUrl = baseUrl;
}
async submitInference(modelUuid, inputData) {
const response = await fetch(`${this.baseUrl}/api/v1/inference`, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
model_uuid: modelUuid,
input_data: typeof inputData === 'object'
? JSON.stringify(inputData)
: inputData
})
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
return response.json();
}
async getStatus(requestId) {
const response = await fetch(`${this.baseUrl}/api/v1/inference/${requestId}`);
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
return response.json();
}
async inference(modelUuid, inputData, timeout = 60000, pollInterval = 1000) {
// Submit
const result = await this.submitInference(modelUuid, inputData);
const requestId = result.request_id;
// Poll for result
const startTime = Date.now();
while (Date.now() - startTime < timeout) {
const status = await this.getStatus(requestId);
if (status.status === 'completed') {
return JSON.parse(status.output_data);
} else if (status.status === 'failed') {
throw new Error(status.error_message || 'Unknown error');
}
await new Promise(resolve => setTimeout(resolve, pollInterval));
}
throw new Error(`Request ${requestId} timed out`);
}
async healthCheck() {
const response = await fetch(`${this.baseUrl}/health`);
return response.json();
}
}
// Usage
const client = new NCNHttpClient();
const result = await client.inference('bark_semantic', { text: 'Hello, world!' });
console.log(result);
```
### Go
```go
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"time"
)
type NCNClient struct {
BaseURL string
Client *http.Client
}
type InferenceRequest struct {
ModelUUID string `json:"model_uuid"`
InputData string `json:"input_data"`
}
type InferenceStatus struct {
RequestID string `json:"request_id"`
Status string `json:"status"`
OutputData string `json:"output_data"`
ErrorMessage string `json:"error_message"`
}
func NewNCNClient(baseURL string) *NCNClient {
return &NCNClient{
BaseURL: baseURL,
Client: &http.Client{Timeout: 30 * time.Second},
}
}
func (c *NCNClient) SubmitInference(modelUUID string, inputData interface{}) (*InferenceStatus, error) {
inputJSON, _ := json.Marshal(inputData)
reqBody, _ := json.Marshal(InferenceRequest{
ModelUUID: modelUUID,
InputData: string(inputJSON),
})
resp, err := c.Client.Post(
c.BaseURL+"/api/v1/inference",
"application/json",
bytes.NewBuffer(reqBody),
)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var status InferenceStatus
json.NewDecoder(resp.Body).Decode(&status)
return &status, nil
}
func (c *NCNClient) GetStatus(requestID string) (*InferenceStatus, error) {
resp, err := c.Client.Get(c.BaseURL + "/api/v1/inference/" + requestID)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var status InferenceStatus
json.NewDecoder(resp.Body).Decode(&status)
return &status, nil
}
func (c *NCNClient) Inference(modelUUID string, inputData interface{}, timeout time.Duration) (map[string]interface{}, error) {
result, err := c.SubmitInference(modelUUID, inputData)
if err != nil {
return nil, err
}
deadline := time.Now().Add(timeout)
for time.Now().Before(deadline) {
status, err := c.GetStatus(result.RequestID)
if err != nil {
return nil, err
}
if status.Status == "completed" {
var output map[string]interface{}
json.Unmarshal([]byte(status.OutputData), &output)
return output, nil
} else if status.Status == "failed" {
return nil, fmt.Errorf("task failed: %s", status.ErrorMessage)
}
time.Sleep(1 * time.Second)
}
return nil, fmt.Errorf("timeout")
}
func main() {
client := NewNCNClient("http://localhost:8080")
result, err := client.Inference("bark_semantic", map[string]string{
"text": "Hello, world!",
}, 60*time.Second)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Result: %v\n", result)
}
```
***
## Error Handling
### HTTP Status Codes
| Code | Meaning | Action |
| ---- | ------------ | ------------------ |
| 200 | Success | Process response |
| 400 | Bad Request | Check input format |
| 404 | Not Found | Check request\_id |
| 429 | Rate Limited | Retry with backoff |
| 500 | Server Error | Retry or report |
| 503 | Unavailable | Retry later |
### Error Response Format
```json
{
"error": {
"code": "INVALID_MODEL",
"message": "Model 'unknown' not found",
"details": {}
}
}
```
### Retry Logic
```python
import time
from requests.exceptions import RequestException
def retry_request(func, max_retries=3, backoff=1.0):
for attempt in range(max_retries):
try:
return func()
except RequestException as e:
if attempt < max_retries - 1:
if hasattr(e.response, 'status_code'):
if e.response.status_code in [429, 503]:
time.sleep(backoff * (2 ** attempt))
continue
raise
```
***
## Authentication (Future)
When API keys are implemented:
```http
Authorization: Bearer YOUR_API_KEY
```
```python
client = NCNHttpClient()
client.session.headers['Authorization'] = 'Bearer YOUR_API_KEY'
```
***
## Rate Limiting
### Limits
| Endpoint | Limit |
| ------------------------ | -------- |
| POST /api/v1/inference | 100/min |
| GET /api/v1/inference/\* | 1000/min |
| GET /health | No limit |
### Rate Limit Headers
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067260
```
### Handle Rate Limits
```python
def handle_rate_limit(response):
if response.status_code == 429:
reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
wait_time = max(reset_time - time.time(), 1)
time.sleep(wait_time)
return True
return False
```
***
## Next Steps
* [gRPC Client](/nc/neurochainai-guides/clients/grpc-client) - Higher performance option
* [Payment Integration](/nc/neurochainai-guides/clients/payment-integration) - Handle payments
* [Examples](/nc/neurochainai-guides/clients/examples) - More code examples
# Payment Integration
Guide for integrating blockchain payments with NCN Network.
***
## Overview
NCN Network uses blockchain-based payments:
1. Client receives payment info after submitting request
2. Client pays to smart contract
3. Client confirms payment with gateway
4. Inference proceeds
5. Payment distributed on completion
***
## Payment Flow
```
┌──────────────────────────────────────────────────────────────────────────┐
│ Payment Flow │
│ │
│ Client Gateway Blockchain │
│ │ │ │ │
│ │ 1. Submit request │ │ │
│ │──────────────────────▶│ │ │
│ │ │ │ │
│ │ 2. Payment info │ │ │
│ │◀──────────────────────│ │ │
│ │ (amount, contract) │ │ │
│ │ │ │ │
│ │ 3. Pay to contract │ │ │
│ │───────────────────────────────────────────────▶│ │
│ │ │ │ │
│ │ 4. tx_hash │ │ │
│ │◀──────────────────────────────────────────────│ │
│ │ │ │ │
│ │ 5. Confirm payment │ │ │
│ │──────────────────────▶│ │ │
│ │ (tx_hash) │ │ │
│ │ │ │ │
│ │ │ 6. Verify tx │ │
│ │ │──────────────────────▶│ │
│ │ │ │ │
│ │ 7. Processing... │ │ │
│ │◀──────────────────────│ │ │
│ │ │ │ │
│ │ 8. Result │ │ │
│ │◀──────────────────────│ │ │
│ │ │ │ │
└──────────────────────────────────────────────────────────────────────────┘
```
***
## Prerequisites
* Web3 wallet (MetaMask, etc.) or programmatic wallet
* NCN tokens (testnet: use faucet)
* ETH for gas fees
***
## Contract Addresses
### Testnet (Forknet)
| Contract | Address |
| -------------------- | -------------------------------------------- |
| **InferencePayment** | `0x4361115359E5C0a25c9b2f8Bb71184F010b768ea` |
| **NCNToken** | `0x38E2565e8905BeAf83C34b266592465C22A2f108` |
**Network Config:**
* RPC URL: `https://testnet-rpc-1.forknet.io`
* Chain ID: `828`
***
## Integration Steps
### 1. Submit Request & Get Payment Info
```python
import requests
# Submit inference request
response = requests.post(
"http://localhost:8080/api/v1/inference",
json={
"model_uuid": "bark_semantic",
"input_data": '{"text": "Hello"}'
}
)
result = response.json()
request_id = result['request_id']
# Check if payment is required
if result.get('payment_required'):
payment_info = result['payment_info']
amount_wei = payment_info['total_amount_wei']
contract_address = payment_info['contract_address']
signatures = payment_info['validator_signatures']
```
### 2. Approve Token Spend
```python
from web3 import Web3
w3 = Web3(Web3.HTTPProvider('https://testnet-rpc-1.forknet.io'))
TOKEN_ADDRESS = '0x38E2565e8905BeAf83C34b266592465C22A2f108'
CONTRACT_ADDRESS = '0x4361115359E5C0a25c9b2f8Bb71184F010b768ea'
# ERC20 ABI (approve function only)
token_abi = [
{
"inputs": [
{"name": "spender", "type": "address"},
{"name": "amount", "type": "uint256"}
],
"name": "approve",
"outputs": [{"type": "bool"}],
"stateMutability": "nonpayable",
"type": "function"
}
]
token = w3.eth.contract(address=TOKEN_ADDRESS, abi=token_abi)
# Approve contract to spend tokens
tx = token.functions.approve(
CONTRACT_ADDRESS,
int(amount_wei)
).build_transaction({
'from': YOUR_ADDRESS,
'nonce': w3.eth.get_transaction_count(YOUR_ADDRESS),
'gas': 100000,
'gasPrice': w3.eth.gas_price
})
signed_tx = w3.eth.account.sign_transaction(tx, YOUR_PRIVATE_KEY)
tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction)
w3.eth.wait_for_transaction_receipt(tx_hash)
```
### 3. Initiate Payment
```python
# InferencePayment ABI (initiateInferenceRequest function)
payment_abi = [
{
"inputs": [
{"name": "requestId", "type": "bytes32"},
{"name": "gateway", "type": "address"},
{"name": "computeNode", "type": "address"},
{"name": "computePrice", "type": "uint256"},
{"name": "gatewayGas", "type": "uint256"},
{"name": "validatorReward", "type": "uint256"},
{"name": "treasuryFee", "type": "uint256"},
{"name": "expiry", "type": "uint256"},
{"name": "validatorSignatures", "type": "bytes[]"}
],
"name": "initiateInferenceRequest",
"outputs": [],
"stateMutability": "nonpayable",
"type": "function"
}
]
payment = w3.eth.contract(address=CONTRACT_ADDRESS, abi=payment_abi)
# Convert request_id to bytes32
request_id_bytes = Web3.keccak(text=request_id)
# Build transaction
tx = payment.functions.initiateInferenceRequest(
request_id_bytes,
payment_info['gateway_address'],
payment_info['compute_node_address'],
int(payment_info['compute_price_wei']),
int(payment_info['gateway_gas_wei']),
int(payment_info['validator_reward_wei']),
int(payment_info['treasury_fee_wei']),
payment_info['expiry_timestamp'],
[bytes.fromhex(sig[2:]) for sig in payment_info['validator_signatures']]
).build_transaction({
'from': YOUR_ADDRESS,
'nonce': w3.eth.get_transaction_count(YOUR_ADDRESS),
'gas': 500000,
'gasPrice': w3.eth.gas_price
})
signed_tx = w3.eth.account.sign_transaction(tx, YOUR_PRIVATE_KEY)
tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
```
### 4. Confirm Payment with Gateway
```python
# Confirm payment with gateway
response = requests.post(
f"http://localhost:8080/api/v1/inference/{request_id}/confirm-payment",
json={
"tx_hash": tx_hash.hex(),
"block_number": receipt['blockNumber']
}
)
if response.status_code == 200:
print("Payment confirmed, inference proceeding...")
```
### 5. Wait for Result
```python
import time
while True:
response = requests.get(f"http://localhost:8080/api/v1/inference/{request_id}")
status = response.json()
if status['status'] == 'completed':
print(f"Result: {status['output_data']}")
break
elif status['status'] == 'failed':
print(f"Error: {status['error_message']}")
break
time.sleep(1)
```
***
## JavaScript Integration
### Using ethers.js
```javascript
import { ethers } from 'ethers';
const provider = new ethers.providers.JsonRpcProvider('https://testnet-rpc-1.forknet.io');
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
const TOKEN_ADDRESS = '0x38E2565e8905BeAf83C34b266592465C22A2f108';
const CONTRACT_ADDRESS = '0x4361115359E5C0a25c9b2f8Bb71184F010b768ea';
// Token ABI
const tokenABI = ['function approve(address spender, uint256 amount) returns (bool)'];
const token = new ethers.Contract(TOKEN_ADDRESS, tokenABI, wallet);
// Payment ABI
const paymentABI = [
'function initiateInferenceRequest(bytes32 requestId, address gateway, address computeNode, uint256 computePrice, uint256 gatewayGas, uint256 validatorReward, uint256 treasuryFee, uint256 expiry, bytes[] validatorSignatures)'
];
const payment = new ethers.Contract(CONTRACT_ADDRESS, paymentABI, wallet);
async function payForInference(paymentInfo) {
// 1. Approve tokens
const approveTx = await token.approve(
CONTRACT_ADDRESS,
paymentInfo.total_amount_wei
);
await approveTx.wait();
// 2. Initiate payment
const requestIdBytes = ethers.utils.id(paymentInfo.request_id);
const payTx = await payment.initiateInferenceRequest(
requestIdBytes,
paymentInfo.gateway_address,
paymentInfo.compute_node_address,
paymentInfo.compute_price_wei,
paymentInfo.gateway_gas_wei,
paymentInfo.validator_reward_wei,
paymentInfo.treasury_fee_wei,
paymentInfo.expiry_timestamp,
paymentInfo.validator_signatures
);
const receipt = await payTx.wait();
return receipt.transactionHash;
}
```
***
## Complete Example
### Python with Full Payment Flow
```python
#!/usr/bin/env python3
import requests
import time
from web3 import Web3
class NCNPaymentClient:
def __init__(self, gateway_url, rpc_url, private_key):
self.gateway_url = gateway_url
self.w3 = Web3(Web3.HTTPProvider(rpc_url))
self.account = self.w3.eth.account.from_key(private_key)
self.TOKEN_ADDRESS = '0x38E2565e8905BeAf83C34b266592465C22A2f108'
self.CONTRACT_ADDRESS = '0x4361115359E5C0a25c9b2f8Bb71184F010b768ea'
# Load ABIs
self.token = self.w3.eth.contract(
address=self.TOKEN_ADDRESS,
abi=self._token_abi()
)
self.payment = self.w3.eth.contract(
address=self.CONTRACT_ADDRESS,
abi=self._payment_abi()
)
def inference(self, model_uuid, input_data, timeout=120):
"""Submit inference with payment."""
# 1. Submit request
response = requests.post(
f"{self.gateway_url}/api/v1/inference",
json={
"model_uuid": model_uuid,
"input_data": input_data
}
)
result = response.json()
request_id = result['request_id']
# 2. Handle payment if required
if result.get('payment_required'):
payment_info = result['payment_info']
# Approve tokens
self._approve_tokens(payment_info['total_amount_wei'])
# Pay
tx_hash = self._initiate_payment(request_id, payment_info)
# Confirm with gateway
requests.post(
f"{self.gateway_url}/api/v1/inference/{request_id}/confirm-payment",
json={"tx_hash": tx_hash}
)
# 3. Wait for result
return self._wait_for_result(request_id, timeout)
def _approve_tokens(self, amount):
tx = self.token.functions.approve(
self.CONTRACT_ADDRESS,
int(amount)
).build_transaction({
'from': self.account.address,
'nonce': self.w3.eth.get_transaction_count(self.account.address),
'gas': 100000,
'gasPrice': self.w3.eth.gas_price
})
signed = self.account.sign_transaction(tx)
tx_hash = self.w3.eth.send_raw_transaction(signed.rawTransaction)
self.w3.eth.wait_for_transaction_receipt(tx_hash)
def _initiate_payment(self, request_id, payment_info):
request_id_bytes = Web3.keccak(text=request_id)
tx = self.payment.functions.initiateInferenceRequest(
request_id_bytes,
payment_info['gateway_address'],
payment_info['compute_node_address'],
int(payment_info['compute_price_wei']),
int(payment_info['gateway_gas_wei']),
int(payment_info['validator_reward_wei']),
int(payment_info['treasury_fee_wei']),
payment_info['expiry_timestamp'],
[bytes.fromhex(sig[2:]) for sig in payment_info['validator_signatures']]
).build_transaction({
'from': self.account.address,
'nonce': self.w3.eth.get_transaction_count(self.account.address),
'gas': 500000,
'gasPrice': self.w3.eth.gas_price
})
signed = self.account.sign_transaction(tx)
tx_hash = self.w3.eth.send_raw_transaction(signed.rawTransaction)
self.w3.eth.wait_for_transaction_receipt(tx_hash)
return tx_hash.hex()
def _wait_for_result(self, request_id, timeout):
start_time = time.time()
while time.time() - start_time < timeout:
response = requests.get(
f"{self.gateway_url}/api/v1/inference/{request_id}"
)
status = response.json()
if status['status'] == 'completed':
return status['output_data']
elif status['status'] == 'failed':
raise Exception(status.get('error_message', 'Unknown error'))
time.sleep(1)
raise TimeoutError(f"Request {request_id} timed out")
def _token_abi(self):
return [{"inputs":[{"name":"spender","type":"address"},{"name":"amount","type":"uint256"}],"name":"approve","outputs":[{"type":"bool"}],"stateMutability":"nonpayable","type":"function"}]
def _payment_abi(self):
return [{"inputs":[{"name":"requestId","type":"bytes32"},{"name":"gateway","type":"address"},{"name":"computeNode","type":"address"},{"name":"computePrice","type":"uint256"},{"name":"gatewayGas","type":"uint256"},{"name":"validatorReward","type":"uint256"},{"name":"treasuryFee","type":"uint256"},{"name":"expiry","type":"uint256"},{"name":"validatorSignatures","type":"bytes[]"}],"name":"initiateInferenceRequest","outputs":[],"stateMutability":"nonpayable","type":"function"}]
# Usage
if __name__ == "__main__":
client = NCNPaymentClient(
gateway_url="http://localhost:8080",
rpc_url="https://testnet-rpc-1.forknet.io",
private_key="0x..."
)
result = client.inference(
model_uuid="bark_semantic",
input_data='{"text": "Hello, world!"}'
)
print(f"Result: {result}")
```
***
## Testnet Faucet
Get testnet NCN tokens:
```bash
# Check faucet availability
curl https://faucet.testnet.ncn-network.io/api/status
# Request tokens
curl -X POST https://faucet.testnet.ncn-network.io/api/faucet \
-H "Content-Type: application/json" \
-d '{"address": "0xYOUR_ADDRESS"}'
```
***
## Next Steps
* [gRPC Client](/nc/neurochainai-guides/clients/grpc-client) - gRPC integration
* [HTTP Client](/nc/neurochainai-guides/clients/http-client) - HTTP integration
* [Examples](/nc/neurochainai-guides/clients/examples) - More code examples
# Examples
Complete code examples for NCN Network client integration.
***
## Python Examples
### Simple HTTP Client
```python
#!/usr/bin/env python3
"""Simple NCN client using HTTP API."""
import requests
import json
import time
GATEWAY_URL = "http://localhost:8080"
def inference(model_uuid, input_data, timeout=60):
"""Submit inference and wait for result."""
# Submit request
response = requests.post(
f"{GATEWAY_URL}/api/v1/inference",
json={
"model_uuid": model_uuid,
"input_data": json.dumps(input_data)
}
)
response.raise_for_status()
result = response.json()
request_id = result['request_id']
print(f"Submitted: {request_id}")
# Poll for result
start_time = time.time()
while time.time() - start_time < timeout:
status_response = requests.get(
f"{GATEWAY_URL}/api/v1/inference/{request_id}"
)
status = status_response.json()
if status['status'] == 'completed':
return json.loads(status['output_data'])
elif status['status'] == 'failed':
raise Exception(status.get('error_message', 'Unknown error'))
print(f"Status: {status['status']}")
time.sleep(1)
raise TimeoutError("Request timed out")
if __name__ == "__main__":
result = inference(
model_uuid="bark_semantic",
input_data={"text": "Hello, world!"}
)
print(f"Result: {result}")
```
### Async HTTP Client
```python
#!/usr/bin/env python3
"""Async NCN client using aiohttp."""
import asyncio
import aiohttp
import json
GATEWAY_URL = "http://localhost:8080"
async def inference(model_uuid, input_data, timeout=60):
"""Submit inference and wait for result (async)."""
async with aiohttp.ClientSession() as session:
# Submit request
async with session.post(
f"{GATEWAY_URL}/api/v1/inference",
json={
"model_uuid": model_uuid,
"input_data": json.dumps(input_data)
}
) as response:
result = await response.json()
request_id = result['request_id']
# Poll for result
for _ in range(timeout):
async with session.get(
f"{GATEWAY_URL}/api/v1/inference/{request_id}"
) as response:
status = await response.json()
if status['status'] == 'completed':
return json.loads(status['output_data'])
elif status['status'] == 'failed':
raise Exception(status.get('error_message'))
await asyncio.sleep(1)
raise TimeoutError()
async def main():
# Run multiple inferences concurrently
tasks = [
inference("bark_semantic", {"text": f"Hello {i}!"})
for i in range(5)
]
results = await asyncio.gather(*tasks)
for i, result in enumerate(results):
print(f"Result {i}: {result}")
if __name__ == "__main__":
asyncio.run(main())
```
### gRPC Client
```python
#!/usr/bin/env python3
"""NCN client using gRPC."""
import grpc
import uuid
import json
# Generate these from proto file
from common_types_pb2 import InferenceRequest, TaskID
from common_types_pb2_grpc import GatewayClientServiceStub
def main():
# Connect to gateway
channel = grpc.insecure_channel('localhost:50051')
stub = GatewayClientServiceStub(channel)
# Create request
request = InferenceRequest(
request_id=str(uuid.uuid4()),
model_uuid="bark_semantic",
input_data=json.dumps({"text": "Hello, world!"}),
originator_client_id="python-grpc-client"
)
# Submit
status = stub.SubmitInferenceTask(request)
print(f"Submitted: {status.request_id}")
# Subscribe to results
for response in stub.SubscribeToTaskUpdates(
TaskID(id=status.request_id)
):
print(f"Status: {response.status}")
if response.status == "completed":
result = json.loads(response.output_data)
print(f"Result: {result}")
break
elif response.status == "failed":
print(f"Error: {response.error_message}")
break
if __name__ == "__main__":
main()
```
***
## JavaScript Examples
### Browser Client (fetch)
```javascript
// browser-client.js
class NCNClient {
constructor(baseUrl = 'http://localhost:8080') {
this.baseUrl = baseUrl;
}
async inference(modelUuid, inputData, timeout = 60000) {
// Submit request
const submitResponse = await fetch(`${this.baseUrl}/api/v1/inference`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
model_uuid: modelUuid,
input_data: JSON.stringify(inputData)
})
});
const { request_id } = await submitResponse.json();
console.log(`Submitted: ${request_id}`);
// Poll for result
const startTime = Date.now();
while (Date.now() - startTime < timeout) {
const statusResponse = await fetch(
`${this.baseUrl}/api/v1/inference/${request_id}`
);
const status = await statusResponse.json();
if (status.status === 'completed') {
return JSON.parse(status.output_data);
} else if (status.status === 'failed') {
throw new Error(status.error_message);
}
await new Promise(r => setTimeout(r, 1000));
}
throw new Error('Timeout');
}
}
// Usage
const client = new NCNClient();
client.inference('bark_semantic', { text: 'Hello, world!' })
.then(result => console.log('Result:', result))
.catch(error => console.error('Error:', error));
```
### Node.js Client
```javascript
// node-client.js
const fetch = require('node-fetch');
class NCNClient {
constructor(baseUrl = 'http://localhost:8080') {
this.baseUrl = baseUrl;
}
async inference(modelUuid, inputData, timeout = 60000) {
// Submit
const submitRes = await fetch(`${this.baseUrl}/api/v1/inference`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
model_uuid: modelUuid,
input_data: JSON.stringify(inputData)
})
});
const { request_id } = await submitRes.json();
// Poll
const deadline = Date.now() + timeout;
while (Date.now() < deadline) {
const statusRes = await fetch(`${this.baseUrl}/api/v1/inference/${request_id}`);
const status = await statusRes.json();
if (status.status === 'completed') {
return JSON.parse(status.output_data);
}
if (status.status === 'failed') {
throw new Error(status.error_message);
}
await new Promise(r => setTimeout(r, 1000));
}
throw new Error('Timeout');
}
}
// Usage
(async () => {
const client = new NCNClient();
const result = await client.inference('bark_semantic', { text: 'Hello!' });
console.log('Result:', result);
})();
```
### TypeScript Client
```typescript
// ncn-client.ts
interface InferenceResult {
tokens?: number[];
[key: string]: any;
}
interface InferenceStatus {
request_id: string;
status: 'queued' | 'processing' | 'completed' | 'failed';
output_data?: string;
error_message?: string;
}
class NCNClient {
private baseUrl: string;
constructor(baseUrl: string = 'http://localhost:8080') {
this.baseUrl = baseUrl;
}
async inference(
modelUuid: string,
inputData: Record,
timeout: number = 60000
): Promise {
// Submit
const submitResponse = await fetch(`${this.baseUrl}/api/v1/inference`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
model_uuid: modelUuid,
input_data: JSON.stringify(inputData)
})
});
const { request_id } = await submitResponse.json();
// Poll
const deadline = Date.now() + timeout;
while (Date.now() < deadline) {
const statusResponse = await fetch(
`${this.baseUrl}/api/v1/inference/${request_id}`
);
const status: InferenceStatus = await statusResponse.json();
if (status.status === 'completed' && status.output_data) {
return JSON.parse(status.output_data) as T;
}
if (status.status === 'failed') {
throw new Error(status.error_message || 'Unknown error');
}
await new Promise(r => setTimeout(r, 1000));
}
throw new Error('Timeout');
}
}
// Usage
const client = new NCNClient();
const result = await client.inference('bark_semantic', { text: 'Hello!' });
```
***
## Go Example
```go
// main.go
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"time"
)
type NCNClient struct {
BaseURL string
Client *http.Client
}
func NewNCNClient(baseURL string) *NCNClient {
return &NCNClient{
BaseURL: baseURL,
Client: &http.Client{Timeout: 30 * time.Second},
}
}
func (c *NCNClient) Inference(modelUUID string, inputData map[string]interface{}) (map[string]interface{}, error) {
// Marshal input
inputJSON, _ := json.Marshal(inputData)
body, _ := json.Marshal(map[string]string{
"model_uuid": modelUUID,
"input_data": string(inputJSON),
})
// Submit
resp, err := c.Client.Post(
c.BaseURL+"/api/v1/inference",
"application/json",
bytes.NewBuffer(body),
)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var submitResult map[string]interface{}
json.NewDecoder(resp.Body).Decode(&submitResult)
requestID := submitResult["request_id"].(string)
// Poll
for i := 0; i < 60; i++ {
resp, _ := c.Client.Get(c.BaseURL + "/api/v1/inference/" + requestID)
var status map[string]interface{}
json.NewDecoder(resp.Body).Decode(&status)
resp.Body.Close()
if status["status"] == "completed" {
var result map[string]interface{}
json.Unmarshal([]byte(status["output_data"].(string)), &result)
return result, nil
}
if status["status"] == "failed" {
return nil, fmt.Errorf("%s", status["error_message"])
}
time.Sleep(time.Second)
}
return nil, fmt.Errorf("timeout")
}
func main() {
client := NewNCNClient("http://localhost:8080")
result, err := client.Inference("bark_semantic", map[string]interface{}{
"text": "Hello, world!",
})
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Result: %v\n", result)
}
```
***
## Rust Example
```rust
// main.rs
use reqwest::Client;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::time::Duration;
use tokio::time::sleep;
#[derive(Serialize)]
struct InferenceRequest {
model_uuid: String,
input_data: String,
}
#[derive(Deserialize)]
struct SubmitResponse {
request_id: String,
}
#[derive(Deserialize)]
struct StatusResponse {
status: String,
output_data: Option,
error_message: Option,
}
struct NCNClient {
base_url: String,
client: Client,
}
impl NCNClient {
fn new(base_url: &str) -> Self {
Self {
base_url: base_url.to_string(),
client: Client::new(),
}
}
async fn inference(&self, model_uuid: &str, input_data: Value) -> Result> {
// Submit
let response = self.client
.post(&format!("{}/api/v1/inference", self.base_url))
.json(&InferenceRequest {
model_uuid: model_uuid.to_string(),
input_data: serde_json::to_string(&input_data)?,
})
.send()
.await?;
let submit: SubmitResponse = response.json().await?;
println!("Submitted: {}", submit.request_id);
// Poll
for _ in 0..60 {
let status: StatusResponse = self.client
.get(&format!("{}/api/v1/inference/{}", self.base_url, submit.request_id))
.send()
.await?
.json()
.await?;
match status.status.as_str() {
"completed" => {
let output: Value = serde_json::from_str(&status.output_data.unwrap())?;
return Ok(output);
}
"failed" => {
return Err(status.error_message.unwrap_or_default().into());
}
_ => {}
}
sleep(Duration::from_secs(1)).await;
}
Err("Timeout".into())
}
}
#[tokio::main]
async fn main() {
let client = NCNClient::new("http://localhost:8080");
match client.inference("bark_semantic", json!({"text": "Hello!"})).await {
Ok(result) => println!("Result: {}", result),
Err(e) => eprintln!("Error: {}", e),
}
}
```
***
## Bash/Shell Example
```bash
#!/bin/bash
# ncn-client.sh
GATEWAY_URL="${GATEWAY_URL:-http://localhost:8080}"
MODEL_UUID="${1:-bark_semantic}"
INPUT_TEXT="${2:-Hello, world!}"
# Submit request
echo "Submitting request..."
RESPONSE=$(curl -s -X POST "$GATEWAY_URL/api/v1/inference" \
-H "Content-Type: application/json" \
-d "{\"model_uuid\": \"$MODEL_UUID\", \"input_data\": \"{\\\"text\\\": \\\"$INPUT_TEXT\\\"}\"}")
REQUEST_ID=$(echo "$RESPONSE" | jq -r '.request_id')
echo "Request ID: $REQUEST_ID"
# Poll for result
echo "Waiting for result..."
for i in $(seq 1 60); do
STATUS=$(curl -s "$GATEWAY_URL/api/v1/inference/$REQUEST_ID")
STATE=$(echo "$STATUS" | jq -r '.status')
case "$STATE" in
completed)
echo "Result: $(echo "$STATUS" | jq -r '.output_data')"
exit 0
;;
failed)
echo "Error: $(echo "$STATUS" | jq -r '.error_message')"
exit 1
;;
*)
echo "Status: $STATE"
sleep 1
;;
esac
done
echo "Timeout"
exit 1
```
***
## Next Steps
* [gRPC Client](/nc/neurochainai-guides/clients/grpc-client) - gRPC details
* [HTTP Client](/nc/neurochainai-guides/clients/http-client) - HTTP details
* [Payment Integration](/nc/neurochainai-guides/clients/payment-integration) - Add payments
# Overview
This section documents all configuration options for NCN Network v2 components.
***
## Configuration Methods
NCN Network components can be configured through:
1. **Environment Variables** - Primary method
2. **Configuration Files** - For complex settings (e.g., `.env` files)
3. **Command Line Arguments** - For runtime overrides
### Priority Order
```
Command Line Args > Environment Variables > Config Files > Defaults
```
***
## Configuration Guides
### [Gateway Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/configuration/gateway-config.md)
Complete gateway configuration:
* Wallet settings
* Network addresses
* Blockchain configuration
* Payment settings
### [Compute Node Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/configuration/compute-config.md)
Compute node configuration:
* Sandbox settings
* Resource limits
* Model paths
* Execution settings
### [Registry Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/configuration/registry-config.md)
P2P Registry configuration:
* P2P network settings
* Validator settings
* Storage settings
### [Environment Variables Reference](/nc/neurochainai-guides/configuration/environment-vars)
Complete reference of all environment variables across all components.
### [Network Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/configuration/network-config.md)
Network-specific configurations:
* Local development
* Forknet testnet
* Sepolia testnet
* Mainnet
***
## Quick Reference
### Gateway Node
```bash
# Required
GATEWAY_WALLET_PRIVATE_KEY=0x...
RPC_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x4361...
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050
# Optional
GRPC_ADDR=127.0.0.1:50051
HTTP_ADDR=127.0.0.1:8080
WS_ADDR=127.0.0.1:9000
SUBNET_ID=1
```
### Compute Node
```bash
# Command line
--gateway-addr http://127.0.0.1:50051
--model-path ./models
# Environment
COMPUTE_NODE_PRIVATE_KEY=0x...
SANDBOX_MODE=strict
EXECUTION_TIMEOUT_SECS=300
MAX_MEMORY_MB=4096
```
### P2P Registry
```bash
# Command line
--p2p-listen-addr /ip4/0.0.0.0/tcp/8828
--grpc-listen-addr 127.0.0.1:50050
# Environment
VALIDATOR_PRIVATE_KEY=0x...
VALIDATOR_SYNC_ENABLED=true
```
***
## Network Configurations
### Local Development
```bash
# Gateway
RPC_URL=http://127.0.0.1:8545
NETWORK=local
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050
# Features disabled for development
REQUIRE_PAYMENT=false
SANDBOX_MODE=disabled
```
### Forknet Testnet
```bash
# Gateway
RPC_URL=https://forknet-rpc.neuralgpu.online
NETWORK=forknet
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
# Compute
SANDBOX_MODE=strict
REQUIRE_PAYMENT=true
```
### Production (Mainnet)
```bash
# Gateway
RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
NETWORK=mainnet
CONTRACT_ADDRESS=0x...
# Security
SANDBOX_MODE=strict
REQUIRE_PAYMENT=true
REQUIRED_CONFIRMATIONS=12
```
***
## Configuration Files
### Gateway `.env` File
Location: `gateway_node/.env`
```bash
# ============================================================================
# REQUIRED: Wallet Configuration
# ============================================================================
GATEWAY_WALLET_PRIVATE_KEY=0x...
GATEWAY_WALLET_ADDRESS=0x...
# ============================================================================
# Blockchain Configuration
# ============================================================================
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
RPC_URL=http://127.0.0.1:8545
NETWORK=forknet
# ============================================================================
# Network Configuration
# ============================================================================
SUBNET_ID=1
GRPC_ADDR=127.0.0.1:50051
HTTP_ADDR=127.0.0.1:8080
WS_ADDR=127.0.0.1:9000
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050
# ============================================================================
# Transaction Configuration
# ============================================================================
GAS_LIMIT=500000
GAS_PRICE_MULTIPLIER=1.1
REQUIRED_CONFIRMATIONS=1
```
### Subnet Configuration
Location: Custom (used with `subnet-cli`)
```json
{
"gateway_address": "0x...",
"models": [
{
"name": "bark_semantic",
"download_url": "https://huggingface.co/suno/bark/...",
"executor_script": "...",
"file_size_bytes": 2000000000
}
]
}
```
***
## Security Recommendations
### Private Keys
```bash
# DON'T commit .env files with real keys
# .gitignore should include:
.env
*.env.local
*.env.production
# DO use environment variables or secrets management
export GATEWAY_WALLET_PRIVATE_KEY="$SECRET_FROM_VAULT"
```
### Network Exposure
```bash
# Development (bind to localhost)
GRPC_ADDR=127.0.0.1:50051
HTTP_ADDR=127.0.0.1:8080
# Production (bind to all interfaces behind firewall)
GRPC_ADDR=0.0.0.0:50051
HTTP_ADDR=0.0.0.0:8080
```
### Sandbox Mode
```bash
# Development only
SANDBOX_MODE=disabled
# Testing
SANDBOX_MODE=permissive
# Production (always)
SANDBOX_MODE=strict
```
***
## Validation
### Check Configuration
```bash
# Gateway: verify wallet loads
cargo run --bin gateway_node -- --dry-run
# Compute: verify sandbox
cargo run --bin compute_node -- --check-sandbox
# Subnet CLI: validate config
subnet-cli validate -c my_subnet.json
```
### Required vs Optional
| Component | Required | Recommended | Optional |
| --------- | ------------------------------- | --------------- | -------------- |
| Gateway | Wallet, RPC, Contract, Registry | TLS, Metrics | Debug settings |
| Compute | Gateway addr | Wallet, Sandbox | Fallback |
| Registry | Listen addresses | Validator key | Sync settings |
***
## Next Steps
* [Gateway Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/configuration/gateway-config.md) - Full gateway options
* [Compute Configuration](https://github.com/NeuroChainAi/docs-guides/blob/main/configuration/compute-config.md) - Compute node options
* [Environment Variables](/nc/neurochainai-guides/configuration/environment-vars) - Complete reference
# Environment Variables
Complete reference of all environment variables across NCN Network v2 components.
***
## Gateway Node
### Required
| Variable | Description | Example |
| ---------------------------- | --------------------------------- | ------------------------ |
| `GATEWAY_WALLET_PRIVATE_KEY` | Gateway wallet private key | `0xabcd...` |
| `RPC_URL` | Blockchain RPC endpoint | `http://127.0.0.1:8545` |
| `CONTRACT_ADDRESS` | InferencePayment contract address | `0x4361...` |
| `REGISTRY_GRPC_ADDR` | P2P Registry gRPC address | `http://127.0.0.1:50050` |
### Optional
| Variable | Default | Description |
| ----------------------------- | ----------------- | --------------------------------- |
| `GATEWAY_WALLET_ADDRESS` | Derived | Wallet address (derived from key) |
| `GRPC_ADDR` | `127.0.0.1:50051` | gRPC listen address |
| `HTTP_ADDR` | `127.0.0.1:8080` | HTTP listen address |
| `WS_ADDR` | `127.0.0.1:9000` | WebSocket listen address |
| `SUBNET_ID` | `1` | Gateway's subnet ID |
| `NETWORK` | `forknet` | Network name |
| `GAS_LIMIT` | `500000` | Default gas limit |
| `GAS_PRICE_MULTIPLIER` | `1.1` | Gas price multiplier |
| `REQUIRED_CONFIRMATIONS` | `1` | Required tx confirmations |
| `CONFIRMATION_TIMEOUT_SECS` | `300` | Confirmation timeout |
| `ENABLE_PAYMENT_VERIFICATION` | `true` | Enable payment verification |
| `REQUIRE_PAYMENT` | `false` | Require payment for requests |
***
## Compute Node
### Required
| Variable | Description | Example |
| -------------- | ---------------------------- | ------------------------ |
| `GATEWAY_ADDR` | Gateway address (or CLI arg) | `http://127.0.0.1:50051` |
### Optional
| Variable | Default | Description |
| --------------------------- | ------------------ | ------------------------------------------------ |
| `COMPUTE_NODE_PRIVATE_KEY` | Auto-generated | Node wallet private key |
| `NODE_WALLET_ADDRESS` | Derived | Node wallet address |
| `MODEL_PATH` | `./models` | Model files directory |
| `SANDBOX_MODE` | `strict` | Sandbox mode: `strict`, `permissive`, `disabled` |
| `EXECUTION_TIMEOUT_SECS` | `300` | Max execution time (seconds) |
| `MAX_MEMORY_MB` | `4096` | Max memory per execution (MB) |
| `MAX_CPU_CORES` | All | Max CPU cores per execution |
| `ENABLE_EXECUTION_FALLBACK` | `false` | Enable fallback execution |
| `REQUIRE_PAYMENT` | `false` | Require payment validation |
| `PYTHON_EXECUTOR_PATH` | `python_executors` | Path to Python executors |
| `PYTHON_PATH` | `python3` | Python interpreter path |
| `PYTHON_VENV_PATH` | None | Python virtual environment |
### Sandbox-specific
| Variable | Default | Description |
| ----------------------- | ------- | ------------------------ |
| `SANDBOX_ALLOW_NETWORK` | `false` | Allow network in sandbox |
| `SANDBOX_ALLOWED_PATHS` | `/tmp` | Additional allowed paths |
| `SANDBOX_MAX_PROCESSES` | `10` | Max processes in sandbox |
| `SANDBOX_MAX_FDS` | `1024` | Max file descriptors |
***
## P2P Registry Node
### Required
| Variable | Description | Example |
| -------- | ----------------- | ------- |
| None | All have defaults | - |
### Optional
| Variable | Default | Description |
| ------------------------------ | ----------------------- | ----------------------------- |
| `P2P_LISTEN_ADDR` | `/ip4/0.0.0.0/tcp/8828` | P2P listen address |
| `GRPC_LISTEN_ADDR` | `127.0.0.1:50050` | gRPC listen address |
| `VALIDATOR_PRIVATE_KEY` | Auto-generated | Validator signing key |
| `VALIDATOR_SYNC_ENABLED` | `true` | Enable blockchain sync |
| `VALIDATOR_SYNC_INTERVAL` | `60` | Sync interval (seconds) |
| `VALIDATOR_SYNC_ACTIVE_ONLY` | `false` | Sync only active validators |
| `VALIDATOR_REGISTRY_CONTRACT` | None | On-chain validator registry |
| `FORKNET_RPC_URL` | None | Blockchain RPC URL |
| `CHAIN_ID` | `828` | Blockchain chain ID |
| `MIN_VALIDATORS_FOR_CONSENSUS` | `3` | Minimum validators for M-of-N |
| `MAX_VALIDATORS_TO_SELECT` | `5` | Maximum validators to select |
| `MIN_REPUTATION_THRESHOLD` | `20` | Minimum validator reputation |
***
## Test Client
### Required
| Variable | Description | Example |
| -------- | ------------------------ | ------- |
| None | All configurable via CLI | - |
### Optional
| Variable | Default | Description |
| -------------------- | ------------------------ | ------------------------- |
| `GATEWAY_ADDR` | `http://127.0.0.1:50051` | Gateway gRPC address |
| `CLIENT_PRIVATE_KEY` | None | Client wallet private key |
| `NETWORK` | `local` | Network name |
***
## Smart Contracts (Foundry)
### Deployment
| Variable | Description | Example |
| ------------------- | -------------------- | ----------------------- |
| `PRIVATE_KEY` | Deployer private key | `0xabcd...` |
| `RPC_URL` | RPC endpoint | `http://127.0.0.1:8545` |
| `ETHERSCAN_API_KEY` | For verification | `ABC123...` |
***
## Logging
### All Components
| Variable | Default | Description |
| ---------------- | ------- | ------------------------------------------------------ |
| `RUST_LOG` | `info` | Log level filter |
| `RUST_BACKTRACE` | `0` | Enable backtraces (`1` for basic, `full` for detailed) |
### Log Level Examples
```bash
# Basic info
export RUST_LOG=info
# Debug all
export RUST_LOG=debug
# Debug specific component
export RUST_LOG=gateway_node=debug,compute_node=info
# Trace specific module
export RUST_LOG=gateway_node::payment=trace
# Multiple filters
export RUST_LOG=info,gateway_node=debug,libp2p=warn
```
***
## Docker Environment
### Docker Compose Variables
Create `.env` file in project root:
```bash
# Blockchain
RPC_URL=http://localhost:8545
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
CHAIN_ID=828
# Gateway
GATEWAY_PRIVATE_KEY=0x...
GATEWAY_WALLET_ADDRESS=0x...
# Compute
COMPUTE_PRIVATE_KEY=0x...
SANDBOX_MODE=disabled
# Registry
VALIDATOR_PRIVATE_KEY=0x...
VALIDATOR_SYNC_ENABLED=true
# General
RUST_LOG=info
```
***
## Security Notes
### Sensitive Variables
**NEVER commit these to version control:**
* `*_PRIVATE_KEY`
* `*_SECRET`
* API keys
### Best Practices
```bash
# Use environment variables
export GATEWAY_WALLET_PRIVATE_KEY="$SECRET_FROM_VAULT"
# Or use .env file (add to .gitignore)
echo ".env" >> .gitignore
# Use secrets manager in production
# (AWS Secrets Manager, HashiCorp Vault, etc.)
```
***
## Quick Setup Templates
### Development
```bash
# Development mode - no payment, no sandbox
export RUST_LOG=debug
export REQUIRE_PAYMENT=false
export SANDBOX_MODE=disabled
export ENABLE_EXECUTION_FALLBACK=true
```
### Testing
```bash
# Testing mode - permissive sandbox
export RUST_LOG=info
export REQUIRE_PAYMENT=false
export SANDBOX_MODE=permissive
export ENABLE_EXECUTION_FALLBACK=true
```
### Production
```bash
# Production mode - strict security
export RUST_LOG=info
export REQUIRE_PAYMENT=true
export SANDBOX_MODE=strict
export ENABLE_EXECUTION_FALLBACK=false
export REQUIRED_CONFIRMATIONS=12
```
***
## Variable Priority
Configuration priority (highest to lowest):
1. Command line arguments
2. Environment variables
3. `.env` file
4. Default values
```bash
# CLI overrides environment variable
export GRPC_ADDR=127.0.0.1:50051
cargo run --bin gateway_node -- --grpc-addr 0.0.0.0:50051
# Uses 0.0.0.0:50051
```
# Overview
Complete API documentation for NCN Network v2 services.
***
## Overview
NCN Network exposes multiple API interfaces:
| Interface | Protocol | Primary Use |
| --------------------- | ------------- | --------------------------------------- |
| **Gateway gRPC** | gRPC/Protobuf | Compute nodes, high-performance clients |
| **Gateway HTTP** | REST/JSON | Web clients, simple integrations |
| **Gateway WebSocket** | WebSocket | Real-time updates |
| **Registry gRPC** | gRPC/Protobuf | Gateways, validators |
***
## API Documentation
### [Protobuf Definitions](/nc/neurochainai-guides/api-reference/protobuf)
Protocol Buffer message and service definitions:
* Complete `.proto` file documentation
* Message type reference
* Service definitions
### [Gateway gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/gateway-grpc.md)
Gateway gRPC service documentation:
* `GatewayClientService` - Client-facing RPCs
* `GatewayComputeService` - Compute node RPCs
* Request/Response formats
* Error handling
### [Registry gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/registry-grpc.md)
P2P Registry gRPC service documentation:
* `P2PRegistryService` - All registry RPCs
* Node management
* Validation RPCs
* Subnet management
### [HTTP Endpoints](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/http-endpoints.md)
Gateway HTTP REST API:
* Inference endpoints
* Status endpoints
* Health checks
### [WebSocket Events](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/websocket-events.md)
Gateway WebSocket API:
* Connection management
* Event types
* Subscription patterns
### [Error Codes](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/error-codes.md)
Error code reference:
* gRPC status codes
* HTTP status codes
* Application-specific errors
***
## Quick Reference
### Gateway Endpoints
| Protocol | Address | Purpose |
| --------- | -------- | --------------------------- |
| gRPC | `:50051` | Compute nodes, gRPC clients |
| HTTP | `:8080` | REST API |
| WebSocket | `:9000` | Real-time updates |
### Registry Endpoints
| Protocol | Address | Purpose |
| -------- | -------- | ----------------------- |
| gRPC | `:50050` | All registry operations |
| P2P | `:8828` | Peer-to-peer networking |
***
## Common Patterns
### Submit Inference Request (gRPC)
```protobuf
// Request
message InferenceRequest {
string request_id = 1;
string model_uuid = 2;
string input_data = 3;
string originator_client_id = 4;
}
// Response
message InferenceTaskStatus {
string request_id = 1;
string status = 2; // "queued", "processing", "completed", "failed"
string error_message = 3;
}
```
### Submit Inference Request (HTTP)
```http
POST /api/v1/inference HTTP/1.1
Host: gateway.example.com
Content-Type: application/json
{
"model_uuid": "bark_semantic",
"input_data": "{\"text\": \"Hello world\"}"
}
```
**Response:**
```json
{
"request_id": "req-abc123",
"status": "queued"
}
```
### Subscribe to Updates (WebSocket)
```javascript
const ws = new WebSocket('wss://gateway.example.com/ws');
ws.send(JSON.stringify({
type: 'subscribe',
request_id: 'req-abc123'
}));
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Status:', data.status);
};
```
***
## Authentication
### Current Status
NCN Network v2 currently uses wallet-based authentication:
* **Clients**: Sign requests with wallet
* **Compute Nodes**: Authenticate via signature
* **Validators**: Sign validations with registered key
### Future: API Keys
API key authentication is planned for HTTP endpoints:
```http
Authorization: Bearer YOUR_API_KEY
```
***
## Rate Limiting
### Current Limits
| Endpoint | Limit |
| -------------- | ----------------- |
| HTTP Inference | 100 req/min |
| gRPC Submit | 1000 req/min |
| WebSocket | 10 connections/IP |
### Rate Limit Headers
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067260
```
***
## Versioning
### API Version
Current version: **v1**
### Version Header
```http
X-API-Version: v1
```
### Deprecation Policy
* Breaking changes require major version bump
* Deprecated endpoints marked in headers
* 6-month deprecation notice
***
## SDK Support
### Official SDKs
| Language | Status | Repository |
| ---------- | ---------- | ------------- |
| Rust | ✅ Built-in | `test_client` |
| Python | 🚧 Planned | - |
| JavaScript | 🚧 Planned | - |
| Go | 🚧 Planned | - |
### Generate Client Code
```bash
# Python gRPC client
python -m grpc_tools.protoc \
-I./proto \
--python_out=./client \
--grpc_python_out=./client \
proto/common_types.proto
# Go gRPC client
protoc \
--go_out=./client \
--go-grpc_out=./client \
proto/common_types.proto
```
***
## Testing APIs
### gRPC Testing (grpcurl)
```bash
# List services
grpcurl -plaintext localhost:50051 list
# Call method
grpcurl -plaintext \
-d '{"model_uuid": "test", "input_data": "{}"}' \
localhost:50051 common_types.GatewayClientService/SubmitInferenceTask
```
### HTTP Testing (curl)
```bash
# Submit inference
curl -X POST http://localhost:8080/api/v1/inference \
-H "Content-Type: application/json" \
-d '{"model_uuid": "test", "input_data": "{}"}'
# Check health
curl http://localhost:8080/health
```
### WebSocket Testing (wscat)
```bash
# Connect
wscat -c ws://localhost:9000
# Send message
{"type": "subscribe", "request_id": "req-123"}
```
***
## Next Steps
* [Protobuf Definitions](/nc/neurochainai-guides/api-reference/protobuf) - Complete proto documentation
* [Gateway gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/gateway-grpc.md) - Gateway RPC reference
* [HTTP Endpoints](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/http-endpoints.md) - REST API reference
* [Error Codes](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/error-codes.md) - Error handling
# Protocol Buffers
Complete reference for NCN Network v2 Protocol Buffer definitions.
***
## Overview
NCN Network uses Protocol Buffers (protobuf) for all gRPC communication. The definitions are in `proto/common_types.proto`.
***
## Services
### GatewayClientService
Client-facing service exposed by Gateway nodes.
```protobuf
service GatewayClientService {
// Submit an inference task
rpc SubmitInferenceTask(InferenceRequest) returns (InferenceTaskStatus);
// Subscribe to task updates (streaming)
rpc SubscribeToTaskUpdates(TaskID) returns (stream InferenceResponse);
// Get current task status
rpc GetTaskStatus(TaskID) returns (InferenceTaskStatus);
// Cancel a task
rpc CancelTask(TaskID) returns (Ack);
// Confirm payment was made
rpc ConfirmPayment(TransactionConfirmation) returns (Ack);
// Get supported models
rpc GetSupportedModels(Empty) returns (stream ModelInfo);
}
```
### GatewayComputeService
Compute node-facing service exposed by Gateway nodes.
```protobuf
service GatewayComputeService {
// Register compute node
rpc RegisterComputeNode(NodeInfo) returns (Ack);
// Update heartbeat
rpc UpdateHeartbeat(HeartbeatRequest) returns (Ack);
// Receive task stream
rpc ReceiveTask(NodeInfo) returns (stream InferenceRequest);
// Submit completed result
rpc SubmitResult(InferenceResponse) returns (Ack);
// Get task by ID
rpc GetTask(TaskID) returns (InferenceRequest);
}
```
### P2PRegistryService
Registry service for node discovery and validation.
```protobuf
service P2PRegistryService {
// Node management
rpc RegisterNode(NodeInfo) returns (Ack);
rpc UpdateNodeHeartbeat(UpdateNodeHeartbeatRequest) returns (Ack);
rpc DeregisterNode(WalletAddress) returns (Ack);
rpc DiscoverNodes(DiscoverNodesRequest) returns (stream NodeInfo);
// Validation
rpc RequestPreprocessingValidation(InferenceRequest) returns (PreprocessingValidation);
rpc RequestCompletionValidation(InferenceResponse) returns (CompletionValidation);
// Subnet management
rpc EstimateSubnetFee(EstimateSubnetFeeRequest) returns (EstimateSubnetFeeResponse);
rpc CreateSubnet(CreateSubnetRequest) returns (CreateSubnetResponse);
rpc GetSubnet(GetSubnetRequest) returns (GetSubnetResponse);
rpc ListSubnets(Empty) returns (stream SubnetMetadata);
// Validator management
rpc RegisterValidator(RegisterValidatorRequest) returns (RegisterValidatorResponse);
rpc UnregisterValidator(UnregisterValidatorRequest) returns (Ack);
rpc GetValidatorInfo(ValidatorAddressRequest) returns (ValidatorInfoResponse);
rpc ListValidators(ListValidatorsRequest) returns (stream ValidatorInfoMessage);
}
```
***
## Core Messages
### InferenceRequest
Request for model inference.
```protobuf
message InferenceRequest {
string request_id = 1; // Unique request identifier
string model_uuid = 2; // Model to use
string input_data = 3; // JSON-encoded input
string originator_client_id = 4; // Client wallet address
// Payment information (optional)
optional PreprocessingValidation preprocessing_validation = 5;
optional TransactionConfirmation transaction_confirmation = 6;
optional int64 assigned_timestamp = 7;
optional string assigned_compute_node_id = 8;
}
```
### InferenceResponse
Response from model inference.
```protobuf
message InferenceResponse {
string request_id = 1;
string model_uuid = 2;
string output_data = 3; // JSON-encoded output
string status = 4; // "completed", "failed", "processing"
string error_message = 5;
// Compute node attestation
optional ComputeCompletion compute_completion = 6;
// Validation
optional CompletionValidation completion_validation = 7;
}
```
### NodeInfo
Information about a network node.
```protobuf
message NodeInfo {
string node_id = 1; // Unique node identifier
string node_type = 2; // "compute", "gateway", "validator"
string ip_address = 3; // Node IP address
uint32 port = 4; // Node port
repeated string capabilities = 5; // Supported features
string wallet_address = 6; // Node's wallet address
int64 last_heartbeat = 7; // Unix timestamp
// Model support
repeated ModelData supported_models = 8;
// Subnet membership
optional uint64 subnet_id = 9;
}
```
***
## Payment Messages
### PaymentTree
Payment distribution specification.
```protobuf
message PaymentTree {
string compute_price_wei = 1; // Wei for compute node
string gateway_gas_wei = 2; // Wei for gateway
string validator_reward_wei = 3; // Wei for validators
string treasury_fee_wei = 4; // Wei for treasury
}
```
### PreprocessingValidation
Validator approval for payment initiation.
```protobuf
message PreprocessingValidation {
string request_id = 1;
string gateway_wallet = 2;
string compute_node_id = 3;
string compute_node_wallet = 4;
PaymentTree payment_tree = 5;
repeated ValidatorSignature validator_signatures = 6;
int64 expiry_timestamp = 7;
}
```
### TransactionConfirmation
Blockchain transaction confirmation.
```protobuf
message TransactionConfirmation {
string request_id = 1;
string tx_hash = 2; // Transaction hash
uint64 block_number = 3; // Confirmation block
uint64 confirmations = 4; // Number of confirmations
string originator_wallet = 5; // Payer address
string amount_wei = 6; // Amount paid
int64 timestamp = 7; // Confirmation time
}
```
### ComputeCompletion
Compute node's result attestation.
```protobuf
message ComputeCompletion {
string request_id = 1;
string compute_node_signature = 2; // Signature over result
bytes result_hash = 3; // SHA-256 of result
int64 completion_timestamp = 4;
uint64 computation_time_ms = 5;
}
```
### CompletionValidation
Validator approval for payment distribution.
```protobuf
message CompletionValidation {
string request_id = 1;
repeated ValidatorSignature validator_signatures = 2;
ComputeCompletion compute_completion = 3;
}
```
### ValidatorSignature
Individual validator signature.
```protobuf
message ValidatorSignature {
string validator_address = 1; // Validator wallet
string signature = 2; // Hex-encoded signature
int64 timestamp = 3; // Signature time
}
```
***
## Subnet Messages
### SubnetMetadata
Subnet configuration and status.
```protobuf
message SubnetMetadata {
uint64 subnet_id = 1;
string gateway_address = 2;
int64 created_at = 3;
repeated ModelDescriptor models = 4;
repeated ValidatorSignature validated_by = 5;
string network_fee_wei = 6;
string payment_tx = 7;
string status = 9; // "pending", "active", "deprecated"
}
```
### ModelDescriptor
Model specification in subnet.
```protobuf
message ModelDescriptor {
string model_uuid = 1; // Unique model ID
string source = 2; // "huggingface", "path", "url"
string path = 3; // Model path/URL
string name = 4; // Display name
string category = 5; // "text", "audio", "vision"
string description = 6; // Model description
int64 max_tokens = 7; // Max tokens supported
string version = 8; // Model version
string input_format = 9; // Expected input format
string output_format = 10; // Output format
}
```
### CreateSubnetRequest
Request to create a new subnet.
```protobuf
message CreateSubnetRequest {
string gateway_address = 1;
repeated ModelDescriptor models = 2;
string fee_quote_id = 3; // From EstimateSubnetFee
string payment_tx = 4; // Transaction hash
bytes config_hash = 5; // Hash of configuration
}
```
***
## Status Messages
### InferenceTaskStatus
Current status of an inference task.
```protobuf
message InferenceTaskStatus {
string request_id = 1;
string status = 2; // "queued", "processing", "completed", "failed"
string error_message = 3;
// Payment status
optional PaymentStatus payment_status = 4;
optional PreprocessingValidation preprocessing_validation = 5;
}
```
### PaymentStatus
Status of payment flow.
```protobuf
message PaymentStatus {
bool required = 1; // Is payment required?
bool preprocessing_complete = 2; // Validation received?
bool payment_confirmed = 3; // Transaction confirmed?
bool completion_validated = 4; // Result validated?
PaymentTree payment_tree = 5; // Payment amounts
string contract_address = 6; // Contract to pay
}
```
***
## Utility Messages
### TaskID
```protobuf
message TaskID {
string id = 1;
}
```
### Ack
```protobuf
message Ack {
bool success = 1;
string message = 2;
}
```
### Empty
```protobuf
message Empty {}
```
### WalletAddress
```protobuf
message WalletAddress {
string address = 1;
}
```
***
## Error Handling
### gRPC Status Codes
| Code | Meaning | When Used |
| ----------------------- | ------------ | ---------------------- |
| OK (0) | Success | Request completed |
| CANCELLED (1) | Cancelled | Task cancelled |
| INVALID\_ARGUMENT (3) | Bad input | Invalid request format |
| NOT\_FOUND (5) | Not found | Unknown task/model |
| ALREADY\_EXISTS (6) | Duplicate | Request ID exists |
| RESOURCE\_EXHAUSTED (8) | Rate limited | Too many requests |
| INTERNAL (13) | Server error | Processing error |
| UNAVAILABLE (14) | Service down | Node unavailable |
***
## Code Generation
### Rust (tonic)
```bash
# Build generates automatically with build.rs
cargo build
```
### Python
```bash
pip install grpcio-tools
python -m grpc_tools.protoc \
-I./proto \
--python_out=./generated \
--grpc_python_out=./generated \
proto/common_types.proto
```
### Go
```bash
protoc \
--go_out=./generated \
--go-grpc_out=./generated \
proto/common_types.proto
```
### JavaScript
```bash
npm install grpc-tools
grpc_tools_node_protoc \
--js_out=import_style=commonjs:./generated \
--grpc_out=./generated \
proto/common_types.proto
```
***
## Related Documentation
* [Gateway gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/gateway-grpc.md) - Gateway service details
* [Registry gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/registry-grpc.md) - Registry service details
* [HTTP Endpoints](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/http-endpoints.md) - REST API reference
# Overview
This section documents the security architecture and best practices for NCN Network v2.
***
## Security Model
NCN Network v2 employs a **defense-in-depth** security model with multiple layers of protection:
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Security Layers │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 1: Network Security │ │
│ │ • TLS encryption for all connections │ │
│ │ • Rate limiting and DDoS protection │ │
│ │ • Firewall rules and network isolation │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 2: Authentication & Authorization │ │
│ │ • Wallet-based authentication │ │
│ │ • Cryptographic signatures │ │
│ │ • Role-based access control │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 3: Execution Security │ │
│ │ • Sandboxed model execution │ │
│ │ • System call filtering (seccomp) │ │
│ │ • Process isolation (namespaces) │ │
│ │ • Filesystem isolation (Landlock) │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 4: Economic Security │ │
│ │ • Validator staking │ │
│ │ • Slashing for misbehavior │ │
│ │ • Escrow-based payments │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Layer 5: Cryptographic Security │ │
│ │ • Result signing (secp256k1) │ │
│ │ • Message hashing (SHA-256) │ │
│ │ • Signature verification │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Security Documentation
### [Sandbox Security](https://github.com/NeuroChainAi/docs-guides/blob/main/security/sandbox-security.md)
Compute node sandbox isolation:
* seccomp syscall filtering
* Linux namespace isolation
* Landlock filesystem rules
* Resource limits
### [Cryptographic Signing](https://github.com/NeuroChainAi/docs-guides/blob/main/security/cryptographic-signing.md)
Signature schemes and verification:
* secp256k1 ECDSA signatures
* Message hashing
* Key management
* Verification process
### [Payment Security](https://github.com/NeuroChainAi/docs-guides/blob/main/security/payment-security.md)
Smart contract security:
* Escrow mechanism
* Signature verification
* Reentrancy protection
* Expiry handling
### [Network Security](https://github.com/NeuroChainAi/docs-guides/blob/main/security/network-security.md)
Network-level protections:
* TLS configuration
* Rate limiting
* DDoS protection
* Firewall rules
### [Best Practices](https://github.com/NeuroChainAi/docs-guides/blob/main/security/best-practices.md)
Security recommendations:
* Key management
* Deployment hardening
* Monitoring
* Incident response
***
## Threat Model
### Assets to Protect
| Asset | Criticality | Protection |
| ------------------------ | ----------- | -------------------------------------- |
| **User Funds** | Critical | Escrow, signatures, validators |
| **Private Keys** | Critical | Never stored on-chain, HSM recommended |
| **Model Data** | High | Sandboxing, access control |
| **User Data** | High | Encryption, minimal retention |
| **Service Availability** | Medium | Redundancy, rate limiting |
### Threat Actors
| Actor | Motivation | Mitigations |
| ---------------------- | ----------------------- | ------------------ |
| **Malicious Model** | Execute arbitrary code | Sandbox isolation |
| **Rogue Compute Node** | Steal funds, data | Signatures, escrow |
| **Rogue Validator** | Approve invalid results | M-of-N consensus |
| **External Attacker** | DoS, exploitation | Rate limiting, TLS |
| **Man-in-the-Middle** | Intercept data | TLS, signatures |
### Attack Vectors
```
Attack Surface
┌─────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────┐ Network Attacks │
│ │ Network │ • DDoS │
│ │ Layer │ • Man-in-the-middle │
│ └──────┬──────┘ • DNS hijacking │
│ │ │
│ ▼ │
│ ┌─────────────┐ Application Attacks │
│ │ Application │ • API abuse │
│ │ Layer │ • Input manipulation │
│ └──────┬──────┘ • Authentication bypass │
│ │ │
│ ▼ │
│ ┌─────────────┐ Execution Attacks │
│ │ Execution │ • Sandbox escape │
│ │ Layer │ • Resource exhaustion │
│ └──────┬──────┘ • Malicious code execution │
│ │ │
│ ▼ │
│ ┌─────────────┐ Economic Attacks │
│ │ Economic │ • Double spending │
│ │ Layer │ • Front-running │
│ └─────────────┘ • Validator collusion │
│ │
└─────────────────────────────────────────────────────────┘
```
***
## Security Features
### Implemented ✅
| Feature | Description | Component |
| ---------------------- | ----------------------------- | -------------- |
| Sandboxed Execution | seccomp, namespaces, Landlock | Compute Node |
| Signature Verification | secp256k1 ECDSA | All components |
| M-of-N Consensus | Distributed validation | Registry |
| Escrow Payments | Funds held until completion | Smart Contract |
| Request Expiry | Automatic refunds | Smart Contract |
| Reentrancy Guard | Prevent reentrancy attacks | Smart Contract |
| Resource Limits | CPU, memory, time bounds | Compute Node |
### Recommended for Production 🚧
| Feature | Description | Status |
| ------------------ | ----------------------- | ------------- |
| TLS Everywhere | Encrypt all connections | Configuration |
| API Authentication | API keys for clients | Planned |
| Rate Limiting | Prevent abuse | Partial |
| Security Audit | External audit | Recommended |
| Bug Bounty | Incentivize disclosure | Recommended |
***
## Key Management
### Best Practices
```
┌─────────────────────────────────────────────────────────┐
│ Key Management │
│ │
│ Development Staging Production │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
│ │ Environment │ │ Environment │ │ HSM / ││
│ │ Variables │ │ Variables │ │ Vault ││
│ │ │ │ + Secrets │ │ ││
│ │ (Ephemeral)│ │ Manager │ │ (Hardware) ││
│ └─────────────┘ └─────────────┘ └─────────────┘│
│ │
│ Security Level: │
│ Low ────────────────────────────────────────▶ High │
│ │
└─────────────────────────────────────────────────────────┘
```
### Key Types
| Key Type | Owner | Storage Recommendation |
| -------------- | ---------------- | ---------------------- |
| Gateway Wallet | Gateway Operator | Hardware wallet / HSM |
| Compute Wallet | Compute Operator | Secure enclave |
| Validator Key | Validator | HSM |
| Client Wallet | User | User-controlled |
***
## Incident Response
### Response Levels
| Level | Trigger | Response |
| ----------------- | ----------------------- | ------------------------------ |
| **P0 - Critical** | Fund loss, exploit | Immediate pause, investigation |
| **P1 - High** | Service outage | 1-hour response |
| **P2 - Medium** | Performance degradation | 4-hour response |
| **P3 - Low** | Minor issues | 24-hour response |
### Response Process
```
Detection → Triage → Containment → Investigation → Remediation → Post-mortem
```
***
## Compliance
### Data Handling
| Data Type | Retention | Protection |
| --------------- | --------------------- | ------------------- |
| Request data | 30 days | Encrypted at rest |
| Payment records | Indefinite (on-chain) | Blockchain security |
| Logs | 90 days | Access controlled |
| User data | Minimal | GDPR compliant |
### Audit Trail
All operations are logged:
* Request submissions
* Payment transactions
* Validation events
* Access attempts
***
## Security Checklist
### Pre-Deployment
* [ ] Generate unique keys for each component
* [ ] Configure TLS certificates
* [ ] Set up firewall rules
* [ ] Enable rate limiting
* [ ] Configure logging
* [ ] Test backup/recovery
### Production
* [ ] Regular key rotation
* [ ] Monitor for anomalies
* [ ] Keep dependencies updated
* [ ] Conduct security reviews
* [ ] Maintain incident playbook
* [ ] Test disaster recovery
***
## Reporting Security Issues
### Responsible Disclosure
Please report security vulnerabilities to:
* Email:
* PGP Key: \[Available on request]
### What to Include
1. Description of vulnerability
2. Steps to reproduce
3. Potential impact
4. Suggested fix (if any)
### Response Timeline
* Acknowledgment: 24 hours
* Initial assessment: 72 hours
* Fix timeline: Depends on severity
***
## Next Steps
* [Sandbox Security](https://github.com/NeuroChainAi/docs-guides/blob/main/security/sandbox-security.md) - Isolation details
* [Cryptographic Signing](https://github.com/NeuroChainAi/docs-guides/blob/main/security/cryptographic-signing.md) - Signature verification
* [Best Practices](https://github.com/NeuroChainAi/docs-guides/blob/main/security/best-practices.md) - Security recommendations
# Overview
This section helps you diagnose and resolve common issues with NCN Network v2.
***
## Quick Diagnostics
### Health Check Commands
```bash
# Check Gateway
curl http://localhost:8080/health
# Check P2P Registry (if health endpoint available)
grpcurl -plaintext localhost:50050 grpc.health.v1.Health/Check
# Check process status
ps aux | grep -E "(gateway|compute|registry)"
# Check port bindings
netstat -tlnp | grep -E "(50050|50051|8080|9000|8828)"
```
### Log Locations
| Component | Log Location |
| --------- | -------------------------------------- |
| Gateway | stdout/stderr or `./logs/gateway.log` |
| Compute | stdout/stderr or `./logs/compute.log` |
| Registry | stdout/stderr or `./logs/registry.log` |
### Enable Debug Logging
```bash
# Full debug
export RUST_LOG=debug
# Component-specific
export RUST_LOG=gateway_node=debug,compute_node=info
# Trace specific module
export RUST_LOG=gateway_node::payment=trace
```
***
## Troubleshooting Guides
### [Common Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/common-issues.md)
General issues affecting all components:
* Build failures
* Configuration errors
* Network connectivity
### [Gateway Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/gateway-issues.md)
Gateway-specific problems:
* Connection failures
* Payment processing
* Compute node management
### [Compute Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/compute-issues.md)
Compute node problems:
* Sandbox failures
* Model loading
* Execution timeouts
### [Payment Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/payment-issues.md)
Blockchain and payment problems:
* Transaction failures
* Confirmation delays
* Refund issues
### [FAQ](/nc/neurochainai-guides/troubleshooting/faq)
Frequently asked questions
***
## Common Issues Quick Reference
### Build Failures
| Error | Cause | Solution |
| ------------------- | ------------------- | --------------------------- |
| `linker not found` | Missing build tools | Install `build-essential` |
| `protoc not found` | Missing protoc | Install `protobuf-compiler` |
| `cannot find -lssl` | Missing OpenSSL | Install `libssl-dev` |
### Connection Failures
| Error | Cause | Solution |
| ----------------------- | ------------------- | --------------------- |
| `Connection refused` | Service not running | Start the service |
| `DNS resolution failed` | Wrong hostname | Check service address |
| `TLS handshake failed` | Certificate issue | Verify TLS config |
### Execution Failures
| Error | Cause | Solution |
| ------------------- | ------------------- | --------------------- |
| `Timeout exceeded` | Slow execution | Increase timeout |
| `Out of memory` | Model too large | Increase memory limit |
| `Permission denied` | Sandbox restriction | Check sandbox config |
***
## Error Messages
### Gateway Errors
```
Error: No compute nodes available for model X
```
**Cause**: No compute node supports the requested model **Solution**:
* Verify compute nodes are connected
* Check model is in subnet
* Verify compute node's `--model-path`
```
Error: Payment verification failed: Transaction not found
```
**Cause**: Blockchain transaction not visible **Solution**:
* Wait for more confirmations
* Verify RPC URL is correct
* Check transaction hash
### Compute Node Errors
```
Error: Sandbox execution failed: seccomp violation
```
**Cause**: Model attempted blocked syscall **Solution**:
* Check model compatibility
* Use `SANDBOX_MODE=permissive` for debugging
* Review seccomp filter
```
Error: Model not found at path X
```
**Cause**: Model file missing **Solution**:
* Verify `--model-path` is correct
* Enable `--sync-models` for auto-download
* Check file permissions
### Registry Errors
```
Error: Insufficient validators for consensus
```
**Cause**: Not enough validators available **Solution**:
* Register more validators
* Check validator connectivity
* Reduce `MIN_VALIDATORS_FOR_CONSENSUS`
***
## Diagnostic Tools
### Network Diagnostics
```bash
# Test gRPC connectivity
grpcurl -plaintext localhost:50051 list
# Test HTTP endpoint
curl -v http://localhost:8080/api/v1/health
# Check P2P peers
# (If diagnostic endpoint available)
```
### Process Diagnostics
```bash
# Check memory usage
ps -o pid,rss,command -p $(pgrep gateway_node)
# Check open files
lsof -p $(pgrep gateway_node) | head -20
# Check network connections
ss -tlnp | grep gateway
```
### Blockchain Diagnostics
```bash
# Check RPC connectivity
curl -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
# Check contract
cast call $CONTRACT_ADDRESS "minValidatorSignatures()" --rpc-url $RPC_URL
```
***
## Recovery Procedures
### Gateway Recovery
1. **Stop gateway**: `pkill gateway_node`
2. **Check state file**: `ls -la ./data/gateway_state.json`
3. **Backup if needed**: `cp ./data/gateway_state.json ./data/gateway_state.json.bak`
4. **Restart**: `cargo run --bin gateway_node`
### Compute Node Recovery
1. **Stop compute node**: `pkill compute_node`
2. **Clear model cache**: `rm -rf ./cache/*`
3. **Verify models**: `ls -la ./models/`
4. **Restart**: `cargo run --bin compute_node -- --gateway-addr http://localhost:50051`
### Registry Recovery
1. **Stop registry**: `pkill p2p_registry`
2. **Check DHT data**: `ls -la ./data/dht/`
3. **Clear if corrupted**: `rm -rf ./data/dht/*`
4. **Restart**: `cargo run --bin p2p_registry_node`
***
## Getting Help
### Information to Provide
When reporting issues, include:
1. **Component and version**: `cargo run --bin gateway_node -- --version`
2. **OS and architecture**: `uname -a`
3. **Full error message**: Copy complete error
4. **Logs**: Relevant log excerpts
5. **Configuration**: Sanitized config (no private keys!)
6. **Steps to reproduce**: How to trigger the issue
### Support Channels
* **GitHub Issues**: Bug reports and feature requests
* **Documentation**: This troubleshooting guide
* **Community**: \[Discord/Telegram link if available]
***
## Debug Mode
### Enable Debug Mode
```bash
# Maximum debug output
export RUST_LOG=trace
export RUST_BACKTRACE=1
# Run with debug mode
cargo run --bin gateway_node
```
### Debug Specific Issues
```bash
# Debug sandbox only
export RUST_LOG=compute_node::sandbox=trace
# Debug payment only
export RUST_LOG=gateway_node::payment=trace
# Debug P2P networking
export RUST_LOG=libp2p=debug,p2p_registry_node=trace
```
### Performance Profiling
```bash
# Enable profiling
cargo build --release --features profiling
# Run with profiler
perf record -g ./target/release/gateway_node
perf report
```
***
## Next Steps
* [Common Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/common-issues.md) - Detailed solutions
* [Gateway Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/gateway-issues.md) - Gateway-specific help
* [Compute Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/compute-issues.md) - Compute node help
* [FAQ](/nc/neurochainai-guides/troubleshooting/faq) - Frequently asked questions
# FAQ
Common questions about NCN Network v2.
***
## General Questions
### What is NCN Network?
NCN Network v2 is a decentralized AI inference network that connects clients who need AI computation with compute providers who have GPU/CPU resources. It uses blockchain-based payments and validator consensus to ensure fair and secure computation.
### How does NCN differ from centralized AI services?
| Aspect | Centralized | NCN Network |
| ---------------- | -------------------- | ------------------ |
| **Control** | Single company | Decentralized |
| **Pricing** | Fixed by provider | Market-driven |
| **Availability** | Vendor dependent | Multiple providers |
| **Censorship** | Possible | Resistant |
| **Payment** | Subscription/API key | Pay-per-use crypto |
### What AI models are supported?
NCN supports:
* **TorchScript** models (`.pt`, `.pth`)
* **ONNX** models (`.onnx`)
* **Safetensors** models
* **Custom models** with executor scripts
### Is NCN production-ready?
NCN Network v2 is approximately 85% complete. It's suitable for:
* ✅ Development and testing
* ✅ Beta deployments
* ⚠️ Production (with caution)
See [Project Status](/nc/neurochainai-guides) for current completion status.
***
## Technical Questions
### What programming languages are supported?
**Backend Services**: Rust **Model Execution**: Python (PyTorch, Transformers) **Smart Contracts**: Solidity **Client Libraries**: Currently Rust, others planned
### What are the hardware requirements?
**Gateway Node**:
* CPU: 2+ cores
* RAM: 4 GB
* Storage: 50 GB
**Compute Node**:
* CPU: 4+ cores
* RAM: 8+ GB (16 GB recommended)
* GPU: Optional but recommended for ML workloads
* Storage: 100+ GB
**P2P Registry**:
* CPU: 2+ cores
* RAM: 4 GB
* Storage: 50 GB
### How does the sandbox work?
The compute node sandbox uses multiple Linux security features:
1. **seccomp** - Filters system calls
2. **Namespaces** - Isolates processes, network, filesystem
3. **Landlock** - Controls filesystem access
4. **Resource limits** - Bounds CPU, memory, time
See [Sandbox Security](https://github.com/NeuroChainAi/docs-guides/blob/main/security/sandbox-security.md) for details.
### Can I run NCN on macOS or Windows?
* **Linux**: Full support (recommended for production)
* **macOS**: Development support (limited sandbox features)
* **Windows**: Experimental (sandbox not available)
***
## Payment Questions
### How do payments work?
1. Client submits request
2. Validators sign preprocessing validation
3. Client pays to smart contract (escrow)
4. Compute node executes model
5. Validators sign completion validation
6. Smart contract distributes payment
See [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow) for details.
### What cryptocurrencies are supported?
NCN uses ERC20 tokens on Ethereum-compatible chains:
* **Testnet**: NCN Token on Forknet
* **Future**: ETH, stablecoins planned
### What happens if a request fails?
* **Compute failure**: Request expires, automatic refund
* **Validator rejection**: Request cannot complete, refund on expiry
* **Network failure**: Request times out, automatic refund
### How are fees calculated?
```
Total Fee = Compute Price + Gateway Gas + Validator Reward + Treasury Fee
```
Typical distribution:
* 80% to Compute Node
* 10% to Gateway
* 5% to Validators
* 5% to Treasury
***
## Operator Questions
### How do I become a Gateway operator?
1. Set up a Gateway node
2. Create a subnet with models
3. Pay subnet creation fee
4. Attract compute nodes and clients
See [Gateway Operator Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/gateway-operator.md).
### How do I become a Compute provider?
1. Set up a Compute node
2. Join a subnet
3. Download/configure models
4. Start receiving tasks
See [Compute Operator Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/compute-operator.md).
### How do I become a Validator?
1. Stake required tokens
2. Run P2P Registry node with validator key
3. Participate in validation consensus
See [Validator Operator Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/validator-operator.md).
### How much can I earn?
Earnings depend on:
* **Gateways**: Routing fee per request
* **Compute**: Execution fee per request
* **Validators**: Validation reward per request
Typical fees: See [Payment Flow](/nc/neurochainai-guides/architecture/payment-flow).
***
## Development Questions
### How do I add a custom model?
1. Export model to TorchScript/ONNX
2. Create executor script
3. Configure subnet with model
4. Deploy to compute nodes
See [Use Cases - Custom Models](/nc/neurochainai-guides/introduction/use-cases#custom-model-deployment).
### How do I run tests?
```bash
# Rust tests
cargo test --all
# Contract tests
cd contracts && forge test -vvv
# Integration tests
./scripts/run_integration_tests.sh
```
### How do I debug issues?
```bash
# Enable debug logging
export RUST_LOG=debug
export RUST_BACKTRACE=1
# Run component
cargo run --bin gateway_node
```
See [Debugging Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/development/debugging.md).
### Where can I find API documentation?
* [API Reference](/nc/neurochainai-guides/api-reference/api-reference) - Overview
* [Protobuf Definitions](/nc/neurochainai-guides/api-reference/protobuf) - Proto files
* [HTTP Endpoints](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/http-endpoints.md) - REST API
***
## Security Questions
### Is NCN secure?
NCN implements multiple security layers:
* ✅ Sandboxed execution
* ✅ Cryptographic signatures
* ✅ Validator consensus
* ✅ Escrow payments
* ⚠️ External audit (recommended before production)
See [Security Overview](/nc/neurochainai-guides/security/security).
### What if a malicious model is uploaded?
The sandbox prevents:
* Network access
* Filesystem access outside allowed paths
* Dangerous system calls
* Resource exhaustion
Malicious code is contained and cannot affect the host system.
### What if validators collude?
The M-of-N consensus requires 3 of 5 validators to agree. Collusion requires:
* Compromising multiple validators
* Overcoming stake-based selection
* Risking slashing penalties
Economic incentives discourage collusion.
### How are private keys protected?
Private keys should be:
* Never stored on-chain
* Kept in secure storage (HSM for production)
* Never committed to version control
* Rotated regularly
See [Best Practices](https://github.com/NeuroChainAi/docs-guides/blob/main/security/best-practices.md).
***
## Troubleshooting Questions
### Why can't I connect to the Gateway?
Common causes:
1. Gateway not running
2. Wrong address/port
3. Firewall blocking
4. Network issues
```bash
# Check if running
ps aux | grep gateway
# Test connection
curl http://localhost:8080/health
```
### Why is my inference request failing?
Check:
1. Model exists on compute node
2. Input format is correct
3. Payment was submitted (if required)
4. Compute node is not busy
See [Common Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/common-issues.md).
### Why is the sandbox failing?
Common causes:
1. Running on non-Linux system
2. Missing kernel features
3. Incompatible model code
Try `SANDBOX_MODE=permissive` for debugging.
See [Compute Issues](https://github.com/NeuroChainAi/docs-guides/blob/main/troubleshooting/compute-issues.md).
***
## Future Plans
### What's on the roadmap?
* Model auto-downloader (Phase 11)
* Integration testing (Phase 12)
* Production deployment (Phase 13)
* Monitoring & analytics (Phase 14)
See [Implementation Roadmap](https://github.com/NeuroChainAi/docs-guides/blob/main/IMPLEMENTATION_ROADMAP.md).
### Will there be official SDKs?
Planned SDKs:
* Python (in progress)
* JavaScript/TypeScript
* Go
### Will NCN support other blockchains?
Currently focused on Ethereum/Arbitrum. Future chains may include:
* Other EVM chains
* Solana
* Near
***
## Still Have Questions?
* Check the [Documentation Index](/nc/neurochainai-guides)
* Search [GitHub Issues](https://github.com/neurochainai/ncn-network-v2-rs/issues)
* Join the community (Discord/Telegram)
* Open a new GitHub issue
# Contributing Guide
Thank you for your interest in contributing to NCN Network v2! This guide will help you get started.
***
## Ways to Contribute
### Code Contributions
* Bug fixes
* New features
* Performance improvements
* Documentation updates
### Non-Code Contributions
* Bug reports
* Feature requests
* Documentation improvements
* Community support
***
## Getting Started
### 1. Fork the Repository
```bash
# Fork on GitHub, then clone your fork
git clone https://github.com/neurochainai/ncn-network-v2-rs.git
cd ncn-network-v2-rs
```
### 2. Set Up Development Environment
```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install additional tools
rustup component add clippy rustfmt
# Build project
cargo build
# Run tests
cargo test --all
```
### 3. Create a Branch
```bash
git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix
```
### 4. Make Changes
Follow the [Code Style Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/code-style.md).
### 5. Submit Pull Request
See [Pull Request Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/pull-requests.md).
***
## Contributing Guides
### [Code Style](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/code-style.md)
Coding standards and conventions:
* Rust style guide
* Formatting with `cargo fmt`
* Linting with `cargo clippy`
* Documentation standards
### [Pull Requests](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/pull-requests.md)
PR process and guidelines:
* Branch naming conventions
* Commit message format
* PR template
* Review process
### [Documentation](https://github.com/NeuroChainAi/docs-guides/blob/main/contributing/documentation.md)
Documentation contribution guide:
* Writing style
* Markdown conventions
* Adding new documents
***
## Development Workflow
```
1. Fork & Clone
│
▼
2. Create Branch
│
▼
3. Make Changes ←───┐
│ │
▼ │
4. Run Tests │
│ │
▼ │
5. Fix Issues ──────┘
│
▼
6. Commit
│
▼
7. Push to Fork
│
▼
8. Create PR
│
▼
9. Address Review Comments
│
▼
10. Merge! 🎉
```
***
## Code of Conduct
### Our Standards
* Be respectful and inclusive
* Welcome newcomers
* Provide constructive feedback
* Focus on the best outcome for the project
### Unacceptable Behavior
* Harassment or discrimination
* Personal attacks
* Trolling or insulting comments
* Publishing private information
***
## Issue Guidelines
### Bug Reports
Include:
1. **Description**: What happened?
2. **Expected**: What should have happened?
3. **Steps to reproduce**: How can we reproduce it?
4. **Environment**: OS, versions, configuration
5. **Logs**: Relevant error messages
### Feature Requests
Include:
1. **Problem**: What problem does this solve?
2. **Solution**: What's your proposed solution?
3. **Alternatives**: What alternatives did you consider?
4. **Impact**: Who benefits from this?
***
## Quick Commands
```bash
# Build
cargo build
# Test
cargo test --all
# Format code
cargo fmt
# Lint code
cargo clippy
# Build docs
cargo doc --open
# Run specific component
cargo run --bin gateway_node
```
***
## Questions?
* Check existing issues and documentation
* Ask in community channels
* Open a discussion on GitHub
We appreciate all contributions! 🙏
# Changelog
This section tracks changes and releases for NCN Network v2.
***
## Versioning
NCN Network follows [Semantic Versioning](https://semver.org/):
* **MAJOR**: Breaking changes
* **MINOR**: New features, backward compatible
* **PATCH**: Bug fixes, backward compatible
***
## Current Version
**v2.0.0** (Pre-release)
Status: 85% Complete - Beta Testing Recommended
***
## Release Notes
### [Releases](https://github.com/NeuroChainAi/docs-guides/blob/main/changelog/releases.md)
Complete release history with:
* Version numbers
* Release dates
* New features
* Bug fixes
* Breaking changes
* Migration guides
***
## Recent Changes
### Phase 10 (Current)
* Gateway CLI for subnet management
* Complete payment flow integration
* State persistence
* Response finalization
### Phase 9
* Validator consensus mechanism
* M-of-N signature scheme
* Preprocessing validation
* Completion validation
### Phase 8
* Sandboxed model execution
* seccomp filtering
* Namespace isolation
* Landlock filesystem rules
### Phase 7
* Compute node signing
* Result attestation
* Payment validation
### Phase 6
* Test client with payment flow
* Blockchain integration
* Transaction monitoring
### Phase 1-5
* Smart contract development
* Protocol buffer definitions
* P2P Registry implementation
* Gateway node implementation
* Compute node implementation
***
## Upcoming
### Phase 11 (Next)
* Model auto-downloader for compute nodes
* Automatic model synchronization
### Phase 12
* Integration testing
* End-to-end test suite
### Phase 13
* Production deployment
* Performance optimization
### Phase 14
* Monitoring & analytics
* Dashboard implementation
***
## Deprecations
No deprecations in current version.
***
## Breaking Changes
### v0.1.0
Initial release - no breaking changes from previous versions.
***
## Migration Guides
Migration guides will be provided for any breaking changes in future releases.