Qurrex mathcing module. Specification.

Transcription

1 Qurrex mathcing module Specification

2 Table of contents Introduction... 2 Module description... 3 Matching auction... 3 Features of the current implementation... 3 Types of messages... 4 New order... 4 Type of order... 4 Type of execution and time in force... 4 Cancellation of the order... 5 Bulk cancellation of orders... 5 Message formats... 6 Message... 6 Header... 7 NewOrder... 7 NewOrderReport... 9 CancelRequest CancelReport MassCancelRequest MassCancelReport ExecutionReport Deal RejectReport Error codes

3 Introduction The matching module is the central element of any exchange that is responsible for processing, storing and aggregating incoming orders, requests for orders cancellation, and generating transactions reports. The performance of the entire exchange, in general, depends on the performance of the matching module. The key feature of the matching module of Qurrex is its performance and scalability capabilities. During the internal testing phase, the matching module has already shown the performance of over 3 million transactions per second (without recording information about orders and transactions to the hard drive). Rich experience of the team in the building of exchange systems allowed to achieve results, which can not show any of the known to us crypto-exchanges at the moment. 2

4 Module description Matching auction The Qurrex matching module uses the Time Priority principle of matching auction. This principle means that if the price of two orders is equal, the higher priority of execution has the order that was previously registered in the matching module. Features of the current implementation For testing purposes, the current implementation of matching has the following features: The matching module is available 24/7, except for restarts and software updates. The current implementation of the module consists of: o Matching core; o "Light" Gateway; o Statistics service. This is not an industrial configuration because it disables a number of functional and business logic checks to simplify testing for end customers. The matching module supports non-linear paralleling of the matching cores and network gateways, which allows scaling within the server and increasing the throughput of the entire module as a whole. There is no authorization system. Each connection (TCP connection) to the module is unique. All activity is carried out within the connection. When the connection is broken, all active orders are removed. Client Request must be a unique identifier within the connection. Client s, such as Clearing Account and Trader Account, are filled with arbitrary values. Thus the Error 2000 "Wrong Clearing Account or the Client (Trader Account )" is possible only in response to CancelRequest. The Transaction report (ExecutionReport) can contain a maximum of 5 transactions. If more than five transactions were made, then the matching module will send several transaction reports. 3

5 Types of messages Messages are divided into two types: requests and reports. In response to each request, the matching module sends one or more reports. The matching module accepts the following types of requests: new order; cancellation of the order; cancellation of all orders. New order This request allows you to add a new order to the system using the trading instrument you specify. The format of the request body is described in NewOrder section. The following types of reports may be sent in response to this request: NewOrderReport report on the successful addition of a new order; CancelReport report on the successful cancellation of the order or its unexecuted part; ExecutionReport report on the execution of the order or its part and the conclusion of transactions on it; RejectReport report on a rejection of the order. Type of order The order type is specified in the Order type field. The following types are available: LIMIT is an ordinary limit order, which is issued at the specified price. HDEN is a hidden limit order that is displayed at the specified price. Orders of this type are not reflected in the public Order Book. Type of execution and time in force The type of execution and the validity time of the order are specified in the Order Time in force field. The following types are available: Good-Till-Cancel (hereinafter "GTC") - an order that will act until it is canceled. Immediate-or-Cancel (hereinafter "IOC") - an order that will be executed immediately and the remainder will be withdrawn. In addition to NewOrderReport message, in response to such an order, ExecutionReport and/or CancelReport messages will be sent immediately. Fill-or-Kill (hereinafter "FOK") - an order that is rejected if it cannot be fully executed immediately. Unlike IOC, this type of order does not imply partial execution. If the order is successfully added, NewOrderReport and ExecutionReport messages will be sent to the response. In case the order is rejected, RejectReport message will be sent in response. 4

6 Cancellation of the order This request allows you to cancel a previously added order. It will only remove the unfulfilled volume. The format of the request body is described in CancelRequest section. In case the order is rejected, CancelReport message will be sent in response. If the order cannot be canceled or the request has been generated with an error, RejectReport message will be sent. Bulk cancellation of orders This request allows you to undo all previously added orders for the specified trading instrument. The format of the request body is described in MassCancelRequest section. CancelReport message will be sent for each canceled order. MassCancelReport message will be sent after all available orders have been withdrawn. If the request was generated with an error, RejectReport message will be sent. 5

7 Message formats Any message has the format that is described in the Message section. The table describing the formats contains the following columns: Offset The offset of the field in bytes relative to the beginning of the message or its part. Required fields are marked with "*". Field is the name of the field. If the name begins with the ">" character, it means that this part of the message is described in detail in another section. Type the type of the value for the specified field. Description Description of the field. Message Each message can be divided into two components: Header and Body of the message. In some messages, the body may include other parts described in this document. For example,executionreport might include the transactions that are described in the Deal section. 0* > Header The message header. 12* > Body The message body. Possible values are: NewOrder NewOrderReport CancelRequest CancelReport MassCancelRequest MassCancelReport ExecutionReport RejectReport 6

