API Reference¶

Overview¶

CP'S Enterprise DCS uses gRPC with Protocol Buffers for all inter-service communication. The service definitions are in cps-enterprise-dcs/proto/cps_enterprise_v4.proto.

gRPC Services¶

AccountingSwarmProtocol¶

The primary service for financial event management, reconciliation, and agent coordination.

Port: 50051 (Local Agent), 50052 (Regional Agent)

Unary RPCs¶

Server Streaming RPCs¶

Client Streaming RPCs¶

Bidirectional Streaming RPCs¶

QueryProtocol¶

Read-model query service for dashboards and reporting.

Unary RPCs¶

Server Streaming RPCs¶

Core Messages¶

SovereignFinancialEvent¶

The central event type in the system. Every financial transaction is captured as an immutable event.

message SovereignFinancialEvent {
  string event_id = 1;           // UUID v7 (time-ordered)
  string correlation_id = 2;     // Saga event linkage
  string idempotency_key = 3;    // Deterministic SHA-256
  uint32 stream_version = 4;     // Optimistic concurrency control
  string event_hash = 5;         // SHA-256 of event content

  string branch_id = 6;
  string agent_id = 7;
  string saga_id = 8;
  string tenant_id = 9;

  EventType type = 10;
  double amount = 11;
  string currency = 12;
  SovereignPayload payload = 13;
  bytes public_metadata = 14;

  CausalContext causal_context = 15;
  google.protobuf.Timestamp ts = 16;
  int64 received_at = 17;

  string created_by = 18;
  string approved_by = 19;
  bytes digital_signature = 20;
}

SovereignPayload¶

Envelope-encrypted payload attached to each event.

message SovereignPayload {
  bytes encrypted_data = 1;          // AES-256-GCM ciphertext
  bytes encrypted_dek = 2;          // DEK encrypted by KEK via Vault
  string kms_key_id = 3;           // KEK identifier in HashiCorp Vault
  bytes iv = 4;                    // 12-byte IV, unique per event
  bytes auth_tag = 5;             // GCM authentication tag (16 bytes)
  string hmac_signature = 6;      // HMAC-SHA512 on visible metadata
  uint32 schema_version = 7;
  bytes encrypted_inner_layer = 8; // Additional encryption for sensitive data
  string inner_key_derivation = 9; // HKDF identifier for inner layer
  bytes compliance_proof = 10;     // Zero-knowledge proof for compliance
  bytes audit_trail_hash = 11;    // Hash chain for tamper detection
}

CausalContext¶

Tracks causality and ordering across distributed nodes.

message CausalContext {
  HybridLogicalClock hlc = 1;
  VectorClock v_clock = 2;
  repeated string parent_event_ids = 3;
  int64 lamport_timestamp = 4;
}

message HybridLogicalClock {
  int64 physical_ms = 1;    // Physical time in milliseconds
  int32 logical = 2;        // Logical counter for concurrent events
  string node_id = 3;       // Node identifier
  int32 counter = 4;        // Monotonic counter per node
}

Event Types¶

Events are organized into domain-specific flows:

Sales Flow¶

Inventory Flow¶

Payment Flow¶

Accounting Flow¶

Saga Flow¶

Agent Flow¶

CRDT Messages¶

GCounter (Grow-Only Counter)¶

message GCounter {
  string node_id = 1;
  map<string, uint64> increments = 2;
}

PNCounter (Positive-Negative Counter)¶

message PNCounter {
  string node_id = 1;
  map<string, uint64> increments = 2;
  map<string, uint64> decrements = 3;
}

ORSet (Observed-Remove Set)¶

message ORSet {
  string node_id = 1;
  repeated ORSetElement elements = 2;
}

LWWRegister (Last-Write-Wins Register)¶

message LWWRegister {
  string value = 1;
  HybridLogicalClock timestamp = 2;
  string node_id = 3;
}

CRDTStateBundle (Sync Envelope)¶

message CRDTStateBundle {
  string branch_id = 1;
  string crdt_type = 2;        // "GCounter", "PNCounter", "ORSet", "LWWRegister"
  string crdt_id = 3;
  bytes serialized_state = 4;
  HybridLogicalClock last_updated = 5;
  uint64 version = 6;
}

Saga Orchestration¶

Saga Types¶

Saga States¶

PENDING → RUNNING → COMPLETED
                  ↘ COMPENSATING → COMPENSATED
                  ↘ FAILED
                  ↘ TIMED_OUT

Conflict Resolution Strategies¶

Agent Types¶