syntax = "proto3";
package kairos.v1;

import "kairos/v1/common.proto";

option go_package = "github.com/kairos/proto/kairos/v1";

// One unordered cross-provider pairing accepted by an arb subscription.
message ArbProviderPair {
  Provider a_provider = 1;
  Provider b_provider = 2;
}

// Server-side filters applied before arb batches are delivered to a client.
message ArbSubscriptionFilter {
  // Explicit empty list matches no pairs. Clients that want all supported
  // pairs send all three combinations; legacy subscriptions receive defaults.
  repeated ArbProviderPair provider_pairs = 1;
  int32 min_spread_bps = 2;
  int32 min_similarity_scaled = 3;
  // Minimum executable notional in dollars, scaled by 10000. Zero disables
  // the liquidity filter. A nonzero minimum excludes opportunities whose
  // executable liquidity is unknown or zero.
  int64 min_arb_liquidity_scaled = 4;
}

// Identified arb subscription. Sending SubscribeRequest again with the same
// subscription_id replaces its filters (update); FetchRequest reads it and
// UnsubscribeRequest deletes it.
message ArbSubscription {
  string subscription_id = 1;
  ArbSubscriptionFilter filter = 2;
}

// SubscribeRequest is sent by the client to subscribe to market data
// Wire format: [TYPE_TAG_SUBSCRIBE: 0x10] [protobuf payload]
message SubscribeRequest {
  string contract_id = 1;
  string provider = 2;
  // Optional: filter which message types to receive (empty = all)
  // Valid values: "price", "volume", "trades", "candles", "orderbook", "ticks"
  repeated string topics = 3;
  // Optional: filter which candle timeframes to receive (in seconds, e.g., 60, 300, 3600)
  repeated uint32 candle_timeframes = 4;
  // Present only for topics:["arb"]. Creates or updates the identified
  // server-side arb subscription.
  ArbSubscription arb_subscription = 5;
}

// UnsubscribeRequest is sent by the client to unsubscribe from market data
// Wire format: [TYPE_TAG_UNSUBSCRIBE: 0x11] [protobuf payload]
message UnsubscribeRequest {
  string contract_id = 1;
  string provider = 2;
  // Deletes this identified arb subscription when non-empty.
  string arb_subscription_id = 3;
}

// PingRequest is sent by the client to measure latency
// Wire format: [TYPE_TAG_PING: 0x12] [protobuf payload]
message PingRequest {
  // Client timestamp in milliseconds for round-trip latency calculation
  int64 timestamp_ms = 1;
}

// PongResponse is sent by the server in response to a ping
// Wire format: [TYPE_TAG_PONG: 0x13] [protobuf payload]
message PongResponse {
  // Echo of client's timestamp for latency calculation
  int64 timestamp_ms = 1;
}

// SubscribedResponse is sent by the server to acknowledge a subscription
// Wire format: [TYPE_TAG_SUBSCRIBED: 0x14] [protobuf payload]
message SubscribedResponse {
  // Normalized contract ID (e.g., stripped :yes/:no suffix)
  string contract_id = 1;
  // Effective server-side state after an arb create, update, or read.
  ArbSubscription arb_subscription = 2;
}

// UnsubscribedResponse is sent by the server to acknowledge an unsubscription
// Wire format: [TYPE_TAG_UNSUBSCRIBED: 0x15] [protobuf payload]
message UnsubscribedResponse {
  // Normalized contract ID
  string contract_id = 1;
  string arb_subscription_id = 2;
}

// FetchRequest is sent by the client to request an immediate data fetch
// Wire format: [TYPE_TAG_FETCH: 0x16] [protobuf payload]
message FetchRequest {
  string contract_id = 1;
  string provider = 2;
  // Reads this arb subscription and returns SubscribedResponse plus filtered
  // cached match/spread batches. Empty keeps the legacy market fetch behavior.
  string arb_subscription_id = 3;
}

// ErrorResponse is sent by the server when an error occurs
// Wire format: [TYPE_TAG_ERROR: 0x17] [protobuf payload]
message ErrorResponse {
  string message = 1;
  // Optional: the action that caused the error
  string action = 2;
}

// ServerPingRequest is sent by the server to check if the client is alive
// Wire format: [TYPE_TAG_SERVER_PING: 0x18] [protobuf payload]
message ServerPingRequest {
  // Server timestamp for logging/debugging
  int64 timestamp_ms = 1;
}

// ClientPongResponse is sent by the client in response to a server ping
// Wire format: [TYPE_TAG_CLIENT_PONG: 0x19] [protobuf payload]
message ClientPongResponse {
  // Echo of server's timestamp
  int64 timestamp_ms = 1;
}

// Unsolicited server notice: this market resolved; the server has stopped
// its data feeds and will reject re-subscribes. Clients should drop local
// subscription state. Wire tag 0x1D.
//
// Tag placement: the control range originally reserved 0x10-0x19, but the
// data-message range spilled past its own 0x0F cap into 0x1A-0x1C (Quote /
// TxOdds / TickSizeChange). 0x1D is therefore the next free byte across BOTH
// tables — see message_router.h.
message MarketResolvedNotice {
  // Contract id in the SAME namespace the client subscribed with. For
  // Polymarket-family (CTF) venues the streaming layer keys on the clob
  // token id, so the server emits one notice per clob token id AND one for
  // the numeric market id; for Kalshi it is the ticker.
  string contract_id = 1;
  string provider = 2;
  // Unix seconds when the resolution event was observed.
  int64 resolved_at_sec = 3;
}