# Deal Statuses and Swap protocol ~~V2~~ V3

## Swap protocol V1
The current implementation of the XUD swap protocol involves the exchange of four P2P packets:
1. `dealRequest` - From taker to maker. Includes deal information like amounts, currencies, taker pubkey, dealid, and orderid. This message notifies the maker that the taker wants to take its order and exchange the funds via a swap.
2. `dealResponse` - from maker to taker. This message is a confirmation by the maker. The most important data that is included in this message is the `r_hash` which will later be used by the maker `hash-resolver` to find the right deal in the deals data structure.
3. `swapRequest` - from taker to maker. This is a confirmation that the taker is ready (got the `r_hash`) and that the maker can start the swap.
4. `swapResponse` - from maker to taker. Once the swap is over the maker is sending back to the taker the `r_preImage`

Between step 3 and 4 above the actual swap happens. This involves the following:
* (a) The maker is sending his amount with the agreed r_hash via sendPaymentSync and wait(blocking) for a response
* (b) The taker's resolver is being called by LND to resolve the r_hash
* (c) The taker is sending his amount with the agreed r_hash via sendPayment and wait(blocking) for a response
* (d) The maker's resolver is being called by LND to resolve the r_hash
* (e) The maker send back the r_preimage. At this point, the maker got his amount.
* (f) the taker wakes up (c) with the preimage and send it back to the maker. At the point, the taker got his amount
* (g) the maker wakes up (a) and the swap is done

## Issues with the current protocol
1. No proper error handling - Current implementation is not robust with regards to errors. For example, there is no way for the maker to reject the deal in case the swap was already done with another peer.
2. No deal status - adding a deal status to the deal object (data structure) assists in verifying that the protocol is working as planned (verify pre-status before setting a new one) and ease the analysis in case of swap problems. Moreover, deal status can help to define when we should emit an event to impact other components of the system.
3. No way to view the deal data structure
4. deal data structure is not stored in the database
5. The protocol is not efficient. Number of P2P packets can be reduced to allow the swap to start faster

### Deal Status (V1 protocol)
I would like to suggest the implementation of the following deal status (as part of the deal structure):
1. `dealRequested` - on taker's side only. Set when sending `dealRequest` message. Prior status `NA` (no deal)
2. `dealAgreed` - on maker's side only. Set when sending `dealResponse` message. Prior status `NA`
3. `swapRequested` - on taker's side only. Set when sending `swapRequest` message. Prior status `dealRequested`
4. `amountSent` - set when sending amounts with `sendPaymentSync`. Prior status `dealAgreed` when maker and `swapRequested` when taker
5. `preImagerevealed` - set when providing the preImage to LND. Prior status should be `amountSent` (both maker and taker)
6. `swapDone` - set by maker when getting a response from `sendPaymentSync` which includes the preImage. Prior status should be `preImagerevealed`. Set by taker when getting from maker the `swapResponse` message with the preImage.

### Swap protocol V2
Swap version 2 reduces the need for `swapRequest` message from the taker to the maker and allows the actual swap to start sooner. To do that the following changes take place:
1. The r_hash and the r_preImage are set by the taker and not by the maker.
2. The taker sends to the maker a`swapRequest` message which includes the r_hash.
3. The maker confirms with `swapResponse` message
4. The taker initiates the swap
5. upon success the taker issue a `swapResponse` message (to be renamed to `swapConmpleted`) to the maker.

#### Impact on Deal Status
1. `swapRequested` **status is not needed**
2. `amountSent` - set when sending amounts with `sendPaymentSync`. Prior status `dealAgreed` when maker and `dealRequested` when taker
3. `swapDone` - set by taker when getting a response from `sendPaymentSync` which includes the preImage. Prior status should be `preImagerevealed`. Set by maker when getting from maker the `swapResponse` message with the preImage.

### Swap protocol V3
Swap version 3 reduces the need for `dealResponse` (maker to taker) and `swapRequest` (taker to maker) messages and allows the actual swap to start very fast. To do that the following changes take place:
1. The r_hash and the r_preImage are set by the maker when adding the order to the maker's order book.
2. **The r_hash is provided to all peers together with the peerOrder**. This way, when the taker wants to take a deal it already knows the r_hash.
3. The taker sends to the maker a`swapRequest` message.
4. The maker initiates the swap
6. upon success the maker issue a `swapResponse` message (to be renamed to `swapConmpleted`) to the taker.

#### Impact on Deal Status
1. `dealAgreed` **status is not needed**
2. `swapRequested` **status is not needed**
3. `amountSent` - set when sending amounts with `sendPaymentSync`. Prior status `NA` when maker and `dealRequested` when taker

#### V3 happy flow status change simulation
1. taker change status from NA to `dealResuested` when sending `dealRequest` to the maker.
2. maker change status from NA to `amountSent` when calling `sendPaymentSync`
3. taker change status from `dealRequested` to `amountSent` when calling `sendPaymentSync`
4. maker change status from `amountSent` to `preImagerevealed` when providing the preImage to LND
5. taker change status from 'amountSent' to `preImagerevealed` when providing the preImage to LND
6. maker change status from `preImagerevealed` to `swapDone` when getting the preImage response from `sendPaymentSync`
7. taker change status from `preImagerevealed` to `swapDone` when getting from maker the `swapCompleted` message

### Error handling and Error state (V3)
Errors may occur during the protocol execution. Errors can be classified as `rejection`, `execution problems` and `protocol errors`. For now, we will refer to all these as `errors`.

Once we face an error we flag the deal with an error state. The state together with the status can help us to understand where/when we got the error. We will also add an `errorReason`.

How can we get an error:
1. during logic execution, if one of our validation checks fails we mark the deal as Error and send a `dealError` message to the peer. Example: when the taker sends a `dealRequest` message and we fail to find the order in our book.
2. When we get an error from LND we mark the deal as Error and send `dealError` to the peer. Examples: not having the amount to send, no route to LND peer, unknown hash", etc.
3. When we get from a peer a `dealError` message.
4. Connection with peer terminated during the swap protocol
5. Operation timeout

It should be noted that once the deal has a status of `preImagerevealed` that deal should be considered successful even if we received an error. Once we revealed the preImage we got our payment and we need to help the peer to get his.