rwadurian/backend/mpc-system/api/proto/message_router.proto

syntax = "proto3";

package mpc.router.v1;

option go_package = "github.com/rwadurian/mpc-system/api/grpc/router/v1;router";

// MessageRouter service handles MPC message routing
service MessageRouter {
  // RouteMessage routes a message from one party to others
  rpc RouteMessage(RouteMessageRequest) returns (RouteMessageResponse);

  // SubscribeMessages subscribes to messages for a party (streaming)
  rpc SubscribeMessages(SubscribeMessagesRequest) returns (stream MPCMessage);

  // GetPendingMessages retrieves pending messages (polling alternative)
  rpc GetPendingMessages(GetPendingMessagesRequest) returns (GetPendingMessagesResponse);

  // AcknowledgeMessage acknowledges receipt of a message
  // Must be called after processing a message to confirm delivery
  rpc AcknowledgeMessage(AcknowledgeMessageRequest) returns (AcknowledgeMessageResponse);

  // GetMessageStatus gets the delivery status of a message
  rpc GetMessageStatus(GetMessageStatusRequest) returns (GetMessageStatusResponse);

  // RegisterParty registers a party with the message router (party actively connects)
  rpc RegisterParty(RegisterPartyRequest) returns (RegisterPartyResponse);

  // Heartbeat sends a heartbeat to keep the party alive
  rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse);

  // SubscribeSessionEvents subscribes to session lifecycle events (session start, etc.)
  rpc SubscribeSessionEvents(SubscribeSessionEventsRequest) returns (stream SessionEvent);

  // PublishSessionEvent publishes a session event (called by Session Coordinator)
  rpc PublishSessionEvent(PublishSessionEventRequest) returns (PublishSessionEventResponse);

  // GetRegisteredParties returns all registered parties (for Session Coordinator party discovery)
  rpc GetRegisteredParties(GetRegisteredPartiesRequest) returns (GetRegisteredPartiesResponse);
}

// RouteMessageRequest routes an MPC message
message RouteMessageRequest {
  string session_id = 1;
  string from_party = 2;
  repeated string to_parties = 3;        // Empty for broadcast
  int32 round_number = 4;
  string message_type = 5;
  bytes payload = 6;                     // Encrypted MPC message
}

// RouteMessageResponse confirms message routing
message RouteMessageResponse {
  bool success = 1;
  string message_id = 2;
}

// SubscribeMessagesRequest subscribes to messages for a party
message SubscribeMessagesRequest {
  string session_id = 1;
  string party_id = 2;
}

// MPCMessage represents an MPC protocol message
message MPCMessage {
  string message_id = 1;
  string session_id = 2;
  string from_party = 3;
  bool is_broadcast = 4;
  int32 round_number = 5;
  string message_type = 6;
  bytes payload = 7;
  int64 created_at = 8;                  // Unix timestamp milliseconds
}

// GetPendingMessagesRequest retrieves pending messages
message GetPendingMessagesRequest {
  string session_id = 1;
  string party_id = 2;
  int64 after_timestamp = 3;             // Get messages after this timestamp
}

// GetPendingMessagesResponse contains pending messages
message GetPendingMessagesResponse {
  repeated MPCMessage messages = 1;
}

// NotificationChannel represents a notification channel for offline parties
// If a party has notification channels, it operates in offline mode (24h async)
// If no notification channels, it operates in real-time mode (Message Router push)
message NotificationChannel {
  string email = 1;                          // Optional: email address for notifications
  string phone = 2;                          // Optional: phone number for SMS notifications
  string push_token = 3;                     // Optional: push notification token (FCM/APNs)
}

// RegisterPartyRequest registers a party with the router
message RegisterPartyRequest {
  string party_id = 1;                       // Unique party identifier
  string party_role = 2;                     // persistent, delegate, or temporary
  string version = 3;                        // Party software version
  NotificationChannel notification = 4;     // Optional: notification channel for offline mode
}

