SimTX API/Connection and handshake

Every SimTX game connection begins the same way: a TLS connection to the host and port from the server directory, an 8-byte preface and a ClientHello from the client, and a ServerHello from the server. What follows depends on the role the client asked for.

Transport

Property	Value
Transport	TCP
Security	TLS 1.3 or TLS 1.2, required. Verify the server certificate against the system's public CA store and the host name from the directory.
Port	From the server directory. The public deployment, argon.simtx.net, uses 5556.
Protocol version	25, sent in the preface. Must match exactly.
Framing	Varint length, then one protobuf ClientFrame or ServerFrame. See SimTX API/Framing.
Encoding	Standard protobuf 3. Sample payloads inside bytes fields are big-endian. See SimTX API/Data types.

Recommended socket options are TCP_NODELAY (frames are small and latency matters) and SO_KEEPALIVE. Ping and Pong are available on every role for round-trip measurement and liveness checks.

Unencrypted connections are accepted only by a development server bound to the loopback address. Public servers never accept them.

Connection sequence

 client                                                    server
   | ---- TCP connect, TLS handshake -----------------------> |
   | ---- preface  53 49 4D 54 00 00 00 19 ------------------> |
   | ---- [1] hello            ClientHello ----------------> |
   | <--- [1] hello_result     ServerHello ----------------- |   status 1 = ACCEPTED
   |                                                         |
   |   ROLE_RECEIVER:            [10] receiver_start ------> |   then session_status, IQ
   |   ROLE_TX_AUDIO / _GENERATED: [12] transmitter_start ---> |   then session_status, queue
   |   ROLE_CONTROL:             requests at once ---------> |   banner if a notice is active
   |   ROLE_MODERATION:          moderation requests ------> |

The numbers in brackets are the oneof member numbers of the frames. The preface, the hello and the first start frame must arrive within 5 seconds of connecting. Send them immediately after the TLS handshake completes.

Preface

The client opens the byte stream with 8 bytes: the magic number 0x53494D54 ("SIMT") and the protocol version 25, both as big-endian 32-bit integers. A server refuses any other version. The server sends no preface. Everything after it, in both directions, is framed. See Framing.

Hello

The first frame from the client must be ClientFrame.hello, a ClientHello:

message ClientHello {
  Role role = 1;
  AuthKind auth = 2;
  string credential = 3;        // stx_gt1_… game ticket; empty when anonymous
  string client_name = 4;       // e.g. "SimTX Transmitter"
  string client_version = 5;
  repeated string features = 6;  // client feature registry (see the top of this file)
  int32 protocol_revision = 7;    // highest protocol revision this client implements
}

• role selects the kind of session. It cannot change later on the same connection.
• auth and credential carry a game ticket for authenticated connections. Anonymous connections leave both unset; an anonymous hello that carries a credential is refused.
• client_name and client_version identify the software to operators.
• features and protocol_revision say which optional behaviours the client implements. See SimTX API/Compatibility and versioning.

The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and closes the connection 20 seconds after connecting if no hello has arrived.

Roles

Value	Name	Purpose	Authentication
1	ROLE_RECEIVER	Receive IQ. See Receiver session.	Anonymous for an ad-hoc site. A ticket (receiver) for a station-bound site.
2	ROLE_TX_AUDIO	Transmit audio or IQ streamed by the client. See Transmitter session.	Ticket (tx-audio) with game.transmit
3	ROLE_TX_GENERATED	Transmit a source generated by the server (white noise).	Ticket (tx-generated) with game.transmit
4	ROLE_CONTROL	Station list, banners, health, maps, ephemerides, passes, catalog, own-transmitter monitor. See Control session.	Anonymous, or ticket (control). A ticket unlocks the own-transmitter monitor and catalog publishing.
5	ROLE_MODERATION	Moderator tools. See Moderation session.	Ticket (moderation) with moderation.manage

ROLE_UNSPECIFIED (0) and unknown values are refused. Any receiver can ask for timestamps with ReceiverStart.timestamped, with or without an account.

An authenticated receiver behaves like an anonymous one, except that it may bind to a station, and receiver limits and permissions such as monitor.any are evaluated against the account.

