Skip to content
QuantLabTickDirect

DocsResources

SBE schema

The formal definition of the messages (a FIX SBE XML schema).

Every message is defined in this XML schema. The tables in Message format are written from it.

Download freqrelay-sbe.xml
FieldValue
packagefreqrelay
Schema ID1
version1
Byte orderLittle-endian

Generating codecs

SBE code generators can produce encoding and decoding code from this schema. For example, the tool in Real Logic's SBE generates code for Java, C++, C#, Go, and Rust.

The messages are small and close to fixed-size, so you can also write the code by hand from the tables in Message format. The Python sample is written by hand with struct.

Schema

Show freqrelay-sbe.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
  FreqRelay の配信プロトコル(FIX Simple Binary Encoding)。購読者と FreqRelay の間は UDP で、1 データグラムに 1 メッセージを入れる。
  1 データグラムは 1200 バイト以下にする。用語は CONTEXT.md、設計判断は docs/adr/0003、0004、0010 を参照。

  購読者は、次の手順で受け取り始める(ADR 0010)。
    Hello → Challenge(cookie)→ Authenticate(nonce に cookie を入れた JWT)→ AuthenticateAck(購読者トークン)
    → Subscribe(購読者トークン)→ SubscribeAck → 1 秒ごとに Heartbeat(購読者トークン)→ HeartbeatAck
  version 0(Phase1)とは互換性がない。
