From a88775e5384cb33b4e291b47510a027203c85292 Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:07:19 +0200 Subject: [PATCH 1/8] Pairs to orderbooks + banlist added Changed node's pairs to orderbooks in nodestate and adding delay to it. Added banlist to nodestate. --- 02-peer-protocol.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index cc224b5..aa89358 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -151,7 +151,7 @@ The `Nodes` message is used to respond to the `GetNodes` message. `NodeState node_state = 2` The updated node state. -The `NodeStateUpdate` message is used to tell a peer about a change in the node state. An example of an update is the removal or addition of a supported trading pair. +The `NodeStateUpdate` message is used to tell a peer about a change in the node state. An example of an update is the removal or addition of a supported trading pair. Fields where isn't any changes are empty. ## Custom types @@ -160,8 +160,8 @@ The `NodeStateUpdate` message is used to tell a peer about a change in the node `repeated Address addresses = 1` The sender's listening TCP addresses - `repeated string pairs = 2` - The sender's list of trading pair symbols, constructed with the base currency first, followed by a '/' separator and the quote currency (e.g., [“LTC/BTC”, “DAI/BTC”]) + `repeated string orderbooks = 2` + The sender's list of orderbook symbols and delays, constructed with the base currency first, followed by a '/' separator and the quote currency, second '/' separator and the delay. (e.g., [“LTC/BTC/0”, “DAI/BTC/2”]) `string raiden_address = 3` The sender's Raiden address @@ -175,6 +175,10 @@ The `NodeStateUpdate` message is used to tell a peer about a change in the node `map lnd_uris = 6` Mapping between currency symbols to LND listening URIs (e.g., { BTC: ['localhost:30000'], LTC: '['localhost:30030', 'localhost:30031']' }) + `repeated string ban_list = 7` + If node don't want to trade with some nodes, he can add them to banlist. Matcher + shouldn't match orders of nodes that are in banlist of each other. + ### Address type `string host = 1` @@ -192,3 +196,4 @@ The `NodeStateUpdate` message is used to tell a peer about a change in the node `repeated Address addresses = 2` The node's listening TCP addresses + From 77cfe63356999f478e686617bb984e344f46a5fd Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:17:51 +0200 Subject: [PATCH 2/8] Added ordertypes + changes to descriptions. --- 03-trade-protocol.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/03-trade-protocol.md b/03-trade-protocol.md index a9f7bb0..9da2a9f 100644 --- a/03-trade-protocol.md +++ b/03-trade-protocol.md @@ -2,13 +2,11 @@ ## 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 **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 may broadcasted to higher delay matcher. * The **Taker**: issues an order which can immediately be matched with an existing (maker) order in the order book. ## Order Type @@ -17,7 +15,7 @@ Similarly, we distinguish between these two types of participants in a trade on 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”) + A trading pair symbol, constructed with the base currency first, followed by a '/' separator and the quote currency, followed by '/' separator and orderbook delay (e.g., “LTC/BTC/2”) `double price = 3` The price for the order expressed in units of the quote currency @@ -27,6 +25,24 @@ Similarly, we distinguish between these two types of participants in a trade on `bool is_buy = 5` Whether the order is a buy (true) or a sell (false) + + `string order_type = 6` + Type is market, limit or post_only + + `string trigger_price = 7` + Order won't be placed to orderbook before trigger price is reached. If order doesn't have trigger price, this can be empty. After trigger price there is separator '/' and 'over' or 'under'. + + +### Order Types +Market order: +Market order will be matched immediatly. + +Limit order: +Limit orders are used to specify a maximum or minimum price the trader is willing to buy or sell at. + +Post only order: +Order will be placed to orderbook only if it won't be matched immediatly. If order could be matched immediatly, it not either will be matched. + ## Trade Protocol ### Order Message (0x06) @@ -37,7 +53,10 @@ Similarly, we distinguish between these two types of participants in a trade on `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. + `orderbook id = 3` + Orderbook where you want to place order + +The `Order` message is used to tell a matcher about a new order. It should only be sent to matcher after the order (or part of the order) could not be matched in the local order book. ### OrderInvalidation Message (0x07) @@ -53,7 +72,7 @@ The `Order` message is used to tell a peer about a new maker order. It should on `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 `OrderInvalidation` message is used to tell a matcher about the full or partial invalidation of a previously sent order. It allows the matcher to remove the order from orderbook. Order invalidation is a common event which occurs due to order cancellation or filling (by another order). Failing to send updates about the order will result in peers having a stale order in their orderbooks. These matcher 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) From 7265b65661ca83522092df8a7a321acc6086764e Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:23:45 +0200 Subject: [PATCH 3/8] Update 04-swap-protocol.md --- 04-swap-protocol.md | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/04-swap-protocol.md b/04-swap-protocol.md index 15a37a2..278fc84 100644 --- a/04-swap-protocol.md +++ b/04-swap-protocol.md @@ -4,20 +4,21 @@ Once an order match is found in the taker’s order book, the swap protocol should be initiated. The current swap protocol assumes that the taker and maker are connected via a payment channel network (e.g. the [Lightning](http://lightning.network/) or [Raiden Network](https://raiden.network/)) with sufficient balance available for the swap. The following is the swap protocol's "happy" flow: -1. Taker finds a match, e.g. buying 1 BTC for 10k DAI -2. Taker creates the private `r_preimage` and the public `r_hash` for the atomic swap -3. Taker sends the `SwapRequest` message to the maker, which includes `r_hash` -4. Maker confirms full or partial quantity in the `SwapAccepted` message -5. Taker starts the swap by dispatching the first-leg HTLCs on the DAI payment channel to the maker end, using `r_hash` -6. Maker is listening for an incoming HTLC on the DAI payment channel. Once it arrives he verifies price and quantity and then dispatches the second-leg HTLCs on the BTC payment channel to the taker end. -7. Taker is listening for an incoming HTLC on the BTC payment channel. Once it arrives he releases `r_preimage`. This allows **both** the taker and the maker payments to finalize. -9. Taker sends the `SwapCompleted` message to the maker +1. Matcher finds a match, e.g. 1 BTC for 10k DAI +2. Matcher sends the `SwapRequest` message to the taker and maker +3. Taker creates the private `r_preimage` and the public `r_hash` for the atomic swap +4. Taker sends the `SwapAccepted` message to the maker and matcher, which includes `r_hash`. Or if he unaccept trade he send swapFailed +5. Maker sends `SwapAccepted` message to matcher and taker. +6. Taker starts the swap by dispatching the first-leg HTLCs on the DAI payment channel to the maker end, using `r_hash` +7. Maker is listening for an incoming HTLC on the DAI payment channel. Once it arrives he verifies price and quantity and then dispatches the second-leg HTLCs on the BTC payment channel to the taker end. +8. Taker is listening for an incoming HTLC on the BTC payment channel. Once it arrives he releases `r_preimage`. This allows **both** the taker and the maker payments to finalize. +9. Taker sends the `SwapCompleted` message to the maker and matcher Possible misbehaviors and their outcome: | Misbehavior | Outcome | Effect on payment channels |-------------------------------------------------------------------------------------|-------------------------------------------------------|------------------------------------------------------------| -| Maker doesn't respond to the `SwapRequest` message | Taker should timeout the swap and penalize the maker | None | +| Owner of order doesn't respond to the `SwapRequest` message from matcher | Swap should be timeouted and matcher and other party of trade should penalize peer that didn't respond | None | | Taker doesn't start the swap after receiving the `SwapAccepted` message | Maker should timeout the swap and penalize the taker | None | | Maker receives the first-leg HTLC with insufficient amount or incorrect CLTV delta | Maker should send the taker a `SwapError` message | Taker funds are locked until HTLC expiration | | Maker doesn't continue the swap after receiving the first-leg HTLC | Taker should timeout the swap and penalize the maker | Taker funds are locked until HTLC expiration | @@ -39,13 +40,9 @@ Possible misbehaviors and their outcome: `string order_id = 4` The unique identifier of the maker order - `string r_hash = 5` - The taker preimage hash (in hex) + - `uint32 taker_cltv_delta = 6` - The CLTV delta from the current height that should be used to set the timelock for the final hop when sending to the taker - -The `SwapRequest` message is sent by the taker to the maker to start the swap negotiation. +The `SwapRequest` message is sent by the matcher to the taker and the maker to start the swap negotiation. ### SwapAccepted Message (0x0d) @@ -62,9 +59,9 @@ The `SwapRequest` message is sent by the taker to the maker to start the swap ne The accepted quantity (which may be less than the proposed quantity) `uint32 maker_cltv_delta = 5` - The CLTV delta from the current height that should be used to set the timelock for the final hop when sending to the maker + The CLTV delta from the current height that should be used to set the timelock for the final hop when sending to the maker. -The `SwapAccepted` message is sent by the maker to the taker to accept the swap request. +The `SwapAccepted` message is sent by either side of the swap protocol to other side and matcher to accept the swap request. ### SwapComplete Message (0x0e) @@ -74,7 +71,7 @@ The `SwapAccepted` message is sent by the maker to the taker to accept the swap `string r_hash = 2` The taker preimage hash (in hex) -The `SwapComplete` message is sent by the taker to the maker to announce the successful completion of the swap. +The `SwapComplete` message is sent by the taker and the maker to each other and matcher to announce the successful completion of the swap ### SwapFailed Message (0x0f) @@ -93,7 +90,7 @@ The `SwapComplete` message is sent by the taker to the maker to announce the suc `uint32 failure_reason = 5` The failure reason -The `SwapFailed` message can be sent by either side of the swap protocol, at any time, to announce the swap termination. +The `SwapFailed` message can be sent by either side of the swap protocol to other side and matcher, at any time, to announce the swap termination. `failure_reason` is an optional parameter for specifying the failure reason: From 840e09f9b291646df813aa3395af5411652740a5 Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:26:15 +0200 Subject: [PATCH 4/8] Create 05-matching-protocol --- 05-matching-protocol | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 05-matching-protocol diff --git a/05-matching-protocol b/05-matching-protocol new file mode 100644 index 0000000..e06eba8 --- /dev/null +++ b/05-matching-protocol @@ -0,0 +1,42 @@ +# BOLD #5: Order Matching Protocol + +## Overview +Node can choose which matcher match its orders. Anyone can be matcher. Matcher runs orderbook and find matches, when match is found, matcher sends `SwapRequest` message to both party of trade. Orderbook has delay time, which define how much time peer have to accept or decline swap request. Delay is expressed in seconds and delay of local orderbook is 0. +Node can give its order to matcher, matcher of that one orderbok can again place order to orderbook with higher delay. And so on... +When Matcher create SwapRequest, matcher send it back to slower delay orderbook until owner of order get it, then owner create response message(SwapAccepter or SwapFailed) and send it to first matcher, which send it to matcher with higher delay until matcher which sended SwapRequest get response. +Matcher can choose not to take orders from some nodes. As an example if swap never or very rarely succeed with some node, matcher can stop taking orders from this node. + +### Matching rules +If there are in orderbook many makers in same price, matcher should match oldest order first. +Matcher shouldn't match orders where each party is in ban list of other party. +Market orders, should be matched with current best price order. +Limit orders have to be matched with right price. +Post only order shouldn't be placed to orderbook or matched if it could be matched immediatly. +Orders with trigger should be placed orderbook when trigger price is reached, not earlier. + +## Overview +Node can subscribe all events on matcher's orderbook, so it can be sure that matcher follow matching rules. Matcher is not required to accept any subscribe reguests, but no one may want to use orderbook that can't be verified of following rules. +Node will broadcast messages below, which applies to orders in this orderbook to everyone who have subscribed orderbook. +1. Order Message (0x06) +2. OrderInvalidation Message (0x07) +3. SwapRequest Message (0x0c) +4. SwapAccepted Message (0x0d) +5. SwapComplete Message (0x0e) +6. SwapFailed Message (0x0f) +7. NodestateUpdate Message(0x02), only changes in banlist of nodes which have used orderbook in last 24 hours. If node that haven't been trading in last 24 hours place order, its banlist should be broadcasted to subscribers. + +When peer start subscribing orderbook next things will be broadcasted: +1. All current orders of orderbook +2. All banlists of nodes that have used orderbook in last 24 hours. +3. Last swap protocol messages of orders that have swap in progress. + +### Subscribe Message (0x) + `string orderbook_id = 1` + Orderbook which you want subscribe. + `state = 2` + If state is 'subscribe', node want start subscribing. If state is 'unsubscribe', node stop subscribing. + +### SubscribeResponse Message(0x) + `orderbook id = 1` + `state = 2` + If state is 'accepted', request to subscribe is accepted. If state is 'unaccepted', request to subscribe is unaccepted, or request to unsubscribe is recieved. From 0cc81d4fcb34471567e85a2d2e522aa077c9d642 Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:27:56 +0200 Subject: [PATCH 5/8] Update SUMMARY.md --- SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/SUMMARY.md b/SUMMARY.md index 466ccc6..893b21d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -8,6 +8,7 @@ * [BOLD #2: Peer Protocol](02-peer-protocol.md) * [BOLD #3: Trade Protocol](03-trade-protocol.md) * [BOLD #4: Swap Protocol](04-swap-protocol.md) +* [BOLD #5: Matching Protocol](03-matching-protocol.md) ## Contribute * [Contribution Guide](Contribute.md) From 1f025b7e9b33971a7cc59afab477c25695e3e3cf Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:28:29 +0200 Subject: [PATCH 6/8] Fixed link to matching protocol --- SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SUMMARY.md b/SUMMARY.md index 893b21d..7c3909b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -8,7 +8,7 @@ * [BOLD #2: Peer Protocol](02-peer-protocol.md) * [BOLD #3: Trade Protocol](03-trade-protocol.md) * [BOLD #4: Swap Protocol](04-swap-protocol.md) -* [BOLD #5: Matching Protocol](03-matching-protocol.md) +* [BOLD #5: Matching Protocol](05-matching-protocol.md) ## Contribute * [Contribution Guide](Contribute.md) From 13c742611aeafb7c3b8cfee4bdca75cc489f70a1 Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:29:26 +0200 Subject: [PATCH 7/8] Fixed name --- 05-matching-protocol => 05-matching-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename 05-matching-protocol => 05-matching-protocol.md (98%) diff --git a/05-matching-protocol b/05-matching-protocol.md similarity index 98% rename from 05-matching-protocol rename to 05-matching-protocol.md index e06eba8..655cf18 100644 --- a/05-matching-protocol +++ b/05-matching-protocol.md @@ -1,4 +1,4 @@ -# BOLD #5: Order Matching Protocol +# BOLD #5: Matching Protocol ## Overview Node can choose which matcher match its orders. Anyone can be matcher. Matcher runs orderbook and find matches, when match is found, matcher sends `SwapRequest` message to both party of trade. Orderbook has delay time, which define how much time peer have to accept or decline swap request. Delay is expressed in seconds and delay of local orderbook is 0. From 9ed596bcb242b9bf926a80f420778e2f1b70553e Mon Sep 17 00:00:00 2001 From: VETTE <46370333+xVETTEx@users.noreply.github.com> Date: Tue, 11 Feb 2020 13:30:42 +0200 Subject: [PATCH 8/8] Matching rules to more clear. --- 05-matching-protocol.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/05-matching-protocol.md b/05-matching-protocol.md index 655cf18..114322d 100644 --- a/05-matching-protocol.md +++ b/05-matching-protocol.md @@ -8,10 +8,15 @@ Matcher can choose not to take orders from some nodes. As an example if swap nev ### Matching rules If there are in orderbook many makers in same price, matcher should match oldest order first. + Matcher shouldn't match orders where each party is in ban list of other party. + Market orders, should be matched with current best price order. + Limit orders have to be matched with right price. + Post only order shouldn't be placed to orderbook or matched if it could be matched immediatly. + Orders with trigger should be placed orderbook when trigger price is reached, not earlier. ## Overview