use std::collections::{BTreeMap, HashMap};
use serde::{Deserialize, Serialize};
use crate::mesh::noise::{blake3_digest, SovereignNodeIdentity};
pub const PKC_SERVICE_PREFIX: &str = "service.pkc.";
pub const PKC_SERVICE_MDNS_TYPE: &str = "_pkc-service._tcp.local.";
pub const PKC_CAPABILITY_MIME_TYPE: &str = "application/x-clm-capability+json";
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PropertySchema {
#[serde(rename = "type")]
pub prop_type: String,
#[serde(default)]
pub required: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SchemaSpec {
#[serde(rename = "type")]
pub schema_type: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub properties: Option<BTreeMap<String, PropertySchema>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub required: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub polynomial_order: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SlaWitness {
#[serde(skip_serializing_if = "Option::is_none")]
pub context_window: Option<u32>,
pub compute_type: String,
pub p95_latency_ms: u32,
#[serde(skip_serializing_if = "Option::is_none")]
pub throughput_tps: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub reliability_score: Option<f64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PricingSpec {
pub base_cost: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub cost_per_token: Option<f64>,
pub currency: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ServiceEndpoint {
pub protocol: String,
pub address: String,
pub port: u16,
#[serde(skip_serializing_if = "Option::is_none")]
pub noise_pubkey_hex: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ServiceCapabilityManifest {
pub service_id: String,
pub version: String,
pub provider_did: String,
pub description: String,
pub input_schema: SchemaSpec,
pub output_schema: SchemaSpec,
pub sla: SlaWitness,
pub pricing: PricingSpec,
pub endpoints: Vec<ServiceEndpoint>,
pub registered_at: u64,
pub ttl_seconds: u64,
pub content_hash: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub signature: Option<String>,
}
pub fn is_valid_service_id(service_id: &str) -> bool {
if !service_id.starts_with(PKC_SERVICE_PREFIX) {
return false;
}
let parts: Vec<&str> = service_id[PKC_SERVICE_PREFIX.len()..].split('.').collect();
parts.len() >= 2 && parts.iter().all(|p| !p.is_empty() && p.chars().all(|c| c.is_alphanumeric() || c == '_' || c == '-'))
}
#[derive(Serialize)]
struct CanonicalManifest<'a> {
description: &'a str,
endpoints: &'a [ServiceEndpoint],
input_schema: &'a SchemaSpec,
output_schema: &'a SchemaSpec,
pricing: &'a PricingSpec,
provider_did: &'a str,
registered_at: u64,
service_id: &'a str,
sla: &'a SlaWitness,
ttl_seconds: u64,
version: &'a str,
}
pub fn canonicalize_manifest(manifest: &ServiceCapabilityManifest) -> String {
let canonical = CanonicalManifest {
description: &manifest.description,
endpoints: &manifest.endpoints,
input_schema: &manifest.input_schema,
output_schema: &manifest.output_schema,
pricing: &manifest.pricing,
provider_did: &manifest.provider_did,
registered_at: manifest.registered_at,
service_id: &manifest.service_id,
sla: &manifest.sla,
ttl_seconds: manifest.ttl_seconds,
version: &manifest.version,
};
serde_json::to_string(&canonical).unwrap_or_default()
}
pub fn compute_manifest_hash(manifest: &ServiceCapabilityManifest) -> String {
let canonical = canonicalize_manifest(manifest);
let digest = blake3_digest(canonical.as_bytes());
hex::encode(digest)
}
pub fn sign_capability_manifest(
mut manifest: ServiceCapabilityManifest,
identity: &SovereignNodeIdentity,
) -> Result<ServiceCapabilityManifest, String> {
if !is_valid_service_id(&manifest.service_id) {
return Err(format!("Invalid service identifier '{}'", manifest.service_id));
}
manifest.provider_did = identity.did.clone();
let content_hash = compute_manifest_hash(&manifest);
let hash_bytes = hex::decode(&content_hash).map_err(|e| e.to_string())?;
let sig_bytes = identity.sign(&hash_bytes);
let signature = bs58::encode(sig_bytes).into_string();
manifest.content_hash = content_hash;
manifest.signature = Some(signature);
Ok(manifest)
}
pub fn verify_capability_manifest(manifest: &ServiceCapabilityManifest) -> bool {
if !is_valid_service_id(&manifest.service_id) {
return false;
}
let expected_hash = compute_manifest_hash(manifest);
if expected_hash != manifest.content_hash {
return false;
}
if let Some(ref sig_b58) = manifest.signature {
let pubkey_bytes = match SovereignNodeIdentity::did_to_public_key(&manifest.provider_did) {
Ok(pk) => pk,
Err(_) => return false,
};
let hash_bytes = match hex::decode(&manifest.content_hash) {
Ok(hb) => hb,
Err(_) => return false,
};
let sig_vec = match bs58::decode(sig_b58).into_vec() {
Ok(v) => v,
Err(_) => return false,
};
if sig_vec.len() != 64 {
return false;
}
let mut sig_arr = [0u8; 64];
sig_arr.copy_from_slice(&sig_vec);
return SovereignNodeIdentity::verify_signature(&pubkey_bytes, &hash_bytes, &sig_arr);
}
true
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RouteTier {
Local,
Lan,
Overlay,
}
#[derive(Debug, Clone)]
pub struct RoutingCandidate {
pub manifest: ServiceCapabilityManifest,
pub tier: RouteTier,
pub composite_score: f64,
pub effective_latency_ms: u32,
pub reliability: f64,
pub cost: f64,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoutingTraceHop {
pub node_did: String,
pub timestamp: u64,
pub hop_hash: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoutingTraceVector {
pub trace_id: String,
pub origin_did: String,
pub hops: Vec<RoutingTraceHop>,
}
pub fn create_trace_vector(origin_did: &str, trace_id: Option<String>) -> RoutingTraceVector {
let id = trace_id.unwrap_or_else(|| format!("trace_{}", uuid::Uuid::new_v4()));
let initial_data = format!("{}:{}", id, origin_did);
let initial_hash = hex::encode(blake3_digest(initial_data.as_bytes()));
RoutingTraceVector {
trace_id: id,
origin_did: origin_did.to_string(),
hops: vec![RoutingTraceHop {
node_did: origin_did.to_string(),
timestamp: 0,
hop_hash: initial_hash,
}],
}
}
pub fn append_trace_hop(vector: &mut RoutingTraceVector, node_did: &str, timestamp: u64) {
let prev_hash = vector.hops.last().map(|h| h.hop_hash.as_str()).unwrap_or("0");
let hop_data = format!("{}:{}:{}", node_did, prev_hash, timestamp);
let hop_hash = hex::encode(blake3_digest(hop_data.as_bytes()));
vector.hops.push(RoutingTraceHop {
node_did: node_did.to_string(),
timestamp,
hop_hash,
});
}
pub fn detect_routing_loop(vector: &RoutingTraceVector, target_node_did: &str) -> bool {
vector.hops.iter().any(|h| h.node_did == target_node_did)
}
#[derive(Debug, Clone)]
pub struct ServiceTelemetry {
pub last_seen: u64,
pub latency_ms: u32,
pub success_count: u32,
pub error_count: u32,
pub reliability: f64,
}
pub struct ServiceCatalog {
pub node_did: String,
local_services: HashMap<String, ServiceCapabilityManifest>,
remote_services: HashMap<String, HashMap<String, ServiceCapabilityManifest>>,
telemetry: HashMap<String, ServiceTelemetry>,
}
impl ServiceCatalog {
pub fn new(node_did: &str) -> Self {
Self {
node_did: node_did.to_string(),
local_services: HashMap::new(),
remote_services: HashMap::new(),
telemetry: HashMap::new(),
}
}
pub fn register_local_service(&mut self, manifest: ServiceCapabilityManifest) -> Result<(), String> {
if !verify_capability_manifest(&manifest) {
return Err(format!("Manifest for '{}' failed verification", manifest.service_id));
}
self.local_services.insert(manifest.service_id.clone(), manifest);
Ok(())
}
pub fn register_remote_service(&mut self, manifest: ServiceCapabilityManifest) -> bool {
if !verify_capability_manifest(&manifest) {
return false;
}
let service_id = manifest.service_id.clone();
let provider_did = manifest.provider_did.clone();
self.telemetry.entry(provider_did.clone()).or_insert_with(|| ServiceTelemetry {
last_seen: manifest.registered_at,
latency_ms: manifest.sla.p95_latency_ms,
success_count: 1,
error_count: 0,
reliability: manifest.sla.reliability_score.unwrap_or(1.0),
});
self.remote_services
.entry(service_id)
.or_default()
.insert(provider_did, manifest);
true
}
pub fn find_providers(&self, service_id: &str) -> Vec<ServiceCapabilityManifest> {
let mut results = Vec::new();
if let Some(local) = self.local_services.get(service_id) {
results.push(local.clone());
}
if let Some(remotes) = self.remote_services.get(service_id) {
for manifest in remotes.values() {
results.push(manifest.clone());
}
}
results
}
pub fn update_telemetry(&mut self, provider_did: &str, observed_latency_ms: u32, success: bool) {
let cur = self.telemetry.entry(provider_did.to_string()).or_insert_with(|| ServiceTelemetry {
last_seen: 0,
latency_ms: observed_latency_ms,
success_count: 0,
error_count: 0,
reliability: 1.0,
});
if success {
cur.success_count += 1;
} else {
cur.error_count += 1;
}
let total = cur.success_count + cur.error_count;
cur.reliability = if total > 0 { cur.success_count as f64 / total as f64 } else { 1.0 };
cur.latency_ms = ((cur.latency_ms as f64 * 0.7) + (observed_latency_ms as f64 * 0.3)) as u32;
}
pub fn get_telemetry(&self, provider_did: &str) -> Option<&ServiceTelemetry> {
self.telemetry.get(provider_did)
}
pub fn sweep_expired(&mut self, now: u64) -> Vec<String> {
let mut evicted = Vec::new();
for (service_id, providers) in self.remote_services.iter_mut() {
providers.retain(|did, manifest| {
let last_active = manifest.registered_at;
let ttl_ms = manifest.ttl_seconds * 1000;
if now.saturating_sub(last_active) > ttl_ms {
evicted.push(format!("{}@{}", service_id, did));
false
} else {
true
}
});
}
self.remote_services.retain(|_, providers| !providers.is_empty());
evicted
}
}
pub struct ServiceRouter<'a> {
pub catalog: &'a ServiceCatalog,
pub this_node_did: String,
pub weight_latency: f64,
pub weight_cost: f64,
pub weight_reliability: f64,
}
impl<'a> ServiceRouter<'a> {
pub fn new(catalog: &'a ServiceCatalog) -> Self {
Self {
catalog,
this_node_did: catalog.node_did.clone(),
weight_latency: 0.5,
weight_cost: 0.3,
weight_reliability: 0.2,
}
}
pub fn classify_tier(&self, manifest: &ServiceCapabilityManifest) -> RouteTier {
if manifest.provider_did == self.this_node_did {
return RouteTier::Local;
}
if let Some(ep) = manifest.endpoints.first() {
let addr = ep.address.to_lowercase();
if addr == "127.0.0.1" || addr == "localhost" || addr.ends_with(".local") || addr.starts_with("192.168.") || addr.starts_with("10.") {
return RouteTier::Lan;
}
}
RouteTier::Overlay
}
pub fn rank_candidates(&self, service_id: &str, trace: Option<&RoutingTraceVector>) -> Vec<RoutingCandidate> {
let manifests = self.catalog.find_providers(service_id);
let mut candidates = Vec::new();
for manifest in manifests {
if let Some(tr) = trace
&& detect_routing_loop(tr, &manifest.provider_did) {
continue;
}
let tier = self.classify_tier(&manifest);
let tele = self.catalog.get_telemetry(&manifest.provider_did);
let effective_latency = tele.map(|t| t.latency_ms).unwrap_or(manifest.sla.p95_latency_ms);
let reliability = tele.map(|t| t.reliability).unwrap_or(manifest.sla.reliability_score.unwrap_or(1.0));
let cost = manifest.pricing.base_cost;
let tier_multiplier = match tier {
RouteTier::Local => 0.4,
RouteTier::Lan => 1.0,
RouteTier::Overlay => 1.6,
};
let normalized_lat = effective_latency as f64 / 100.0;
let score = tier_multiplier * (self.weight_latency * normalized_lat + self.weight_cost * cost)
- self.weight_reliability * (reliability * 10.0);
candidates.push(RoutingCandidate {
manifest,
tier,
composite_score: score,
effective_latency_ms: effective_latency,
reliability,
cost,
});
}
candidates.sort_by(|a, b| a.composite_score.partial_cmp(&b.composite_score).unwrap_or(std::cmp::Ordering::Equal));
candidates
}
pub fn select_best_route(&self, service_id: &str, trace: Option<&RoutingTraceVector>) -> Option<RoutingCandidate> {
self.rank_candidates(service_id, trace).into_iter().next()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn dummy_manifest(service_id: &str, did: &str, cost: f64, latency: u32) -> ServiceCapabilityManifest {
ServiceCapabilityManifest {
service_id: service_id.to_string(),
version: "1.0.0".to_string(),
provider_did: did.to_string(),
description: "Dummy capability".to_string(),
input_schema: SchemaSpec {
schema_type: "object".to_string(),
properties: None,
required: None,
polynomial_order: None,
description: None,
},
output_schema: SchemaSpec {
schema_type: "object".to_string(),
properties: None,
required: None,
polynomial_order: None,
description: None,
},
sla: SlaWitness {
context_window: Some(4096),
compute_type: "cpu-generic".to_string(),
p95_latency_ms: latency,
throughput_tps: Some(50),
reliability_score: Some(0.99),
},
pricing: PricingSpec {
base_cost: cost,
cost_per_token: None,
currency: "PKC_TOKEN".to_string(),
},
endpoints: vec![ServiceEndpoint {
protocol: "noise_xx".to_string(),
address: "192.168.1.50".to_string(),
port: 9095,
noise_pubkey_hex: None,
}],
registered_at: 1000,
ttl_seconds: 60,
content_hash: String::new(),
signature: None,
}
}
#[test]
fn test_valid_service_id() {
assert!(is_valid_service_id("service.pkc.llm.inference"));
assert!(is_valid_service_id("service.pkc.tikz.compiler"));
assert!(!is_valid_service_id("service.ollama.inference"));
assert!(!is_valid_service_id("service.pkc."));
assert!(!is_valid_service_id("service.pkc.llm"));
}
#[test]
fn test_manifest_signing_and_verification() {
let identity = SovereignNodeIdentity::generate();
let mut manifest = dummy_manifest("service.pkc.proof.checker", &identity.did, 0.001, 35);
manifest = sign_capability_manifest(manifest, &identity).expect("sign manifest");
assert_eq!(manifest.content_hash.len(), 64);
assert!(manifest.signature.is_some());
assert!(verify_capability_manifest(&manifest));
let mut tampered = manifest.clone();
tampered.pricing.base_cost = 99.0;
assert!(!verify_capability_manifest(&tampered));
}
#[test]
fn test_router_candidate_ranking_and_loop_detection() {
let alice = SovereignNodeIdentity::generate();
let bob = SovereignNodeIdentity::generate();
let mut catalog = ServiceCatalog::new(&alice.did);
let mut m_local = dummy_manifest("service.pkc.llm.inference", &alice.did, 0.01, 20);
m_local = sign_capability_manifest(m_local, &alice).unwrap();
catalog.register_local_service(m_local).unwrap();
let mut m_remote = dummy_manifest("service.pkc.llm.inference", &bob.did, 0.001, 60);
m_remote.endpoints[0].address = "203.0.113.1".to_string(); m_remote = sign_capability_manifest(m_remote, &bob).unwrap();
catalog.register_remote_service(m_remote);
let router = ServiceRouter::new(&catalog);
let ranked = router.rank_candidates("service.pkc.llm.inference", None);
assert_eq!(ranked.len(), 2);
assert_eq!(ranked[0].tier, RouteTier::Local);
assert_eq!(ranked[1].tier, RouteTier::Overlay);
let mut trace = create_trace_vector(&alice.did, None);
append_trace_hop(&mut trace, &bob.did, 100);
assert!(detect_routing_loop(&trace, &bob.did));
}
}