> 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/components/common-types.md).

# 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<PreprocessingValidation>,
    pub transaction_confirmation: Option<TransactionConfirmation>,
    pub assigned_timestamp: Option<i64>,
    pub assigned_compute_node_id: Option<String>,
}

// 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<ComputeCompletion>,
    pub completion_validation: Option<CompletionValidation>,
}
```

### 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<String>,
    pub wallet_address: String,
    pub last_heartbeat: i64,
    pub supported_models: Vec<ModelData>,
    pub subnet_id: Option<u64>,
}

// 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.md) - 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.md) - Payment architecture