8 Header The header format is common for all message types. The message sequence should increase linearly for messages sent within the connection. That is, the value in this field must be equal to one plus the value of this field in the previous sent message. If this condition is not met, the connection will be broken. The first message sent by the client to the server must be filled in with Message Sequence = 1. When a client interacting with a gateway, there are two Message Sequence sequences: from the client to the gateway; from the gateway to the client. 0* Message Type ushort An identifier that indicates the type of message. The following values are possible: 1 (NewOrder) 2 (NewOrderReport) 3 (CancelRequest) 4 (CancelReport) 5 (ExecutionReport) 12 (MassCancelRequest) 14 (MassCancelReport) 20 (BestPrice) 2* Message Length ushort The size of the message body, in bytes. 4* Message Sequence ulonglong The sequence number of the message to be send. NewOrder Request to add a new order. The order of the message fields check: 1. Check of the header filling. 2. Verification of the uniqueness of the Client Request within the current connection. In case of failure, the 2001 error will occur. 3. Verification of filling in the Clearing Account and Trader Account fields. In case of failure, the 2000 error will occur. 4. Verification of the Instrument field being filled. In case of failure, the 2002 error will occur. 5. Check of related parameters of the order, reflecting the type of order and conditions of execution. These fields are Order Type, Order Time in force, Auto Cancel or Order Side. Any combination of these fields can be used in the current implementation. Later, the valid Order Time in force values will depend on other fields, such as Order Type. In case of failure, the 2003 error will occur. 6. Check of the quantity of the order: the quantity of the order must be positive and multiple of the minimum lot value. In case of failure, the 2004 error will occur. 7

9 7. Check of order prices: the price in the order must be multiple of the price step of the instrument. To buy and sell instruments the price should be positive. In case of failure, the 2005 error will occur. 8. Check of the price being within the price limits specified in the configuration of trading instrument. In case of failure, the 2006 error will occur. 0* Client Request Client of the request. Must be unique within the connection. 16* Clearing Account 32* Trader Account of the trading account. Client. 48* Instrument uint of the trading instrument. 52* Order Type byte Order type, the following values are possible: 1 (LIMIT) 2 (HDEN) 53* Order Time in force byte Type of execution and time in force: 1 (GTC) 2 (IOC) 3 (FOK) 54* Order Side byte Order direction: 1 (BUY) 2 (SELL) 55* Auto Cancel byte Automatic orders removal mode when the connection is broken. The only available value is: 1 (ON) 56* Order Qty decimal_8 Quantity of the order can be fractional. 64* Order Price decimal_8 Price of the order. 72 Flags ulonglong Flags of the order. This is a reserved field that is not processed in the current implementation. 80 Comment Comment to the order. 8

10 NewOrderReport Report on adding a new order. 0 Input System time 8 Output System Time UNIX time UNIX time Time to receive the request on the gate side. Time to send a response to a request on the gate side. 16 Client Request Client of the request. 32 Clearing Account 48 Trader Account of the trading account. Client. 64 Instrument uint of the trading instrument. 68 Order Type byte Order type, the following values are possible: 1 (LIMIT) 2 (HDEN) 69 Order Time in force byte Type of execution and time in force: 1 (GTC) 2 (IOC) 3 (FOK) 70 Order Side byte Order direction: 1 (BUY) 2 (SELL) 71 Auto Cancel byte Automatic orders removal mode when the connection is broken. The only available value is: 1 (ON) 72 Order Qty decimal_8 Quantity of the order. 80 Order Price decimal_8 Price of the order. 88 flags ulonglong Flags of the order. This is a reserved field that is not processed in the current implementation. 96 Comment Comment to the order. 112 System time UNIX time Order acceptance time. 120 Exchange Order ulonglong Order assigned by the exchange. 128 Liquidity Pool ushort Liquidity pool where the order was sent. The only available value is: 0 (DEFAULT) 9

11 130 Order Routing Rule ushort Order routing algorithm. The only available value is: 1 (All pools) CancelRequest Request to cancel the order. One of the fields must be filled in CancelRequest: Exchange Order Original Client Request The order of the message fields check: 1. Check of the header filling. 2. Verification of the uniqueness of the Client Request within the current connection. In case of failure, the 2001 error will occur. 3. Verification of filling in the Clearing Account and Trader Account fields. In case of failure, the 2000 error will occur. 4. Verification of the Instrument field being filled. In case of failure, the 2002 error will occur. 5. Check of the filling of the Exchange Order field and search for an order with this. In case of failure, the 3001 error will occur. 6. Check of the filling of the Original Client Request field and search for an order with this. In case of failure, the 3000 error will occur. 7. Additional request checks. In case of failure, the 3003 error will occur. 0* Client Request Client of the request. Must be unique within the connection. 16* Clearing Account 32* Trader Account of the trading account. Client. 48* Instrument ushort of the trading instrument. 52 Exchange Order 60 Original Client Request ulonglong Exchange of the withdrawn order. Client of the order that is being removed, specified earlier in the NewOrder request. 76* Order Side byte Order direction: 1 (BUY) 2 (SELL) 10

