Telos Swaps v3 technical primer
Background
T-Swaps will be migrating to version 3 over the next week. The migration involved a complete user interface rewrite and a major reorganization of the platform contracts. Version 2 will be decommissioned and liquidity moved to version 3 as part of the migration.
What changes?
Self listing of token pairs
A major shortcoming in the implementation of T-Swaps version 2 was the need to deploy separate contracts for each pair added to the platform. This made it impossible to create user tooling needed to allow projects to self list token pairs.
T-Swaps version 3 has been rewritten to work with a single multi-token contract. This allows us to now support self listing of token pairs.
Liquidity tokens
All liquidity pool tokens issued by the platform will now be issued from a single LP token contract. The LP token contract is the standard eosio.token contract with extensions to track profit and loss on deposits / withdrawals of LP tokens.
The liquidity token tickers are composed using a “SP” prefix plus sequential letters signifying the pair id they are issued against (SPA for pair 1, SPB for pair 2, …).
Any liquidity held in T-Swaps version 2 will be migrated to version 3 as part of this migration. Current liquidity providers need not remove liquidity from T-Swaps version 2 ahead of the migration.
Platform contracts
- amm.swaps: Multi-pair swap contract based on Uniswap and Curve algorithms
- swap.swaps: eosio.token contract used for SWAP tokens
- lptkns.swaps: Liquidity tokens
- reward.swaps: SWAP token trading rewards system
- stats.swaps: On-chain record swap trade data
Swap memo format
T-Swap token conversions are routed based on a routing memo. Version 2 used a routing memo based on the standard implemented by Bancor (version 1) on EOS. This memo format is replaced by the following in T-Swaps v3:
swap,<minimum return>,<routing>
Where
- swap: command
- minimum return: the minimum number of tokens allowed as a result of the swap operation. If the swap yields fewer tokens than this value the conversion is aborted. Note that this amount should be specified using the receiving token’s precision and without the decimal point. For example, if the minimum return is 1.001 TLOS, it should be expressed as “10010” in the memo.
- routing: A “-” separated list of pairs needed to convert between tokens. For example, if pair 1 is a A:B pair and pair 2 is a B:C pair, the routing between token A and C is “1–2”.
How to
How to swap tokens
Token pairs listed on the T-Swaps platform are stored in the amm.swaps::pairs table. Pairs are identified by “id” in the routing memo.
As an example, assume;
- Pair 1 : TLOS : SWAP
- Pair 2 : TLOS : PUSDT
- Pair 3 : PUSDT : PUSDC
Routing memos;
- SWAP to TLOS : 1
- TLOS to PUSDT : 1–2 (SWAP -> TLOS -> PUSDT)
- PUSDT to PUSDC : 1–2–3 (SWAP -> TLOS -> PUSDT -> PUSDC)
To convert 1.0000 SWAP to PUSDC, transfer SWAP;
- From : user account
- To : amm.swaps
- Quantity : 1.0000 SWAP
- Memo : swap,0,1–2–3
Note: In this example the minimum return is set to 0 PUSDC. Use the expected swap result allowing for slippage if swap result protection is required.
How to add liquidity
Using the pairs defined above, liquidity can be added to pair to pair 2 by;
- Transfer TLOS to amm.swaps with memo “deposit,2”
- Transfer PUSDT to amm.swaps with memo “deposit,2”
- Call the amm:swaps::deposit action with data [“<user account>”,2,null]
- TLOS and PUSDT will be added to the pair without changing the current price.
- SPB liquidity pool tokens are issued against the TLOS : PUSDT added to the pair.
- If the amounts on TLOS and PUSDT deposited do not match the amounts needed to maintain the ruling swap price, only tokens needed to maintain the price are added as liquidity. Surplus tokens are returned to the user.
How to remove liquidity
A transfer memo is not used when withdrawing liquidity. Simply send LP tokens to amm.swaps. The swap contract will burn the LP tokens received and return the pool tokens represented by those LP tokens to the sender of LP tokens.
