Skip to content

Latest commit

 

History

History
111 lines (79 loc) · 7.58 KB

04-swap-protocol.md

File metadata and controls

111 lines (79 loc) · 7.58 KB

BOLD #4: Swap Protocol

Overview

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 or Raiden Network) with sufficient balance available for the swap. The following is the swap protocol's "happy" flow:

  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
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
Taker receives the second-leg HTLC with insufficient amount or incorrect CLTV delta Taker should sends the maker a SwapError message Both Taker and Maker funds are locked until HTLC expiration
Taker doesn't release r_preimage after receiving the second-leg HTLC Maker should timeout the swap and penalize the taker Both Taker and Maker funds are locked until HTLC expiration
Taker doesn't send the SwapCompleted message after releasing r_preimage None; swap has already finalized None

Swap Protocol

SwapRequest Message (0x0c)

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

`uint64 proposed_quantity = 2`
The proposed quantity

`string pair_id = 3`
The trading pair for the swap

`string order_id = 4`
The unique identifier of the maker order

The SwapRequest message is sent by the matcher to the taker and the maker to start the swap negotiation.

SwapAccepted Message (0x0d)

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

`uint64 req_id = 2`
The id from the received SwapRequest message

`string r_hash = 3`
The taker’s preimage hash (in hex) from the received SwapRequest message

`string quantity = 4`
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 SwapAccepted message is sent by either side of the swap protocol to other side and matcher to accept the swap request.

SwapComplete Message (0x0e)

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

`string r_hash = 2`
The taker preimage hash (in hex)

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)

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

`uint64 req_id = 2`
An optional id from the received SwapRequest message. Otherwise, this field is empty

`string r_hash = 3`
The taker’s preimage hash (in hex)

`string error_message = 4`
Additional information regarding the failure reason

`uint32 failure_reason = 5`
The failure reason

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:

Failure Reason Meaning Description
0x00 Order Not Found Could not find the order specified by a swap request
0x01 Order On Hold The order specified by a swap request is on hold for a different ongoing swap
0x02 Invalid Swap Request The swap request contained invalid data
0x03 Swap Client Not Setup We are not connected to both swap clients, or we are missing public key identifiers for the peer's nodes
0x04 No Route Found Could not find a route to complete the swap
0x05 Unexpected Client Error A swap client call failed for an unexpected reason
0x06 Invalid Swap Message Received Received a swap message with invalid data
0x07 Send Payment Failure The call to send payment failed
0x08 Invalid Resolve Request The swap resolver request was invalid
0x09 Payment Hash Reuse The swap request attempts to reuse a payment hash
0x0a Swap Timed Out The swap timed out while we were waiting for it to complete execution
0x0b Deal Timed Out The deal timed out while we were waiting for the peer to respond to our swap request
0x0c Unknown Error The swap failed due to an unrecognized error