Disclaimer: This is a summary of patterns we have observed during our research and should not be considered any form of technical or investment advice. Also, the given “known examples” do not imply they are the best implementations of the said pattern or any superior to any other implementation of the pattern not listed.
Summary
Token swap allows users to trade directly between two types of tokens as an atomic transaction.
Context
A blockchain-based payment application supports different types of tokens, e.g., different asset classes.
Problem
How can users buy and sell tokens for other types of tokens without the risk of other-party not transferring their tokens?
Forces
- Liquidity – Users need to convert tokens to other types of tokens.
- Atomicity – The exchange of tokens should be atomic based on a rate/amount agreed by both parties of the transaction.
- Trust – It is hard for the parties involved in a transaction to trust each other completely.
Solution
By making the token swap atomic, we can ensure both parties will either receive the respective tokens or none of the tokens. A token swap is an agreement between two parties that exchange different token types (say token 𝐴 and token 𝐵). In a token swap, one party will pay a certain amount of token 𝐴 to the other party and receive the agreed amount of token 𝐵 in return. The token swap process is usually managed using a Hashed Timelock Contract (HTLC) deployed on the blockchain. Multiple HTLCs are used to swap tokens in payment channels and across blockchains with the help of an application-layer integrator.
The followingng figure illustrates the steps involved in atomically swapping two tokens using a HTLC. First, a HTLC smart contract is deployed by one of the parties on-chain. HTLC specifies a hash generated from an off-chain secret and a timeout specified as a block number. Second, each party transfers the agreed amount of tokens to the HTLC. For example, party 1 transfers token 𝐴 while party 2 transfers token 𝐵. Next, to swap the tokens, the off-chain secret is sent to the HTLC using a transaction. Finally, if the revealed off-chain secret generates the same hash embedded in the HTLC, the contract exchanges tokens by transferstoken𝐴to party 2 and token 𝐵 to party 1. If the off-chain secret is not revealed before the timeout, tokens are sent back to their owners.
Sequence diagram of token swap
In payment channels and inter-blockchain token swap, two or more intermediate HTLC contacts are deployed, forming a chain of HTLCs. While each HTLC specifies the same hash generated from the off-chain secret, timeout decreases as we move along the HTLC chain. Then the off-chain secret is revealed from the end of the HTLC chain, leading to a chain reaction that enables each HTLC to swap the tokens it holds. In practice, one HTLC does not automatically transfer the off-chain secret to the next HTLC on the chain. Instead, each party interested in receiving tokens locked by a particular HTLC continues to look for a transaction that reveals the off-chain secret. Once it is observed, the off-chain secret is extracted from the transaction and submitted in a new transaction to the respective HTLC to unlock the tokens. The off-chain secret must be revealed to a HTLC before its timeout.
Benefits
- Liquidity – A user can use his/her tokens to buy other types of tokens, increasing liquidity.
- Data Integrity – The data integrity of the swapped tokens can be ensured because the token swap process and respective transactions are stored on-chain.
- Atomicity – Smart contracts guarantee the atomicity of token swap.
- Cost – As smart contracts can manage the token swap process, no third party service fee is incurred, e.g., payment to an escrow.
- Interoperability – Interoperability is increased through cross-chain token swap.
Drawbacks
- Privacy – Token swap transactions are publicly visible.
- Cost – There might be additional cost due to the exchanged rate. Also, if a public blockchain is used, there is a cost to deploy and use HTLC smart contract.
- Lack of flexibility – If a party does not withdraw tokens out in time by submitting the off-chain secret, the deposited tokens will be locked in the HTLC or sent back to the payer.
Related patterns
- When exchanging on-chain assets like tokens, this pattern could be used over the escrow pattern, as no external confirmation of delivery of assets is needed.
- The token registry pattern can be used to send/receive tokens to/from HTLC.
Known uses
- Metamask supports token swap feature to compare and swap tokens directly within the wallet and browsers.
- Kaileido offers a simple process to swap tokens using HTLCs securely.
- The Bitcoin Lightning Network supports multi-hop payment channels by linking existing payment channels through a chain of HTLCs. This enables parties to transact beyond their payment channel.
- AirSwap supports atomic token swap with a guaranteed price. It also supports swap via Metamask wallet and custom swaps with parties trading tokens.
