Protocol Messages

{
  type: "hello",
  protocolVersion: "1.0",
  serverId: string,
  supportedGames: string[],       // ["texas-holdem", "blackjack", ...]
  capabilities: {
    provablyFair: boolean,
    multiTable: boolean
  },
  messageId: string,
  timestamp: number
}

{
  type: "authenticate",
  token: string,                  // Token from POST /api/auth/verify
  protocolVersion: "1.0",
  messageId: string,
  timestamp: number
}

{
  type: "authenticated",
  walletAddress: string,
  sessionId: string,
  expiresAt: number,              // Unix timestamp
  balance: number,                // Platform credit balance
  linkedUserId: string,           // Verified user account this client acts for
  permissions: {
    maxStakePerRound?: number,
    allowedGames?: string[],
    dailyLossLimit?: number
  },
  messageId: string,
  timestamp: number
}

// Client → Server
{ type: "balance_query", messageId: string, timestamp: number }

// Server → Client
{
  type: "balance_response",
  balance: number,                // Available (unlocked) balance
  lockedBalance: number,          // Credits currently in active bets/pots
  messageId: string,
  timestamp: number
}

// Client → Server
{ type: "session_extend", messageId: string, timestamp: number }

// Server → Client
{
  type: "session_extended",
  expiresAt: number,              // New expiry timestamp
  messageId: string,
  timestamp: number
}

{
  type: "session_expiring",
  expiresIn: number,              // Seconds until expiry
  messageId: string,
  timestamp: number
}

{ type: "heartbeat", messageId: string, timestamp: number }

{
  type: "error",
  code: string,                   // Error code (see Error Codes)
  message: string,                // Human-readable description
  relatedMessageId?: string,      // messageId that triggered the error
  messageId: string,
  timestamp: number
}