5.3. Standardized order package

Each order represents a trading intention packaged in a message containing order parameters concatenated and hashed to 32 bytes using the Keccak SHA3 function. The maker signs the order with the private key associated with his node id.

Once packaged, the order can be sent to the recipient using whatever medium of communication, even a direct message (e.g., via email or a messaging application) or a DHT (§5.4). The communication system can also work on a TOR network so that users can communicate directly without exposing each other’s IP addresses.

The message might be structured as follows (19):

Field	Description
orderid	Unique identifier of the order to avoid duplicates and to update the order (when finalized)
open	Boolean to indicate if the order is open or closed (once fulfilled, orders are updated)
nodeID	Identity of the maker constituting the point of contact
signature	Orders are signed with the private key associated with the nodeID (public) to prove the ownership and update them
tokenA	Contract address of the tokenA offered by the maker
valueA	total units of tokenA offered by the maker
tokenB	Contract address of the tokenB requested by the maker
valueB	total units of tokenB requested by the maker
expiration	time at which the order expires in terms of Bitcoin block height
priceRange	% of deviation from the price (valueA/valueB ratio) accepted by the maker (optional)
multipartySwap	If equal to tokenA, it enables only an exact match (no multi-party swap) If different from tokenA, it indicates the minimum amount of token accepted for a multi-party swap (less or equal than tokenA/2)
feeRecipient	address of a book aggregator (optional)
feeToken	Contract address of the token used to pay the book aggregator (optional)
feeAmount	Fee amount paid to the book aggregator (optional)
lightningSwap	Indicates if the order has to be executed on Lightning Network (optional)

The data contained in the order does not reveal confidential information that directly relates to the maker except for the maker’s node id, which is necessary for the taker(s) to get in touch and perform the transaction.

In some sense, both users involved in an exchange can be labeled as both “maker” and “taker” since the order can only be executed when there is a match between two “maker” offers expressed in the same pair (but in the opposite direction) and which are consistent in terms of amount and price range.

There is an expiration time when the offer is no longer considered valid in terms of Bitcoin block height, and the wallet will reject any match proposed by other nodes.

Some orders are dropped by the nodes who created them, while others are closed because the swap has already been finalized. To notify peers of closed or canceled orders, it is necessary to prove these orders’ ownership by signing a message with the private key connected to the original order creator. Nodes also notify their peers by relaying messages about closed orders.

Two additional parameters are introduced to increase the chances of having a match between maker and taker, both freely configurable by the user:

1. multipartySwap: it is expected that the amount of tokens requested for the swap is not easily matched in the market with an equal and opposite order expressed in the same pairs. Therefore, it might be necessary to split the amount into smaller orders performed by different users in a “multi-party swap” to fulfill an order. For example, the maker can send 0.4 BTC to user1, 0.2 BTC to user2, and 0.4 BTC to user3, creating three different swaps. The trade-off in the case of atomic swaps (but not lightning swaps) is that several exchange transactions require more fees to be paid on-chain, and users are not willing to create so much dust. Therefore, the maker can introduce a threshold in the number of tokens exchanged in the atomic swap, under which any exchange request would be rejected. If the parameter is set equal to valueA, the maker intends to perform a single atomic swap and exchange the entire amount of tokenA. If the parameter is different, it represents an arbitrary value equal to or below half of the valueA, which indicates the minimum amount accepted for every single swap with other users. The lower the parameter is set, the higher the chances of finding a match, but fees and dust increase. On the other hand, if the parameter is high, failure is probable in finalizing the order (i.e., only a few orders find a match and execute).

2. priceRange: indicates the deviation from the actual price in the offer that the maker might accept. For example, if tokenA is BTC, and tokenB is S-USD, and the ratio between valueA and valueB is 1/10.000, then a 1% priceRange means that the maker is willing to accept a swap transaction for any amount of S-USD that is higher than 9,900 S-USD in exchange for a single BTC. By default, each node accepts whatever more favorable price ratio, so the priceRange deviation is calculated only for higher tokenA/tokenB ratios than what is indicated by the maker (which is usually the price suggested by the wallet). Accepting a slight variability in price levels makes it much more likely to find a match on the DEX but may also imply less advantageous trades. By default, the wallet picks up the most favorable price among the matches.

A swap transaction is necessarily bilateral, meaning that both involved users must be online and agree on the exact amount of tokens that shall be exchanged. This could cause issues since it is unlikely to find an exact match between maker and taker at precisely the same moment. In case of low liquidity of a specific asset, users might be unsure about the possibility of finalizing a big order for its entire amount, so it shall be split into many different swaps. Therefore users may choose between different configurations of their node. A standard configuration might allow a swap to be automatically initiated with the first user available for whatever amount equal to or greater than the amount indicated in the multipartySwap parameter.

Otherwise, a user may decide that no swap shall ever be initiated unless there are enough matches to close the entire order and the corresponding users are all online at a specific moment. Users may be considered online when they positively confirm the reception of a message at the end of some time interval. This option minimizes the possibility of starting a multi-party swap without finalizing it. The trade-off is that it may also slow down the process or end up with the exchange transaction stuck at the very beginning.

A solution in the middle is that even if nodes have not checked if counterparties are available to initiate a swap, it is enough to check that there are enough matches in the market to finalize the order for its entire amount because there are enough corresponding non-expired and non-closed ordered packages.

In the presence of multiple available offers, wallets will choose the ones closest to the amount requested and at the most favorable price to reduce the number of swap transactions required and reduce the spread paid on the exchange rate.

Carrying out the reconciliation process between offer and demand without a centralized order book is challenging. Luckily, there are good market incentives for professional operators to intervene in this mechanism as takers, capturing most of the users’ offers in the market, as described in §5.5.

Footnotes/p5.3

19. It is freely inspired by 0x open protocol from the Ethereum network https://0x.org/pdfs/0x_white_paper.pdf