> For the complete documentation index, see [llms.txt](https://docs.neurochain.ai/nc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neurochain.ai/nc/neurochainai-guides/api-reference/protobuf.md).

# 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