ORE Studio Binary Protocol Reference

Table of Contents

This document provides a comprehensive reference for the ORE Studio binary protocol. It is auto-generated from the C++ header files and should be regenerated whenever protocol changes are made.

To regenerate: cmake --build --preset linux-clang-debug --target generate_protocol_docs

Protocol Version

Current version: 8.0

Version History

  • 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 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.

Subsystems

The protocol is organized into subsystems, each with its own message range:

Subsystem Range Component Messages
Core 0x0000-0x0FFF ores.comms 11
Risk 0x1000-0x1FFF ores.risk 8
Accounts 0x2000-0x2FFF ores.accounts 20
Variability 0x3000-0x3FFF ores.variability 2

Session Lifecycle

The following diagram illustrates the session lifecycle for authentication and account management operations.

protocol.session.png

Figure 1: Session Lifecycle - Authentication and Account Management

Connection Establishment

  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

Authentication

  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

Authenticated Operations

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

Session Termination

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

Error Codes

Code Name
0x0000 none
0x0001 version_mismatch
0x0002 crc_validation_failed
0x0003 invalid_message_type
0x0004 handshake_timeout
0x0005 handshake_failed
0x0006 payload_too_large
0x0007 network_error
0x0008 handler_error
0x0009 database_error
0x000A authentication_failed
0x000B authorization_failed
0x000C invalid_request
0x000D bootstrap_mode_only
0x000E bootstrap_mode_forbidden
0x000F weak_password
0x0010 not_localhost

All Messages Quick Reference

ID Name Subsystem
0x0001 handshake_request Core
0x0002 handshake_response Core
0x0003 handshake_ack Core
0x0004 error_response Core
0x0005 ping Core
0x0006 pong Core
0x0010 subscribe_request Core
0x0011 subscribe_response Core
0x0012 unsubscribe_request Core
0x0013 unsubscribe_response Core
0x0014 notification Core
0x1001 get_currencies_request Risk
0x1002 get_currencies_response Risk
0x1003 save_currency_request Risk
0x1004 save_currency_response Risk
0x1005 delete_currency_request Risk
0x1006 delete_currency_response Risk
0x1007 get_currency_history_request Risk
0x1008 get_currency_history_response Risk
0x2001 create_account_request Accounts
0x2002 create_account_response Accounts
0x2003 list_accounts_request Accounts
0x2004 list_accounts_response Accounts
0x2005 login_request Accounts
0x2006 login_response Accounts
0x2007 unlock_account_request Accounts
0x2008 unlock_account_response Accounts
0x2009 delete_account_request Accounts
0x200A delete_account_response Accounts
0x200B list_login_info_request Accounts
0x200C list_login_info_response Accounts
0x200D logout_request Accounts
0x200E logout_response Accounts
0x200F create_initial_admin_request Accounts
0x2010 create_initial_admin_response Accounts
0x2011 bootstrap_status_request Accounts
0x2012 bootstrap_status_response Accounts
0x2013 lock_account_request Accounts
0x2014 lock_account_response Accounts
0x3000 list_feature_flags_request Variability
0x3001 list_feature_flags_response Variability