ORE Studio Binary Protocol Reference

• Protocol version 7 adds correlation_id field to frame header for
• request/response matching, enabling concurrent operations and server-push
• notifications.
• Version 7.1 adds subscription protocol messages (subscribe_request,
• subscribe_response, unsubscribe_request, unsubscribe_response, notification)
• for server-push event notifications.
• Version 7.2 changes logout_request to have empty payload. Account ID is now
• determined from session context to prevent clients from forging logout
• requests for other users.
• Version 7.3 adds database_status_notification message for server-push
• database health status updates, and database_unavailable error code.
• Version 8.0 removes requester_account_id from lock_account_request and
• unlock_account_request. Authorization is now handled via server-side session
• tracking instead of client-provided identity. This is a breaking change.
• Version 9.0 adds optional payload compression support. The reserved1 field
• in the frame header is now used for compression_type (1 byte) and flags
• (1 byte). Supported compression algorithms: none, zlib, gzip, bzip2.
• Uncompressed payloads remain fully supported (compression_type::none).
• Version 10.0 replaces valid_from/valid_to fields with recorded_by/recorded_at
• in domain types (currency, account, feature_flags). This is a breaking change
• affecting all entity serialization in the protocol.
• Version 10.1 adds update_account_request and update_account_response messages
• for editing existing account email and admin status.
• Version 11.0 changes lock_account_request and unlock_account_request to support
• batch operations with a vector of account IDs. Responses now return a vector of
• per-account results (lock_account_result/unlock_account_result). This is a
• breaking change as the wire format is incompatible with previous versions.
• Version 12.0 adds reset_password_request and reset_password_response messages
• for admin-initiated password reset. Adds password_reset_required field to
• login_response and list_login_info_response. This is a breaking change as
• existing serialization formats are extended with new fields.
• Version 13.0 adds role-based access control (RBAC) with full authorization
• system. New domain types: permission, role, account_role, role_permission.
• New RBAC messages: list_roles_request/response, list_permissions_request/response,
• assign_role_request/response, revoke_role_request/response,
• get_account_roles_request/response, get_account_permissions_request/response.
• Adds authorization checks to all protected endpoints. This is a breaking change
• as it introduces mandatory RBAC enforcement for administrative operations.
• Version 13.1 adds user self-registration (signup) workflow. New messages:
• signup_request/response for creating accounts without admin privileges.
• New error codes: signup_disabled, username_taken, email_taken,
• signup_requires_authorization. Signup is controlled by system.user_signups
• feature flag.
• Version 14.0 adds assets subsystem for dynamic image loading. New messages:
• get_currency_images_request/response for retrieving currency-image mappings,
• get_images_request/response for batched image retrieval (max 100 per request).
• This enables the UI to display flag icons for currencies.
• Version 15.0 adds session tracking and statistics. New messages:
• list_sessions_request/response for querying session history by account,
• get_session_statistics_request/response for aggregated session metrics.
• Sessions now track bytes sent/received, client version, and geolocation.
• Session data is stored in a TimescaleDB hypertable for time-series analysis.
• Version 15.1 adds telemetry subsystem for log record streaming. New messages:
• submit_log_records_request for fire-and-forget batched log record submission.
• Clients can stream telemetry data to the server for centralized storage and
• analysis. Controlled by telemetry.streaming.enabled feature flag.
• Version 16.0 adds entity_ids field to notification_message. This allows
• clients to identify which specific entities changed (e.g., currency ISO codes
• or account IDs) rather than just knowing that some entity of a type changed.
• This is a breaking change as the wire format for notifications is extended.
• Version 16.1 adds list_images_request/response to list all available flag images,
• and set_currency_image_request/response to assign or remove flags from currencies.
• Version 16.2 adds server-side telemetry persistence. New messages:
• submit_telemetry_response (0x5001) for acknowledging batch submissions.
• get_telemetry_logs_request/response (0x5010/0x5011) for querying raw logs.
• get_telemetry_stats_request/response (0x5020/0x5021) for querying aggregated stats.
• Telemetry logs are stored in a TimescaleDB hypertable with 30-day retention.
• Version 17.0 removes obsolete currency_image junction table messages. The
• image_id field is now directly on the currency entity, so currency->image
• mappings come from get_currencies_response. Flag changes appear in currency
• version history. Removed messages: get_currency_images_request/response,
• set_currency_image_request/response. Breaking change.
• Version 18.0 uses 32-bit length prefix for svg_data in get_images_response.
• Previously used 16-bit length which truncated SVGs larger than 65535 bytes.
• This is a breaking change affecting image serialization.
• Version 19.0 adds recorded_at field to list_feature_flags_response.
• Previously the timestamp was not serialized. Breaking change.
• Version 20.0 adds version field to list_feature_flags_response.
• Breaking change.
• Version 20.1 adds countries subsystem messages for CRUD operations on
• ISO 3166-1 country reference data. New messages: get_countries_request/response,
• save_country_request/response, delete_country_request/response,
• get_country_history_request/response.

1. Client establishes SSL/TLS connection to server
2. Three-way handshake:
   • Client sends handshake_request with protocol version
   • Server responds with handshake_response indicating compatibility
   • Client sends handshake_ack to complete

1. Client sends login_request with credentials
2. Server validates against account service
3. On success, server stores session context (remote_addr -> account_id)
4. Server returns login_response with account info and admin status

Admin-only operations (lock/unlock account) use server-side session tracking:

1. Client sends request (e.g., lock_account_request)
2. Server looks up requester's account_id from session context
3. Server verifies admin privileges via account service
4. If authorized, operation proceeds; otherwise error returned

1. Client sends logout_request
2. Server clears session context
3. Server updates login_info (online=false)
4. Connection closed