# 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](https://docs.neurochain.ai/nc/neurochainai-guides/architecture/system-overview) - Detailed architecture
* [Payment Flow](https://docs.neurochain.ai/nc/neurochainai-guides/architecture/payment-flow) - Payment deep dive
* [Getting Started](https://docs.neurochain.ai/nc/neurochainai-guides/introduction/getting-started) - Run your first request