12 CancelReport Report on the removal of the order. 0 Input System time 8 Output System Time UNIX time UNIX time Time to receive the request on the gate side. Time to send a response to a request on the gate side. 16 Client Request Client of the request. 32 Clearing Account 48 Trader Account of the trading account. Client. 64 Instrument ushort of the trading instrument. 66 Exchange Order 74 Original Client Request ulonglong Order assigned by the exchange. Client of the order to be removed. 90 Order Side byte Order direction: 1 (BUY) 2 (SELL) 91 System time UNIX time The request processing time that resulted in the cancellation of the order. 99 Amount Canceled double Volume removed. 107 Amount Rest double Volume that was not removed because of being executed. 115 Cancel Reason ushort Removal reason code. Possible values are: 0 (USER CANCEL) 1 (USER MASS CANCEL) 2 (DISCONNECT) 3 (EXPIRED) 4 (SYSTEM CANCEL) 11

13 MassCancelRequest Request to cancel all orders within the connection. The order of the message fields check: 1. Check of the header filling. 2. Verification of the uniqueness of the Client Request within the current connection. In case of failure, the 2001 error will occur. 3. Verification of filling in the Clearing Account and Trader Account fields. In case of failure, the 2000 error will occur. 4. Verification of the Instrument field being filled. In case of failure, the 2002 error will occur. 5. Check of filling of the Mode field In case of failure, the 3003 error will occur. 0* Client Request Client of the request. Must be unique within the connection. 16* Clearing Account 32* Trader Account of the trading account. Client. 50* Instrument uint of the trading instrument. MassCancelReport The MassCancelRequest request report. 0 Input System time UNIX time Time to receive the request on the gate side. 8 Output System Time UNIX time Time to send a response to a request on the gate side. 16 System time UNIX time The time the request was processed by the matching module. 24 Client Request Client of the request. 40 Clearing Account of the trading account Trader Account Client. 72 Instrument uint of the trading instrument. 76 Cancel Mode byte Mass cancel mode: 1 (By connect) 2 (By connect and instrument) 3 (By connect and client) 77 Cancel Status byte Result of mass cancel:

14 78 Canceled orders count uint 0 (NOTHING) 1 (CANCELED) 2 (CANCEL FAILED) Number of removed orders. ExecutionReport 0 Client Request Client of the request. 16 Clearing Account 32 Trader Account of the trading account. Client. 48 Instrument uint of the trading instrument. 52 Order Type byte Order type, the following values are possible: 1 (LIMIT) 2 (HDEN) 53 Order Time in force byte Type of execution and time in force: 1 (GTC) 2 (IOC) 3 (FOK) Order Side byte Order direction: 1 (BUY) 2 (SELL) 55 Auto Cancel byte Automatic orders removal mode when the connection is broken. The only available value is: 1 (ON) 56 Order Qty decimal_8 Quantity of the order. 64 Order Price decimal_8 Price of the order. 72 Flags longlong Flags of the order. This is a reserved field that is not processed in the current implementation. 80 Comment Comment to the order. 96 System time UNIX time Time of the conclusion of the transaction or transactions. 104 Amount Rest double Unfulfilled volume of the order. 105 Deals count byte Number of transactions concluded. 106 >Deal A Deal message that contains information about the transaction. ExecutionReport can include up to five deals that go one after another.

15 14

16 Deal 0 Deal Price decimal_8 Deal price. 8 Deal ulonglong The deal assigned by the exchange. 16 Deal qty decimal_8 The number of lots of the deal. RejectReport 0 Input System time 8 Output System Time UNIX time UNIX time Time to receive the request on the gate side. Time to send a response to a request on the gate side. 16 System time UNIX time The request processing time. 24 Client Request Client of the request. 40 Reason Code ushort Error code (reason for rejecting the request). See possible values in the Error codes section. 15

17 Error codes A list of error codes that describe the reasons of the request rejection. Error code Description 1000 Invalid message format 1001 Invalid header filling 2000 Invalid trading account (Clearing Account ) or Client (Trader Account ) 2001 Not a unique Client Request 2002 Invalid trading instrument (Instrument ) 2003 Incorrect order parameters (Order Type, Order Time in force, Auto Cancel or Order Side) 2004 Wrong quantity (Order Qty) 2005 Wrong Price (Order Price) 2006 Price beyond the limits (Order Price) 3001 Invalid Exchange Order 3002 Invalid Original client request 3003 Incorrect other parameters 16