# XUD raiden Integration
## What do we want to do?
Exchange Union aims to increase liquidity by connecting exchanges and allow trading between these via direct p2p order exchange and settlement of trades via atomic swaps; hence avoiding the need for trust and allow any two exchanges to trade. Today, Exchange Union supports atomic swaps between Bitcoin and Litecoin on the lightning network.

Exchange Union intends to enhance its capability to support atomic swaps between any 2 crypto assets in the long run.

The project priorities are:
1. Atomic swap between Bitcoin to w-ETH
2. Atomic swap between Bitcoin/Litecoin to any ERC20 token
3. Atomic swap between any two ERC20 tokens

The purpose of this document is to share knowledge relevant to the Bitcoin-Litecoin atomic swap, highlight what is missing in the raiden implementation to support above atomic swaps and allow a discussion resulting in an agreed way to implement a raiden-based atomic swap.

## Bitcoin-Litecoin atomic swap (lightning)
Atomic swaps between Bitcoin and Lightcoin are currently handled by XUD in the following way:
1. We have two exchanges: exchange-a (A) and exchange-b (B). Each exchange is connected to the BTC and LTC chains (full nodes)and is running LND for each chain LND-BTC and LND-LTC. Each exchange is running XUD.
2. The exchanges share buy/sell orders between them and trying to find a match. An example of an order can be `buy 13.5 LTC/BTC 0.0080` or `sell 12.5 LTC/BTC market`. These two examples if issued at the same time should yield a trade of 12.5 LTC/BTC at a price of 0.0080. The buyer should send `0.1 BTC` and get in return `12.5 LTC`. The trade should be atomic.
3. The finder of a price match is the "taker" the order issuer is the "maker"
4. Lets assume that B found the price match (B is the taker). It will use the XUD protocol to communicate with A (taker) and agree on the deal. As part of the communication A and B agrees on the amounts and some parameters related to the execution of the trade. B also selects a secret, hashes it and shares the hash with A.
5. Once the deal is agreed, B's XUD sends the BTC amount to A using LND-BTC. It commits the payment of `0.1` BTC to A providing that A knows the secret for the hash. The hash is part of the lightning protocol.
6. Upon receiving the transaction A's LND-BTC does not know the secret so it interfaces with XUD asking if XUD knows the secret for the hash. XUD on A does not know the secret but knows the hash and "remembers" the previously agreed deal with B. XUD on A then sends the 12.5 LTC to B (using LND-LTC) promising to B that if it has the secret it will get these LTC.
7. B's LND-LTC does not know the secret, so it interfaces with B's XUD to check if XUD has the secret. XUD on B has the secret (since it was the creator of the initial payment), so it provides it to B's LND-LTC which in turn provides it to A's LND-LTC and via XUD to A's LND-BTC.
8. Both parties got paid and the trade is done.

Alternatively, check [this visual walk-through](https://github.com/ExchangeUnion/Docs/blob/master/2018-09-01_Berlin_Swap.odp?raw=true) of above described swap.

## Bitcoin-ERC20 atomic swap (Raiden + Lightning)
Basically we would like to implement a similar protocol on raiden to enable a Bitcoin-ERC20 swap. To do this, we would need the following features on a raiden node:

1. The sender raiden node should be allowed to send (as part of the payment-POST api), with a specific hash for this payment.
2. The receiver raiden node, before sending a request to the sender asking to expose the secret should be able to check with an external system (`xud`) if the secret is known. If the secret is known to the external system, the secret should be used and the receiver should not query the sender for the secret. If the secret is unknown, the swap flow continues as described above and the receiver doesn't query the sender for the secret.

## ERC20-ERC20 atomic swap
The same mechanism can be used for ERC20-ERC20 swap. The only requirement is for a raiden node to be able to perform a second payment while in the middle of the first payment.

For example, if A made a payment to B and B is waiting for A to send the secret to B, during that time an app on B should be able to send a payment(different) to A.