// RegisterPartyResponse confirms party registration
message RegisterPartyResponse {
  bool success = 1;
  string message = 2;
  int64 registered_at = 3;                   // Unix timestamp milliseconds
}

// SubscribeSessionEventsRequest subscribes to session events
message SubscribeSessionEventsRequest {
  string party_id = 1;                       // Party ID subscribing to events
  repeated string event_types = 2;           // Event types to subscribe (empty = all)
}

// SessionEvent represents a session lifecycle event
message SessionEvent {
  string event_id = 1;
  string event_type = 2;                     // session_created, session_started, etc.
  string session_id = 3;
  int32 threshold_n = 4;
  int32 threshold_t = 5;
  repeated string selected_parties = 6;       // PartyIDs selected for this session
  map<string, string> join_tokens = 7;        // PartyID -> JoinToken mapping
  bytes message_hash = 8;                     // For sign sessions
  int64 created_at = 9;                       // Unix timestamp milliseconds
  int64 expires_at = 10;                      // Unix timestamp milliseconds
}

// PublishSessionEventRequest publishes a session event
message PublishSessionEventRequest {
  SessionEvent event = 1;
}

// PublishSessionEventResponse confirms event publication
message PublishSessionEventResponse {
  bool success = 1;
  int32 subscriber_count = 2;                // Number of parties that received the event
}

// GetRegisteredPartiesRequest requests registered parties list
message GetRegisteredPartiesRequest {
  string role_filter = 1;                    // Optional: filter by role (persistent, delegate, temporary)
  bool only_online = 2;                      // Optional: only return online parties
}

// RegisteredParty represents a registered party
message RegisteredParty {
  string party_id = 1;                       // Unique party identifier
  string role = 2;                           // persistent, delegate, or temporary
  bool online = 3;                           // Whether party is currently connected
  int64 registered_at = 4;                   // Unix timestamp milliseconds
  int64 last_seen_at = 5;                    // Unix timestamp milliseconds
  NotificationChannel notification = 6;     // Optional: notification channel (if set, party is offline mode)
}

// GetRegisteredPartiesResponse returns registered parties
message GetRegisteredPartiesResponse {
  repeated RegisteredParty parties = 1;
  int32 total_count = 2;
}

// AcknowledgeMessageRequest acknowledges message receipt
message AcknowledgeMessageRequest {
  string message_id = 1;                     // ID of the message being acknowledged
  string party_id = 2;                       // ID of the party acknowledging
  string session_id = 3;                     // Session the message belongs to
  bool success = 4;                          // True if message was processed successfully
  string error_message = 5;                  // Error message if processing failed
}

// AcknowledgeMessageResponse confirms acknowledgment
message AcknowledgeMessageResponse {
  bool success = 1;
  string message = 2;
}

// GetMessageStatusRequest requests message delivery status
message GetMessageStatusRequest {
  string message_id = 1;
  string session_id = 2;
}

// MessageDeliveryStatus represents delivery status to a single party
message MessageDeliveryStatus {
  string party_id = 1;
  string status = 2;                         // pending, delivered, acknowledged, failed
  int64 delivered_at = 3;                    // Unix timestamp milliseconds
  int64 acknowledged_at = 4;                 // Unix timestamp milliseconds
  int32 retry_count = 5;                     // Number of delivery retries
}

// GetMessageStatusResponse returns message delivery status
message GetMessageStatusResponse {
  string message_id = 1;
  string session_id = 2;
  repeated MessageDeliveryStatus deliveries = 3;
  bool all_acknowledged = 4;                 // True if all recipients acknowledged
}

// HeartbeatRequest sends a heartbeat to keep the party alive
message HeartbeatRequest {
  string party_id = 1;
  int64 timestamp = 2;                       // Unix timestamp milliseconds
}

// HeartbeatResponse confirms heartbeat receipt
message HeartbeatResponse {
  bool success = 1;
  int64 server_timestamp = 2;                // Server timestamp for clock sync
  int32 pending_messages = 3;                // Number of pending messages for this party
}