OIP-3: Token Swap

Author William Liu(@OKExChain)
Status Draft
Type Standard Track
Category Core
Created 2020-5-12

1. Summary

This OIP is about introducing on-chain market maker and further mechanism to swap tokens immediately without matching procedure on-chain.

2. Abstract­

Uniswap has been used for swap tokens for a few years on Ethereum. This OIP defines native transactions to support uniswap feature on OKExChain, and also proposes the basic DeFi infrastructure and procedure to use on-chain market maker for different OIP2 token swap feature.

3. Status

This OIP is under implementation.

4. Motivation

OKExChain has a high efficiency asset Exchange processing by Dex module. However, there are major cases cannot satisfied by Dex itself:

  1. Assets market maker serve as liquidity provider there is a cost for Dex.

  2. Assets orders handle cost a lot compute and storage resources on-chain.

For more options market maker can choose to have benefits on OKExChain. One can add liquidity on OKExChain to reap the benefits and swap tokens without wait. Many new requirements are imposed for such model:

  1. Listing token should on low fees.

  2. There should be an easy way for users to swap token immediately.

  3. There should generate a pool token for users who add liquidity on it, and keep pool token normal on OIP2 standards.

The OIP is to conclude above target, the standard infrastructure and procedure proposed to empower the DeFi with OKExChain.

5. Specification

5.1 Roles

  • Client: users who want to swap different tokens

  • Market maker: users who add liquidity on one OIP2 token pool. In most cases, anyone can add liquidity in any token pair pool to reap the benefits. Meanwhile, the user will get pool token which generated by the module according to the ratio of deposited assets to the pool.

5.2 Swap Token Pair Properties

  • QuotePooledCoin: QuotePooledCoin is the token pair pool mortgage quote assets name and value, mostly is the native token.

  • BasePooledCoin: BasePooledCoin is the token pair pool mortgage base assets name and value.

  • PoolTokenName: PoolTokenName represents the name of generated pool token name - e.g.”oip3-xxb-91f”.

5.3 Swap Tokens Management Operation

5.3.1 Create Exchange

Create Exchange is to create new token pair and associate with assets pool on OKExChain. The new assets pool mortgage assets and charge to the token pair account.

Message Structure for Create Exchange: A data structure is needed to represent the create exchange operation:

Field Type Description
Token string Name of the newly token pair exchange, limited to 32 unicode characters, the constraint limited by OIP2 token name,only allowed for those tokens already exist on OKExChain.

Pool Token Symbol Convention:

OIP3-Symbol

Explanations: There should be an additional preffix of “OIP3”. It helps to distinguish the constraint of requiring unique token names.

Create Exchange Process:

  • Initiators of Exchange creation sign a create exchange transaction and make it broadcasted to one of OKExChain nodes

  • This OKChian node will check this transaction. If there is no error, then this transaction will be broadcasted to other OKExChain nodes

  • Create exchange transaction is committed on the blockchain by block proposer

  • Validators will verify the constraints on token name and deduct the fee from the transaction initiator’s address

New pool token is generated based on the OIP3-Symbol. Token pairs info is saved on the OKExChain.

5.3.2 Add Liquidity

Add Liquidity transaction is to send tokens from market maker’s addresses to module addresses. Meanwhile, associated token pair pool increased.

Message Structure for Add Liquidity Operation: A message structure is needed to represent the Add Liquidity operation.

Field Type Description
MinLiquidity Dec Minimum number of sender will mint if total pool token supply is greater than 0.
MaxBaseAmount Coin Maximum number of tokens deposited. Deposits max amount if total pool token supply is 0.
QuoteAmount Coin The number of native token deposited.
DeadlineDuration int64 Deadline Time after which this transaction can no longer be executed. such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h"."
From Address Address for token holders

Add Liquidity Process:

  • Market Makers sign an Add Liquidity transaction and make it broadcasted to one of OKExChain nodes

  • The OKExChain node will check this transaction. If there is no error, then this transaction will be broadcasted to other OKExChain nodes

  • Add Liquidity transaction is committed on the blockchain by block proposer

  • Validators will verify the constraints on balance. The transfer tokens and fee will be deducted from the address of the transaction initiator

  • Add the tokens to the module account address. Mint pool token with the amount of Ratio of total pool assets and add to the Market Makers addresses and token pair info is updated on the OKExChain

5.3.3 Remove Liquidity

Remove Liquidity transaction is to send pool tokens from market makers addresses to module addresses. Meanwhile, associated token pair pool is reduced.

Message Structure for Remove Liquidity Operation: A message structure is needed to represent the Remove Liquidity operation.

Field Type Description
Liquidity Coin The number of pool tokens sender will burn.
MinBaseAmount Coin Minimum base tokens withdrawn.
MinQuoteAmount Coin Minimum quote tokens withdrawn.
DeadlineDuration int64 Deadline Time after which this transaction can no longer be executed. such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h"."
From Address Address for token holders

Remove Liquidity Process:

  • Market Makers sign a Remove Liquidity transaction and make it broadcasted to one of OKExChain nodes

  • The OKExChain node will check this transaction. If there is no error, then this transaction will be broadcasted to other OKExChain nodes

  • Remove Liquidity transaction is committed on the blockchain by block proposer

  • Validators will verify the constraints on balance. The transfer tokens and fee will be deducted from the address of transaction initiator

  • Burned pool token are deducted from the address of the token owner. Add the tokens amount is Ratio of total pool assets to the Market Makers addresses and token pairs info is updated on the OKExChain

5.3.4 Swap Token

Swap Token transaction is exchange one kind of token to another.

Message Structure for Swap Token Operation: A message structure is needed to represent the Swap Token operation.

Field Type Description
SoldTokenAmount Coin The amount of tokens sold.
MinBoughtTokenAmount Coin Minimum tokens bought.
DeadlineDuration int64 Deadline Time after which this transaction can no longer be executed. such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h"."
Recipient Address Address for token receiver
From Address Address for token holders

Swap Token Process:

  • Address-holder sign a swap token transaction and make it broadcasted to one of OKExChain nodes

  • The OKExChain node will check this transaction. If there is no error, then this transaction will be broadcasted to other OKExChain nodes

  • Swap token transaction is committed on the blockchain by block proposer

  • Validators will verify the constraints on balance. The sold tokens and fee will be deducted from the address of transaction initiator

  • Add the bought tokens to the transaction initiator’s address or recipient address if it’s accomplished.

6. License

The content is licensed under CC0.