Atomic Swaps Explained

History of the Technology

Atomic Swaps refer to the techniques that allow tokens from different contracts, which may run on the same or different blockchains, to be securely traded, such that both parties succeed or fail together in getting the offered tokens.

Trading tokens can be easily carried out through a trusted 3rd party such as a centralized exchange. Coinbase is an example of such an exchange. Because centralized exchanges must hold large amount of tokens in order to do efficient market making, they are constantly under the risk of hacking and human mis-management.

Tokens can also be traded directly between the counter-parties without having to rely on a trusted 3rd party. The most critical aspect of carrying out token trades is “atomicity”. If one party fails to fulfill its responsibilities, the trade immediate falls apart and no one gets to keep both tokens. The decentralized exchanges (DEX) are mostly based on this type of techniques, a.k.a Atomic Swaps.

Hashed Time Lock Contract (HTLC)

The technique adopted by Kaleido for trading tokens in an Atomic Swap fashion is called “Hashed Time Lock Contract” (HTLC). It is first pioneered by the Bitcoin community to implement payment channels. The steps involved to carry out an atomic swaps are as follows:

Alice wants to trade 100 A-Tokens with Bob for 50 B-Tokens
Alice generates a random secret and generates its SHA256 hash. Alice gives that hash to Bob.
Alice deposits 100 A-Tokens into the HTLC contract and designate Bob as the beneficiary, the tokens are locked with the hash
Bob responds by depositing 50 B-Tokens into the HTLC and designate Alice as the beneficiary, the tokens are also locked with the same hash Bob has obtained from Alice
Alice has the original secret that was used to produce the hash (called a pre-image), so Alice uses it to call the claim() function on the HTLC contract to claim the trade payment and fully receive the 50 B-Tokens from Bob. By doing so, Alice necessarily reveals the pre-image in the transaction input, which becomes visible to Bob.
Bob uses the pre-image to finalize his payment from Alice

Handling Error Cases

The above is the ideal flow when both parties dutifully fulfilled their part of the deal. However, what if one of the two parties did not like the offer terms and rejected the trade offer? The HTLC contracts have timeout features that allow the token owners to get their tokens back from the contract’s lockbox if the deal fell apart.

Let’s first see the flow if Bob rejected the offer from Alice:

Alice wants to trade 100 A-Tokens with Bob for 50 B-Tokens
Alice generates a random secret and generates its SHA256 hash. Alice gives that hash to Bob.
Alice deposits 100 A-Tokens into the HTLC contract and designate Bob as the beneficiary, the tokens are locked with the hash. Alice also set a timeout of 1 hour on the lock.
Bob only needed 75 A-Tokens, not 100. So he rejected Alice’s offer and did not follow up with a responding offer. After an hour, Alice calls the contract’s refund() function and gets her tokens back

What if Bob responded with a trade offer, but Alice did not like the terms?

Alice wants to trade 100 A-Tokens with Bob for 50 B-Tokens
Alice generates a random secret and generates its SHA256 hash. Alice gives that hash to Bob.
Alice deposits 100 A-Tokens into the HTLC contract and designate Bob as the beneficiary, the tokens are locked with the hash. Alice also set a timeout of 1 hour on the lock.
Bob responds by depositing 30 B-Tokens into the HTLC and designates Alice as the beneficiary. The tokens are also locked with the same hash that Bob has obtained from Alice. Bob sets a timeout of 30 minutes for Alice to call claim().
Alice, seeing that Bob responded with 30 B-Tokens instead of 50, rejected the offer. She refused to call claim() and instead calls refund() after the 1 hour timeout to get her 100 A-Tokens back.
Bob, having never received the secret from Alice, calls refund() after the 30 minutes timeout to get his 30 B-tokens back.