[PROPOSAL #38][ACCEPTED] Proposal to Adopt the Liquidity Module onto the Cosmos Hub

Hi Cosmonauts!

This document is the draft signal proposal to adopt the Liquidity Module(DeX) onto the Cosmos Hub. Please share the valuable thoughts and suggestions about the Liquidity Module!

The proposal will be submitted to the Cosmos Hub after two weeks(25th Feb) from today.

Thank you!

Proposal to Adopt the Liquidity Module onto the Cosmos Hub

Summary: Tendermint (https://tendermint.com) and B-Harvest (https://bharvest.io) have joined forces to produce and develop a Liquidity Module (GitHub - tendermint/liquidity: Cosmos SDK Liquidity module). This signal proposal is a Request For Comment to the ATOM community regarding the addition of this Liquidity Module into the Cosmos Hub source code.

By voting YES to this proposal, you will signal that you approve of having a DEX based on this specific Liquidity Module deployed on the Cosmos Hub.

2020: The Year of DeFi

For the crypto community, 2020 has been the year of DeFi. Websites like DeFi Pulse have recorded a transition from centralized, custodial exchanges onto DEXs like Uniswap. In September of last year, trading volume on Uniswap surpassed the trading volume on Coinbase for the first time. Throughout 2020, the total value locked (TVL) in Ethereum DeFi apps has risen from USD 0.7B to USD 23B.

How do we bring this activity to Cosmos? Our proposed solution is to do that through the Cosmos Hub, that will act as an Interchain router.

Cosmos & DeFi

In Cosmos, a diverse developer community has used the Cosmos SDK to build projects that currently secure over USD 22 billion in digital assets. A large number of these projects provide DeFi services. Gravity Bridge, by Althea, plans on bringing an ETH peg directly to the Cosmos Hub. Sovereign chains like Terra and Kava are providing IBC stable coins and synthetic assets. Ethermint is a fully compatible chain with Ethereum web3 tooling and allows developers to port Solidity contracts. Persistence is working on delivering asset-based lending assets to the interchain.

With Proposition 37, ATOM holders have voted to upgrade to Stargate, fulfilling the original Cosmos whitepaper from 2017. In the next proposal, ATOM holders will vote to enable IBC transfers. This proposition will allow native tokens to be transferred to and from IBC-compatible blockchains, fulfilling the promise of the internet of blockchains.

Why the Hub needs a DEX

For the Cosmos Hub to function as an interchain router, it needs to create incentives for users to transfer tokens. The most direct way is for the Hub to create liquidity for the greater interchain economy. Token holders need a trusted way to discover the prices of tokens, exchange tokens, and generate liquidity via pools. We think these services belong to the Hub. By adopting this DEX, ATOM holders will lay down the first, “sine qua non” component of a Hub-centric interoperable financial ecosystem that will provide all stakeholders with innumerable exciting opportunities.

What is the “Liquidity Module”?

The Liquidity Module is a new Cosmos SDK module that allows the implementation of a token DEX on any Cosmos SDK based network. It will enable any user to create a liquidity pool with a pair of tokens, provide liquidity by depositing reserve tokens into the liquidity pool, and trade tokens using the liquidity pool.

How does it work?

Liquidity Module has two major distinctive characteristics:

  • First, it combines a traditional order book based exchange system with a Uniswap-like AMM (Automated Market Maker) mechanism. This hybrid system deepens liquidity for the token swap marketplace.
  • The second major characteristic of the Liquidity Module is batch-style swap execution. The order book accumulates incoming limit orders into a batch. It matches accumulated limit orders and orders from the liquidity pool at an equivalent swap price at each batch execution height. All limit orders in a batch are treated equally and executed at the same swap price. This mechanism minimizes front-running risk and sub-second latency competition, thereby protecting ordinary traders.

Proposed fee structure

Liquidity providers earn fees through the creation of pools and the supply of tokens. The initial analysis proposes the following fee structure:

  • Swap Fee Rate = 0.003 (0.3%)
  • Pool Creation Fee = 100ATOM

An additional fee is charged on all withdrawals to protect pool investors from attack vectors and maintain pool stability. An appropriate rate could be 0.003 (0.3%)

All transactions incur a gas fee. Readers can find further details in the light paper.

Risk Management

Risk management is focused on two areas, code base and the model. These are mitigated through the following strategies:

Codebase Vulnerabilities

  • Test Coverage Over 80%: Minimum criteria of test coverage for Liquidity Module is 80%.
  • Extensive Simulation Tests: We conduct extensive simulation testing for core functionalities of the Liquidity Module.
  • External Audit: an independent audit of the codebase is due to start shortly.

Economic Model Risk

  • Economic Simulation with Agent-based Model: We conduct economic simulation on Liquidity Module with an agent-based model. The report will be published in early March.
  • Testnets to assess pool performance
  • Optionally a phased mainnet release with pools limited in size initially.

Node Performance

The Cosmos Hub is likely to experience an increased number of transactions coming from new features, such as IBC and DeX. Most new DeX transactions will be swap orders from different liquidity pools. Increased traffic on the Cosmos Hub could cause performance issues for blockchain nodes with less computational resources. It may also require tuning of genesis parameters. For example, an increase in block_size will allow for larger block space.

We have tested the performance of Liquidity Module by submitting many swap order transactions into the state machines. From our testing, with two cores, 8G RAM node specs, it concludes that,

  • All transactions are well broadcasted and committed to the blockchain when the transaction-per-block rate is less than 400.
  • When transaction per block is about 400, the average block time increased from 6.19s to 6.90s (0.71s increased).
  • When transaction per block is higher than 400, the nodes started to lose a significant number of transactions.

To conclude, if there are frequently more than 400 swap order transactions in a block, it will be necessary for node operators and validators to review their hardware capacity.

Also, to allow an increased number of transactions within a block, we have to increase block_size as follows, assuming additional 1,000 swap order transactions in a block:

  • max_bytes : 150,000 → 500,000 ( 350 bytes per 1 swap message )
  • max_gas : 1,500,000 → 81,500,000 ( 80,000 gas per 1 swap message )

Mempool Policy

The sorting of transactions that are to be included in a block is primarily decided by the state machine’s mempool policy. In most AMMs, sorting of swap order transactions impacts significantly on their execution price. Hence fair sorting policy is very crucial. Our AMM does not prioritize swap order transactions based on transaction sorting in blocks thanks to our batch execution model. Every swap order transaction is treated equally, and the execution price is equivalent for all swap order transactions within a batch.

Next steps

The Liquidity Module code is due to be ready by mid-March. At this point, the code will enter the Quality Assurance phase.


As mentioned above, the team has performed extensive testing through test coverage, simulation (i.e. fuzzy testing), and performance testing. Economic testing is underway and will be completed at the beginning of March, before performing full integration testing and the launch of testnets for the community use soon after.


Risk management already mentioned an external software assurance audit as an essential artifact. The process to select an auditor is underway. Once their recommendations are received, they will be implemented as needed.

At this point, a final governance proposal to upgrade Gaia (the state machine of the Cosmos Hub) to include the Liquidity Module will be raised.


The potential of the Cosmos Hub AMM is inspiring. With IBC’s asset transfer capability, it offers Cosmos Hub an opportunity to become the center of the interchain financial ecosystem.

  • Read the Liquidity Module light paper here.
  • Learn about the module implementation here.

Appendix: Pool Investment Opportunities

Assuming adoption of the Liquidity Module on the Cosmos Hub, ATOM holders will have an additional utility for ATOM to be invested in liquidity pools. The graph below is a theoretical analysis of a liquidity pool investment based on an ATOM/$STABLECOIN token pair.


  • Annual percentage yield from swap fee distribution to liquidity pool investors is assumed to be 10%, 20%, 30%, 40% and 50% respectively.
  • The average Atom price for a year is assumed to be the average of Atom prices at the beginning and end of the one year period.
  • HODL APY: It assumes the investor holds 100% ATOM for one year period

Annual Percentage Yield (APY) Analysis

In the below graph, X-axis represents Atom price change after one year; Y-axis represents an annual percentage yield of the pool investment with each assumption. It suggests that the pool investment has a better risk-return profile for most scenarios, except for a sharp increase in ATOM price. The pool investment gives safer and more balanced profit opportunities than just holding the assets(HODL). In the case when ATOM price decreases, it provides some protection from significant loss.

The below data is produced by a simulation based on the assumptions above; therefore, it is NOT meant to be a reliable ROI forecast analysis and should NOT be taken as investment advice.


I’m very excited to the liquidity module come to life as fulfillment of part of the ATOM2021 vision.

There will be many DEXes in the Cosmos but permissionless price discovery is a core function of the Interchain and the HUB must play a role.


Thank you for sharing your support @zaki_iqlusion !

Yes, there will be many trading platforms in Cosmos and also in other blockchain networks. Each will have its own advantages to attract different kinds of trading/investment demands.

B-Harvest has a bigger vision for the Liquidity Module to connect all liquidity from such different blockchains and trading platforms, aka “ibc connected liquidity module”.

Cosmos Hub can become the center of trading environment which connects many DeXs in the interchain world.

This Liquidity Module is only the very first step towards greater utilities for interchain users.


Thanks Hyung this is awesome! Amazing work. Very clear proposal and light paper.

Is there a more formal analysis of Equivalent Swap Price model somewhere or is this the first place it’s introduced? Maybe more specifically, what are the consequences of path dependence for pool reserves (the linked Vitalik post suggests it could be dangerous, but I haven’t thought it through).

Would it also be possible to link to more details on the simulation tests and the agent based models, or at least a short description of the work and who’s doing it if the details are forthcoming
in a report (seems the report is due towards the end of the voting period for this proposal)?

We’re also going to want to keep a close eye on how the yields here compete with staking. We should probably land the update to the “inflation rate change” param before the AMM goes live at least to make the inflation more responsive to changes in stake, and may need to think a bit more about how AMM and staking parameters will intersect. There may be a need for a more advanced inflation rate controller (eg. PID?) or maybe there are ways for the AMM itself to balance fees distribution between LPs and staked atom or otherwise integrate with the controller ?


Thank you @ebuchman for great questions!!! Let me briefly answer your questions.

  1. Thank you again for asking about one of the most important aspect of Liquidity Module matching engine! Yes, we are very aware of the path-dependency topic Vitalik raised several years ago. Let me describe some important aspects of this topic as below
  • Path independency guarantee pool investors that when the pool price changes and come back to original price, the pool investor will have exactly same reserve asset portfolio, except for fee returns. Therefore, attackers cannot fool around the pool investors by moving the price. Whereever the price goes, as long as the price comes back to “unmanipulated” price, which is the global price, (because of arbitrageurs) pool investors will end up with the original portfolio plus fee earned.

  • Path dependency means that, the portfolio can change even though the price comes back to original price. The portfolio is dependent to the path of the price. Vitalik explains that this will open attack vector by manipulating pool price.

  • But, this risk is only bounded to a situation only if there exists any chance that the any one token in the portfolio has less amount than original reserve.(This is not accurately pointed out by Vitalik) We call our situation as “monotonic increasing path dependency”, because for any price path, if the price comes back to the original price, both reserve tokens “always” have greater amount than original amount. This is I can call it “extra earning of pool by volatility”. Higher volatility results in more extra income for pool investors (no extra income for constant product market maker). It gives more buffer for pool investors to protect their position against impermenant loss caused by high volatility of the price.

  • So, our model is safer for pool investors in any price change. It has some drawback though, which is larger slippage cost for large amount swaps. But, if the swap amount is not significant(less than 0.1%), then the difference is minimal. And we also have “orderbook” which is better for large trading.

  • quick fact : Uniswap is not path independent either in practical sense, because of fee earned during price travelling. But, like Equivalent Swap Price Model, it is monotonically increasing so it doesn’t matter!

  • However, the main reason why we fixed the CPMM is that the model incorporates problem when we combine orderbook into AMM. The problem is : inconsistency of pool price and swap price. For example in CPMM, if price is 100, and if i trade 1, then swap price is 101 but the pool price ends up landing 102. Then, the orders in orderbook which are sell orders with order price between 101~102 is not executed, but the pool price is higher than those orders.(“matchable unexecuted orders”). It gives very significant inefficiency in price discovery related to limit orders in orderbook. In short, CPMM does not fit with orderbook! I think it is “wrong” in the “system agnostic” sense.

  • quick fact : because CPMM makes pool price goes much further than swap price, it results in unnecessary extra pool price swing which invites unnecessary additional arbitrage activities. This gives CPMM inefficient price discovery process compared to our model.

  • Analogies are described in this short introduction on Equivalent Swap Price Model : Equivalent Swap Price Model - Google Slides

  1. Let me link our pseudo codes on “agent-based economic simulation” : Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.
  • it assumes 3 types of users : pool investors, traders, and arbitrageurs. Each user type consist of multiple agents randomly(but with following modeled incentive) act on the Liquidity Module with predefined parameters.
  • we will conduct many simulation with different parameters to see the economic consequences of the agents’ behavior.
  1. Yes I think the staking module should genuinely consider its future strategy against higher yields on DeFi space. We cannot stop atom holders to unstake for better profitability in DeFi space. Even if we don’t have alternatives, Uniswap or Sushiswap can also provide such opportunity, “additional profit from farming rewards in UNI or SUSHI”. Therefore, staking module needs its own extra reward source, which can be like “BNB Launch Pool”.(Introducing Launchpool, a Secure Way to Farm New Assets - Farm Launchpool’s First Project, Bella Protocol (BEL) By Staking BNB, BUSD or ARPA Tokens. | Binance Support). The Fund Raising Module in Cosmos Hub can be connected to the staking module to provide proportional amount of new tokens sold in the Fund Raising Module to the Atom delegators. aka “Crowd Fund Farming” from atom delegation.

Personally I don’t think AMM should depend on staking ratio or its related environment. Hub AMM does not compete with staking module, but its actual competitors are AMMs in other networks, and we should not have any disadvantage which might lead to less attractive investment in liquidity pools


Thanks very much for the details Hyung!

I understand that in practice Uniswap is path dependent because of the fees, but it seems straight forward to reason about how that’s in favour of the LPs (“monotonic increasing” as you say). However it’s less clear to me how to conclude that the ESPMM (before fees) is also monotonic increasing. Is there an argument for that somewhere I can follow? I will look at the slides you linked.

Otherwise I think the design you have here of marrying the AMM with an Order Book is really interesting, and adjusting the AMM design to facilitate order book execution so that we can have the best of both worlds is very clever!

1 Like

Let me clarify by providing mathematical proof on “monotonic increasing” as follows:

  • Assumption

    • No limit order participates in this process
    • There is no fee for swaps
  • Process

    • Let the pool has two reserve tokens, A and B
    • Amount of token A,B in reserve is NA,NB respectively
    • An attacker buy B token by sending in n amount of A token
    • If all n amount of A token is swapped, then the best swap price he/she can get is (NA+2*n)/NB from ESPM
    • Hence, the received amount of B token for attacker is NB*(n/(NA+2*n))
    • In CPMM, the received amount of B token would be NB*(n/(NA+n))
    • If you compare those two, you can see that the attacker “always” gets less B token from the swap, compared to CPMM
    • Opposite direction swap process can be described vice versa
  • Conclusion

    • Therefore, ESPM guarantees to pool investors that in any price path, they pay less B token than CPMM to swap requestors
    • Because CPMM is path independent, ESPM is monotonically increasing
  • Fun Fact

    • If attacker want buy B token from A token, (because it is cheaper than global price) , by splitting swap orders (n) to epsilon amount, submit each order per batch, then, the attacker can have the CPMM swap price!
1 Like

Ah thanks for explaining that should have been clear. The price for a buy is always higher in ESPM than CPMM. So can it just be modelled as an extra fee? ie. of n/NB ? That might also clarify where the larger slippage cost comes from.

You CAN see that as an extra fee, but it is not what I intended. As the slide shows, the derivation came from SwapPrice=(postswap)PoolPrice. Very natural equation for any matching system.

Extra fee(twice slippage cost) is just a consequence of such natural reasoning. So ESPM is not just one model with extra fee. It is the only model where swapprice equals poolprice.

Another way to see CPMM is to model it as swapprice = (lastpoolprice+thispoolprice)/2
Swapprice defined as midpoint of last and this pool price. ← this is how I see CPMM. From this, I can intuitively see why it is path independent.

These series of talks should be very interesting, because I also was during design works. Great chance to understand AMM mechanism better.

1 Like

I want to raise an important question towards our Cosmos Hub community.

Do we want to “Limit” the amount invested in Liquidity Pool, until we have enough confidence to remove the limit?

Although we have enough confidence on our implementation quality cross-checked by various testing procedures, for this important network, it is healthy to have as conservative approach as possible upon launching new features on our network.

B-Harvest thinks users’ safety as the first value for any utility developed from us, so we think this limit feature is necessary at the early stage of adoption on Cosmos Hub.

This is how the “Limit” feature can be implemented on Liquidity Module.

  1. Each liquidity pool will have the same limit of reserve token amount as “LiquidityPoolLimitAmount”.
  2. All deposit transaction which makes a pool having more reserve token than “LiquidityPoolLimitAmount” will be failed.
  3. Other transactions such as swap or withdraw will be functioning as normal.
  4. When we have enough confidence on robustness of Liquidity Module, we can have a parameter governance to increase “LiquidityPoolLimitAmount” to much greater value, or modify the value to “-1” so that there exists no amount limit anymore.

Our suggestion on the initial parameter value is 1,000,000.
For some pool cases such as “WBTC/ETH”, it might can have to high USD value as limit, but for the most pools, 1,000,000 limit will work well as a conservative safeguard for early phase of adoption.

Please share your opinions. Thank you.

1 Like

What if atom will cost $1000 ? It will take $100,000 to create a pool?

Thanks for raising the question.
Because the value of Atom has increased over recent months, we would like to suggest lower initial amount for creating new pool.

100ATOM → 40ATOM

It is about $1,000 with $25 Atom price.
As you suggested, higher Atom price will result in more expensive cost for creating new pool.

If we remove this fee, the module will open a spamming attack vector to create thousands of pools, which might delay the performance of the network. So, I think some level of new pool creation fee for preventing spam attack is necessary.

Thank you Hyung for this great proposal.

Would the cost for creating a pool adapt to the price of ATOM, or would it be set at release and only be able to change through governance?

Cant wait for this proposal to be love on the 25th!

Only be able to change via governance. It can be upgraded in the future to have fixed dollar amount by using the biggest atom pool with stable coin as oracle. Currently, dex is not launched yet, so we can’t apply that yet.

Thank you for your question!

In the bull-case for ATOM and the hub, there are surely thousands of pools.

As the number of pools increases, how much does resource consumption / computational load increase when using the liquidity module?

Currently there are just over 30,000 pairs on Uniswap, and it’s probably not grown to its full potential.

How many pairs/pools is too many?

Should we make the cost to open a pool itself a bonding curve based thing ? :stuck_out_tongue: And will there be a way to close out a pool ?

As for pool limits, in general I’m in favour of such conservativism to start, but I wonder how effective it can be, since folks can always redenominate their tokens on a zone so that each unit is 10x or more the original unit. Eg. if there’s a limit of 1M, I can send my ATOMs to a zone that will let me make a new token where each token is 10ATOM or 42ATOM or whatever, and then start a new pool with that token as the reserve, effectively upping the limit. Of course people would need to be aware of this so that they’d trade on that pool and thus they’d know we’re skirting the limit.

In any case, I’d say an initial limit that can be progressively increased is a good idea.

The computation burden actually is not dependent on the number of pools, but on the number of “alive batches” at certain height.

Pools without any order will not create a batch, hence no computation engaged.

So the computation burden is dependent to number of orders and alive batches within a block.

Our performance test suggest that 1k orders in a block results in 0.3second block time delay. But this delay is similar with sending txs simulation. We have to test multi-batch scenarios though.

In the super bull case when we see thousands of orders in a block quite often, we might want to have a flat order fee so that we can discourage low amount orders. But I think we are quite far from that :slight_smile:

Also we have plan to compute each batch in parallel computing, hence increasing number of cores for fullnodes and validator nodes will horizontally expand our capacity to handle the orders.

Also in further plan,b-harvest will develop zkrollup supported dex zone, which will allow gravity dex to move to a zone secured by the hub via zkrollup. This is also quite far away roadmap(2023)

1 Like

Yes. There exists many open risks, but still the limit relatively reduce the risk of systemic failure significantly. The limit will only last for several weeks, so the simplest one can do its job enough :slight_smile:

Thanks for the detailed reply!

I am also curious about your thoughts re: state growth on Gaia-- I guess it’s fair to say that I prefer a high-fee world, where Gaia grows more slowly with respect to storage capacity… and even in a high fee world, we are still likely much more affordable than Uniswap is these days, for example.

TBH, I made a song / propaganda video about it:

Only alive&unexecuted orders are stored in the state. If so many orders are unexecuted and accumulated in orderbook, it is a great burden to the state indeed.

We might want to adopt MaxOrderLife parameter so that any order cannot stay alive more than this number of height(orders alive more than this period are immediately cancelled)