The Coinswap module implements a token exchange protocol based on the Constant Product Market Maker model within the IRISnet ecosystem. It enables fully on-chain, automated swaps between IRIS and other tokens, as well as between different tokens, leveraging the network's robust multi-asset management capabilities.
This system relies on liquidity providers who deposit assets into liquidity pools. The exchange rate between tokens fluctuates based on real-time on-chain trading activity. Arbitrageurs help align these rates with broader market prices, ensuring the system remains efficient and responsive.
A small fee (0.3%) is charged on every swap. This fee is redistributed back into the liquidity pools, serving as a reward for those who provide liquidity. A key feature of this system is that liquidity providers can withdraw their assets at any time without a locking period, offering flexibility and risk mitigation.
Core Concepts
Liquidity Pool
A liquidity pool is a system-controlled, non-custodial account that holds reserves of two assets: typically IRIS and another token. Each token (other than IRIS) has its own dedicated pool to facilitate price discovery. The pool also manages liquidity provider tokens (LPTs), which are fungible tokens representing a share of the pool.
Liquidity
Liquidity refers to the assets deposited into a pool that enable trading. By adding assets, providers contribute to the market's depth. In return for their service, they earn a proportional share of the trading fees generated by the pool.
Liquidity Provider
A liquidity provider can be any individual or entity that deposits an equal value of two assets into a pool. By doing so, they facilitate trading and earn passive income from the accumulated fees.
Constant Product Formula
The protocol uses the constant product formula x * y = k to determine prices algorithmically. Here, x and y represent the reserves of two assets in a pool, and k is a constant. The product k remains unchanged during trades (excluding fees), only shifting when liquidity is added or removed.
How to Use Coinswap
Adding Liquidity
To earn fees, a user must first become a liquidity provider by depositing assets into a pool. The process differs depending on whether a pool already exists.
Creating a New Liquidity Pool
If a pool for a specific token does not yet exist, the first provider must create it. This involves depositing an initial amount of both IRIS and the counterparty token. The ratio of these deposits effectively sets the token's initial price. If this price is misaligned with the external market, arbitrageurs will execute trades to correct it, bringing the on-chain price in line with the market.
Adding to an Existing Pool
If a pool already exists, any new provider must deposit both assets in a ratio that matches the pool's current reserves. The system calculates the required amount of the second token based on the current pool ratio and the amount of the first token being supplied. This mechanism protects providers from immediate arbitrage losses and ensures everyone enters the pool at a fair price.
After a successful deposit, the provider receives liquidity pool tokens (LPTs) representing their share of the total pool. These LPTs are transferable and are used to claim the underlying assets and accrued fees upon withdrawal.
👉 Explore more strategies for providing liquidity
Swapping Tokens
Once a liquidity pool is active, any user can initiate a swap. The protocol charges a 0.3% fee on every trade, which is added to the liquidity reserves. This parameter is governance-upgradable. There are two primary types of swaps:
Buying a Token (Input Fixed)
A user specifies the exact amount of Token A they wish to receive. The protocol then calculates the maximum amount of Token B they must send to facilitate this trade. If the user sends less than this calculated amount, the transaction will fail.
Selling a Token (Output Fixed)
A user specifies the exact amount of Token A they wish to sell. The protocol then calculates the minimum amount of Token B they will receive in return. If the user expects to receive more than this calculated amount, the transaction will fail.
The system also supports direct token-to-token swaps. Internally, this is executed as two consecutive swaps: first from Token A to IRIS, and then from IRIS to Token B. The 0.3% fee is applied to each leg of this transaction.
Removing Liquidity
Liquidity providers can exit their position at any time by returning their LPTokens to the pool contract. In exchange, they receive their original deposited assets, plus their accumulated portion of all trading fees. Upon withdrawal, the provided LPTokens are burned, and the corresponding liquidity is removed from the pool.
Technical Implementation and Access
The Coinswap module is implemented at the protocol level on IRISnet. It is primarily interacted with through RESTful API endpoints, as it does not feature a dedicated command-line interface within the client. Developers can integrate swap functionality directly into their applications or use a reference interface.
For a practical example of a working exchange built on these APIs, you can review the open-source Coinswap Exchange project, which includes detailed usage instructions.
Frequently Asked Questions
What is the Constant Product Market Maker model?
It is an automated market-making algorithm used in decentralized exchanges. It maintains a constant product (k) for the reserves of two assets in a pool (x * y = k), meaning the price of each asset is determined by its available supply within the pool relative to the other asset.
How are swap prices calculated on Coinswap?
Prices are determined algorithmically by the ratio of assets in a liquidity pool. As you swap one token for another, you change the pool's reserves, which in turn changes the price for the next trader. The exact amount received is calculated using the constant product formula, ensuring the product of the reserves remains constant after the trade, minus the fee.
What are the risks of being a liquidity provider?
The primary risk is impermanent loss, which occurs when the price of your deposited assets changes compared to when you deposited them. This divergence means you may incur a loss compared to simply holding the assets. However, this is often offset by the fees earned. The ability to withdraw at any time helps manage this risk.
Can I swap any two tokens on IRISnet?
Yes, you can swap IRIS for any other token that has a liquidity pool. You can also swap between two non-IRIS tokens. The system handles this by routing the swap through the IRIS intermediary pool, which may result in slightly higher fees due to two separate 0.3% charges.
Where do the trading fees go?
The 0.3% fee from every trade is immediately added back to the liquidity pool. This increases the value of the pool and, by extension, the value of each liquidity provider token (LPT). Therefore, when providers withdraw their funds, they receive a share of these accumulated fees.
How do I get started as a liquidity provider?
To provide liquidity, you need to deposit an equal value of two assets into a pool. If a pool doesn't exist, you will create it and set the initial price. If it does, you must deposit assets in the current pool's ratio. You will then receive LPTokens representing your share of the pool.