Hello results

The server answers every hello with a ServerHello as its first frame. Status HELLO_STATUS_ACCEPTED means the session may begin. Any other status is followed by the server closing the connection.

Value	Name	Meaning
0	HELLO_STATUS_UNSPECIFIED	Not sent by servers. Treat it, and unknown values, as SERVER_UNAVAILABLE.
1	HELLO_STATUS_ACCEPTED	The session may begin.
2	HELLO_STATUS_VERSION_UNSUPPORTED	The preface version is not 25.
3	HELLO_STATUS_AUTHENTICATION_REQUIRED	The role needs a ticket and none was sent. Typical message: This role requires a SimTX account.
4	HELLO_STATUS_CREDENTIAL_INVALID	The ticket is unknown, expired, used, or minted for another server or role. Typical message: Game ticket is invalid or expired.
5	HELLO_STATUS_ACCOUNT_RESTRICTED	The account is restricted.
6	HELLO_STATUS_ROLE_FORBIDDEN	The account lacks the permission the role needs. Typical message: Account is not permitted to transmit.
7	HELLO_STATUS_SERVER_UNAVAILABLE	The server cannot verify the ticket or take the connection now. The only status worth retrying unchanged.
8	HELLO_STATUS_IP_BANNED	The client address is banned. The message gives the reason.

Only SERVER_UNAVAILABLE is worth retrying unchanged. A ticket is single-use, so every retry of an authenticated connection needs a new one.

Accounts on the connection

For an authenticated connection, the ServerHello carries the account's id, handle, display name and effective permissions, including numeric capabilities such as tx.pa_limit.400. Software should use these for display and to show limits, rather than asking the account service separately.

Authenticated connections carry a lease of about 12 hours, given as account.lease_expires_at_ms. When it runs out, the server closes the connection. A long-running client should reconnect with a fresh ticket before the lease expires. Changes to the account, such as a revoked device, a new restriction or a ban, can end its connections at any moment.

The ServerHello also carries the server's clocks. simulation_time_ms is the simulated world clock; use it, not the local clock, as "now" for satellite positions and pass predictions.

Connection limits

• At most 32 simultaneous connections per client IP address, and 256 per server in total. A connection over either limit is closed straight away, before the hello.
• Further limits on receivers and transmitters apply once a session is started. See SimTX API/Limits and errors.

Ping

ClientFrame.ping (Ping) is answered by ServerFrame.pong (Pong) on every role, at any time after the hello. Pongs may arrive between any other frames.

Examples

The preface, an anonymous receiver hello, and an accepted reply from a server that implements protocol revision 1:

preface (client to server, 8 bytes):

53 49 4D 54 00 00 00 19

hello_anonymous_receiver (client to server, 37 bytes):

24                                           frame length 36
0A 22                                        hello (ClientHello), 34 bytes
  08 01                                      role = 1 (ROLE_RECEIVER)
  22 0C 53 69 6D 54 58 20 47 6F 6C 64 65 6E  client_name = "SimTX Golden"
  2A 06 32 35 2E 30 2E 30                    client_version = "25.0.0"
  32 08 70 6F 69 6E 74 69 6E 67              features = "pointing"

hello_result_revision_1 (server to client, 96 bytes):

5F                                        frame length 95
0A 5D                                     hello_result (ServerHello), 93 bytes
  08 01                                   status = 1 (HELLO_STATUS_ACCEPTED)
  22 0B 73 74 61 74 69 6F 6E 73 2E 76 31  features = "stations.v1"
  22 08 70 6F 69 6E 74 69 6E 67           features = "pointing"
  22 09 65 70 68 65 6D 65 72 69 73        features = "ephemeris"
  22 06 70 61 73 73 65 73                 features = "passes"
  22 0A 6B 69 6E 65 6D 61 74 69 63 73     features = "kinematics"
  2A 13 73 69 6D 74 78 2D 73 65 …         server_version = "simtx-server/25.1.0"
  30 80 94 83 B9 97 34                    server_time_ms = 1793000000000
  38 F4 97 83 B9 97 34                    simulation_time_ms = 1793000000500
  40 01                                   protocol_revision = 1