BOLD #3: Trade Protocol

Overview

OpenDEX does not rely on a central order book or matching engine. Instead, each node on the network maintains its own local order book and matching engine.

Order matching systems of major exchanges differentiate between two participants: the taker and the maker. A taker "fills" the order of a maker.

Similarly, we distinguish between these two types of participants in a trade on OpenDEX:

  • The Maker: submits an order which cannot be matched immediately by an existing order in the order book. The order is added to the order book and propagated to all connected peers.

  • The Taker: issues an order which can immediately be matched with an existing (maker) order in the order book.

Order Type

`string id = 1`
The order's globally unique identifier, generated by the sender
`string pair_id = 1`
A trading pair symbol, constructed with the base currency first, followed by a '/' separator and the quote currency (e.g., “LTC/BTC”)
`double price = 3`
The price for the order expressed in units of the quote currency
`uint64 quantity = 4`
The number of satoshis (or equivalent) for the order
`bool is_buy = 5`
Whether the order is a buy (true) or a sell (false)
`string replace_order_id = 6`
The id of an order that this order is replacing, the specified order should be removed

Trade Protocol

Order Message (0x06)

`string id = 1`
The message's globally unique identifier, generated by the sender
`Order order = 2`
The order

The Order message is used to tell a peer about a new maker order. It should only be sent to peers after the order (or part of the order) could not be matched in the local order book.

OrderInvalidation Message (0x07)

`string id = 1`
The message's globally unique identifier, generated by the sender
`string order_id = 2`
The order’s unique identifier
`string pair_id = 3`
The trading pair symbol associated with the order
`uint64 quantity = 4`
The number of satoshis (or equivalent) to invalidate from the order sum

The OrderInvalidation message is used to tell a peer about the full or partial invalidation of a previously sent order. It allows the peer to remove the order from his local order book. Order invalidation is a common event which occurs due to order cancellation or filling (by another node). Failing to send updates about the order will result in peers having a stale order in their local order books. These peers might fill the order and instantiate swap procedures which are doomed to fail. In this case, the maker node’s reputation may be penalized.

The GetOrders Message (0x08)

`string id = 1`
The message's globally unique identifier, generated by the sender
`repeated string pair_ids = 2`
The requested orders trading pair symbols, constructed with the base currency first, followed by a '/' separator and the quote currency (e.g., [“LTC/BTC”, “DAI/BTC”])

The GetOrders message is used to query a peer for a list of all open orders for the specified trading pairs. It is mainly used to initialize the local order book with a snapshot of the peer's existing open orders after establishing a connection to the peer. New orders are expected to get pushed by the peer via the Order message, instead of being queried for.

The Orders Message (0x09)

`string id = 1`
The message's globally unique identifier, generated by the sender
`string req_id = 2`
The id from the received `GetOrders` message
`repeated Order orders = 3`
The list of orders

The Orders message is used to respond to the GetOrders message.