Website: zks.org
Contact: dev@l2lab.org
Version: 1.23
Update Date: 2020–11–28
The design spec describes ZKSwap protocol and the difference with ZKSync. Thanks a lot to ZKSync, which provides the ZK Rollup framework for ERC20 token transfer. ZKSwap is an L2 token swap protocol using ZK Rollup on Ethereum and based on the PlonK proof system.
1. Swap Protocol
The swap protocol is the same as Uniswap, but the swap path is limited to 1. That’s the say. Only one token can be swapped to another token if only if the pair for those two tokens is created.
2. Account and Pair Account
The whole L2 state is represented by one Merkle tree, which is leveled by Account and Token. The height of the Account Merkle tree is ACCOUNT_MERKLE_DEPTH, and the height of the Token Merkle tree is TOKEN_MERKLE_DEPTH.
The Account node includes the following fields:
The Token0 ID, Token1 ID, Reserve0, Reserve1, LP token ID, and LP Total Amount fields are added for swap related operation, comparing with zkSync’s Account.
ZKSwap protocol supports two accounts type: one is Account, and the other is Pair Account. For Account, the additional information is useless and empty. For Pair Account, the additional fields should be filled correctly, and the PubKeyHash field is fixed to zero.
3. Token Management
ZKSwap smart contract helps maintain one list of tokens. And the list is divided into two parts: one is for normal ETH/ERC20 tokens, and the other is for LP ERC20 tokens.
a. Normal ERC20 token
Totally, 128 ERC20 tokens are supported with an index from 0 to 127. Index 0 is reserved for ETH.
b. LP ERC20 token
Totally, 2048–128=1920 LP ERC20 tokens are supported, and LP ERC20 token starts from index 128.
In Layer2, each token is assigned one ID. The ID is synchronized between L1 and L2 through ZK-Rollup transactions.
4. Swap Operations
Totally there are four swap related operations. CreatePair helps create swap pairs, which are composed of two different tokens. AddLiquidity and RemoveLiquidity operations help add and remove liquidity. Swap operation is used to swap one token to the other token.
a. CreatePair
CreatePair operation starts from the L1 transaction. The ZKSwap smart contract helps create one pair of ERC20 smart contracts and one associated LP token. The pair ERC20 smart contract address is used in L2 to identify the swap pair. And the LP token address is used in L2 binding with LP token ID.
b. AddLiquidity
When one pair is created, one user can add liquidity to the pair by providing two specified assets. The AddLiqudity starts from L2.
By adding liquidity, one account is rewarded with liquidity tokens. Even the liquidity token is maintained in L2; one liquidity token can be withdrawn to L1.
c. RemoveLiquidity
Remove liquidity can be used to remove specified tokens from one pair. The RemoveLiquidity starts from L2, which is opposite to AddLiquidity.
d. Swap
Swap is used to swap one token for another token, which provides one pair account. From one pair account, the swap ratio depends on the balances of two specified tokens.
5. Circuit Design
The world state of L2 is executed by transactions and verified again by the circuit. When one tx is applied on the circuit, it is “divided” into OperationBranch and Operation Arguments. OperationBranch describes the Merkel path. And Operation Arguments describes all other information besides branches.
Operation is one important structure, which is the “smallest” circuit block.
One logic transaction is split into several operations. And one block can support dynamically different operation numbers:
5.a CreatePair
CreatePair circuit tries to create one pair account with specified tokens information.
5.b AddLiquidity
5.c RemoveLiquidity
The RemoveLiquidity is the reverse operation of AddLiquidity.
5.d Swap
6. Fee Model
No other fee for the ZKSwap protocol, except for the swap operation.
7. Exodus Mode
If the L1 request is NOT handled in 3 days, the ZKSwap protocol enters exodus mode. If the mode is on, users can and should provide proof of assets on L2 and withdraw from L1.
Basically, there are two kinds of assets from the exodus mode point of view: one is a normal ERC20 token, and the other is liquidity tokens in one pair.
a. Normal ERC20 Token
For normal ERC20 tokens, one Merkle path should be verified with the latest Merkle root.
b. Liquidity Tokens
For liquidity tokens, more Merkle paths should be provided. The information of one specified pair should be correct. And the LP token of one account is correct.
ZKSwap Official Website: https://zks.org/en
ZKSwap APP: https://zkswap.app
ZKSwap Twitter: https://twitter.com/ZKSwapOfficial
ZKSwap Discord: https://discord.gg/ZRxS8fYTDv
ZKSwap Github page: https://github.com/l2labs
ZKSwap Official Telegram group: https://t.me/zkswapofficial