-->
<sbe:messageSchema xmlns:sbe="http://fixprotocol.io/2016/sbe"
                   package="freqrelay"
                   id="1"
                   version="1"
                   semanticVersion="0.2.0"
                   description="FreqRelay tick relay protocol"
                   byteOrder="littleEndian">
    <types>
        <composite name="messageHeader" description="Message identifiers and length of the message root">
            <type name="blockLength" primitiveType="uint16"/>
            <type name="templateId" primitiveType="uint16"/>
            <type name="schemaId" primitiveType="uint16"/>
            <type name="version" primitiveType="uint16"/>
        </composite>
        <composite name="groupSizeEncoding" description="Repeating group dimensions">
            <type name="blockLength" primitiveType="uint16"/>
            <type name="numInGroup" primitiveType="uint16"/>
        </composite>
        <composite name="varDataEncoding" description="Variable-length data: a length followed by that many bytes">
            <type name="length" primitiveType="uint16" maxValue="1024"/>
            <type name="varData" primitiveType="uint8" length="0"/>
        </composite>
        <composite name="Price" description="Fixed-point price: mantissa x 10^exponent">
            <type name="mantissa" primitiveType="int64"/>
            <type name="exponent" primitiveType="int8" presence="constant">-8</type>
        </composite>
        <type name="SymbolName" primitiveType="char" length="16" characterEncoding="UTF-8"
              description="Symbol name, padded with zero bytes"/>
        <type name="SymbolId" primitiveType="uint16" description="Symbol ID assigned by FreqRelay"/>
        <type name="OptionalSymbolId" primitiveType="uint16" presence="optional" nullValue="65535"
              description="Symbol ID, or null when the symbol does not exist"/>
        <type name="UnixNanos" primitiveType="int64" description="UTC time in nanoseconds since 1970-01-01"/>
        <type name="RequestId" primitiveType="uint32"/>
        <type name="SequenceNumber" primitiveType="uint64"/>
        <type name="SubscriberToken" primitiveType="uint8" length="16"
              description="Random value that FreqRelay issues on authentication. Valid only from the endpoint that authenticated"/>
        <type name="Cookie" primitiveType="uint8" length="16"
              description="Short-lived value bound to the endpoint and a time window. Put it in the JWT nonce (URL-safe Base64 without padding)"/>
        <type name="HelloPadding" primitiveType="uint8" length="32"
              description="Zero bytes that keep Hello larger than Challenge, so that FreqRelay never amplifies a spoofed request"/>
        <enum name="BooleanType" encodingType="uint8">
            <validValue name="False">0</validValue>
            <validValue name="True">1</validValue>
        </enum>
        <enum name="UpstreamStatus" encodingType="uint8">
            <validValue name="Disconnected">0</validValue>
            <validValue name="Connecting">1</validValue>
            <validValue name="Connected">2</validValue>
        </enum>
        <enum name="AuthenticateResult" encodingType="uint8">
            <validValue name="Accepted" description="The subscriber is created. Send Subscribe with the token">0</validValue>
            <validValue name="InvalidCookie" description="The nonce is not a valid cookie for this endpoint (expired, or for another endpoint). Start again from Hello">1</validValue>
            <validValue name="MalformedToken" description="The JWT cannot be read, alg is not EdDSA, or a required claim (iss, iat, exp) is missing">2</validValue>
            <validValue name="InvalidSignature" description="The signature does not match the public key of the API key">3</validValue>
            <validValue name="TokenExpired" description="exp has passed, iat is in the future, or exp - iat exceeds 5 minutes">4</validValue>
            <validValue name="AudienceMismatch" description="aud is not the expected value">5</validValue>
            <validValue name="UnknownKey" description="The key ID is not known yet. A newly issued key becomes usable within about a minute">6</validValue>
            <validValue name="KeyRevoked" description="The API key was revoked (reissued or the contract ended)">7</validValue>
            <validValue name="KeyExpired" description="The contract period of the API key has ended">8</validValue>
            <validValue name="PlanNotAccepted" description="The plan of the API key is not served by this server">9</validValue>
            <validValue name="IpLimitReached" description="The API key already has subscribers on as many IP addresses as its plan allows">10</validValue>
            <validValue name="EndpointLimitReached" description="The API key already has the maximum number of subscribers on this IP address">11</validValue>
            <validValue name="ServerFull" description="The server has reached its subscriber limit">12</validValue>
            <validValue name="RateLimited" description="Too many requests. Retry later">13</validValue>
            <validValue name="NotReady" description="The server has not loaded the API keys yet. Retry later">14</validValue>
        </enum>
        <enum name="SubscribeResult" encodingType="uint8">
            <validValue name="Accepted" description="The subscription is replaced with the requested symbols">0</validValue>
            <validValue name="UnknownSubscriber" description="The token is not valid from this endpoint. Authenticate again">1</validValue>
        </enum>
        <enum name="SubscriberEndReason" encodingType="uint8">
            <validValue name="None" description="The subscriber is alive">0</validValue>
            <validValue name="Unknown" description="FreqRelay does not know the token (for example, after a restart)">1</validValue>
            <validValue name="HeartbeatTimeout" description="Heartbeats stopped for too long">2</validValue>
            <validValue name="Unsubscribed" description="The subscriber sent an empty Subscribe">3</validValue>
            <validValue name="KeyRevoked" description="The API key was revoked">4</validValue>
            <validValue name="KeyExpired" description="The contract period of the API key has ended">5</validValue>
            <validValue name="Replaced" description="The endpoint authenticated again with another API key">6</validValue>
        </enum>
    </types>

    <sbe:message name="Subscribe" id="1"
                 description="Subscriber to FreqRelay. Replaces the subscription with the given set of symbols (at most 64). An empty set ends the subscriber.">
        <field name="subscriberToken" id="1" type="SubscriberToken"/>
        <field name="requestId" id="2" type="RequestId" description="Echoed in SubscribeAck"/>
        <group name="symbols" id="3" dimensionType="groupSizeEncoding">
            <field name="name" id="4" type="SymbolName"/>
        </group>
    </sbe:message>

    <sbe:message name="SubscribeAck" id="2"
                 description="FreqRelay to subscriber. When accepted, one entry per requested symbol, in request order. Otherwise no entries.">
        <field name="requestId" id="1" type="RequestId"/>
        <field name="result" id="2" type="SubscribeResult"/>
        <group name="symbols" id="3" dimensionType="groupSizeEncoding">
            <field name="symbolId" id="4" type="OptionalSymbolId"/>
            <field name="name" id="5" type="SymbolName"/>
        </group>
    </sbe:message>

    <sbe:message name="Heartbeat" id="3"
                 description="Subscriber to FreqRelay, every second. The subscriber expires after 5 seconds without one.">
        <field name="subscriberToken" id="1" type="SubscriberToken"/>
    </sbe:message>

    <sbe:message name="HeartbeatAck" id="4" description="FreqRelay to subscriber, in reply to each Heartbeat.">
        <field name="subscribed" id="1" type="BooleanType"
               description="False when the subscriber has ended; authenticate again"/>
        <field name="upstreamStatus" id="2" type="UpstreamStatus"/>
        <field name="endReason" id="3" type="SubscriberEndReason" description="Why the subscriber ended, when subscribed is False"/>
    </sbe:message>

    <sbe:message name="Ticks" id="5" description="FreqRelay to subscriber. Ticks of the subscribed symbols.">
        <field name="sequence" id="1" type="SequenceNumber"
               description="Per-subscriber datagram sequence, starting at 1. A gap means lost datagrams."/>
        <group name="ticks" id="2" dimensionType="groupSizeEncoding">
            <field name="symbolId" id="3" type="SymbolId"/>
            <field name="bid" id="4" type="Price"/>
            <field name="ask" id="5" type="Price"/>
            <field name="upstreamTime" id="6" type="UnixNanos"/>
            <field name="receiveTime" id="7" type="UnixNanos"/>
        </group>
    </sbe:message>

    <sbe:message name="Hello" id="6" description="Client to FreqRelay. Starts authentication. FreqRelay answers with Challenge.">
        <field name="padding" id="1" type="HelloPadding"/>
    </sbe:message>

    <sbe:message name="Challenge" id="7" description="FreqRelay to client, in reply to Hello.">
        <field name="cookie" id="1" type="Cookie"/>
    </sbe:message>

    <sbe:message name="Authenticate" id="8"
                 description="Client to FreqRelay. A JWT (compact form, ASCII) signed with the API key: alg EdDSA, iss key ID, aud, iat, exp (at most 5 minutes after iat), nonce cookie.">
        <field name="requestId" id="1" type="RequestId" description="Echoed in AuthenticateAck"/>
        <data name="token" id="2" type="varDataEncoding"/>
    </sbe:message>

    <sbe:message name="AuthenticateAck" id="9" description="FreqRelay to client, in reply to Authenticate.">
        <field name="requestId" id="1" type="RequestId"/>
        <field name="result" id="2" type="AuthenticateResult"/>
        <field name="subscriberToken" id="3" type="SubscriberToken" description="Zero unless the result is Accepted"/>
    </sbe:message>
</sbe:messageSchema>