{"id":13573124,"url":"https://github.com/tendermint/liquidity","last_synced_at":"2025-04-09T09:09:44.223Z","repository":{"id":40497810,"uuid":"299671371","full_name":"tendermint/liquidity","owner":"tendermint","description":"Cosmos SDK Liquidity module","archived":false,"fork":false,"pushed_at":"2022-02-23T09:31:19.000Z","size":10962,"stargazers_count":141,"open_issues_count":34,"forks_count":57,"subscribers_count":24,"default_branch":"develop","last_synced_at":"2025-04-02T02:28:54.543Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tendermint.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-29T16:14:23.000Z","updated_at":"2025-03-17T16:26:07.000Z","dependencies_parsed_at":"2022-07-16T10:16:16.922Z","dependency_job_id":null,"html_url":"https://github.com/tendermint/liquidity","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tendermint%2Fliquidity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tendermint%2Fliquidity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tendermint%2Fliquidity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tendermint%2Fliquidity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tendermint","download_url":"https://codeload.github.com/tendermint/liquidity/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:00:30.133Z","updated_at":"2025-04-09T09:09:44.201Z","avatar_url":"https://github.com/tendermint.png","language":"Go","funding_links":[],"categories":["Cosmos SDK Modules","Go"],"sub_categories":["External Modules"],"readme":"\u003c!-- markdown-link-check-disable-next-line --\u003e\n[![codecov](https://codecov.io/gh/tendermint/liquidity/branch/develop/graph/badge.svg)](https://codecov.io/gh/tendermint/liquidity?branch=develop)\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/tendermint/liquidity)](https://pkg.go.dev/github.com/tendermint/liquidity)\n\n# Liquidity Module\n\nThe liquidity module serves Automated Market Maker (AMM)-style decentralized liquidity by providing liquidity activities and coin swap functions.\n\nThe module enables users to create a liquidity pool, make deposits and withdrawals, and request coin swaps from the liquidity pool.\n\nThis module can be used in the [Cosmos Hub](https://hub.cosmos.network/main/hub-overview/overview.html) and any other [Cosmos SDK](https://cosmos.network/)-based blockchain projects.\n\n- The Cosmos Hub AMM applies a strong philosophy of inclusiveness for users from different blockchains with its prime utility of inter-blockchain communication.\n- To achieve heterogeneous blockchain adoption, the liquidity module provides convenient entry points for external users to come in and use the services that are provided by the Cosmos Hub.\n- The liquidity module does not anticipate specific assets, such as ATOM, into the user workflow. Data shows that unnatural anticipation of native coin at unavoidable parts of the process results in poor user attraction.\n\n## Key features\n\n![new-amm-model](doc/img/new-amm-model.png)\n\n**Combination of traditional orderbook-based model and new AMM model**\n\n- With multiple advantages over order book-based models, the liquidity module combines a batch-based order book matching algorithm with AMM to create enriched utilities for more potential users.\n- The liquidity module redefines the concept of a “swap order” in AMM as a “limit order with a short lifetime” in an order book-based exchange. By combining these concepts from two different models as one united model, the function supports both ways to participate in trading and liquidity-providing activities.\n- Limit order options are not supported in the first version of the liquidity module, but the base structure of the codebase anticipates and supports feature expansion.\n- Advantages of the combined model\n    - More freedom on ways to provide liquidity, planned expansion for limit orders\n    - The combination of pool liquidity and limit order liquidity provide users with a more enriched trading environment\n\nFor details, see the [Liquidity Module Light Paper](doc/LiquidityModuleLightPaper_EN.pdf).\n\n## Installation\n\n### Requirements\n\nRequirement | Notes\n----------- | -----------------\nGo version  | Go1.15 or higher\nCosmos SDK  | v0.45.1 or higher\n\n### Get Liquidity Module source code\n\n```bash\n$ git clone https://github.com/tendermint/liquidity.git\n$ cd liquidity\n$ go mod tidy\n```\n\n### Build\n\n```bash\n# The `liquidityd` binary is in the build directory.\n$ make build\n```\n\n### Install\n\n```bash\n$ make install\n```\n\n## Usage of CLI Commands\n\nWith the exception of creating the liquidity pool, all commands are implemented to execute on the batch.\n\n### Transactions\n\n`$ liquidityd tx liquidity --help`\n\n```bash\nLiquidity transaction subcommands\n\nUsage:\n  liquidityd tx liquidity [flags]\n  liquidityd tx liquidity [command]\n\nAvailable Commands:\n  create-pool Create liquidity pool and deposit coins\n  deposit     Deposit coins to a liquidity pool\n  swap        Swap offer coin with demand coin\n  withdraw    Withdraw pool coin\n```\n\n### Queries\n\n`$ liquidityd query liquidity --help`\n\n```bash\nQuerying commands for the liquidity module\n\nUsage:\n  liquidityd query liquidity [flags]\n  liquidityd query liquidity [command]\n\nAvailable Commands:\n  batch       Query details of a liquidity pool batch\n  deposit     Query the deposit messages on the liquidity pool batch\n  deposits    Query all deposit messages of the liquidity pool batch\n  params      Query the values set as liquidity parameters\n  pool        Query details of a liquidity pool\n  pools       Query for all liquidity pools\n  swap        Query for the swap message on the batch of the liquidity pool specified pool-id and msg-index\n  swaps       Query all swap messages in the liquidity pool batch\n  withdraw    Query the withdraw messages in the liquidity pool batch\n  withdraws   Query for all withdraw messages on the liquidity pool batch\n```\n\n#### A detailed document on client can be found here. [client.md](doc/client.md)\n\n## Development\n\n### Test\n\n```bash\n$ make test-all\n```\n\n### 1\\. Setup local testnet using script\n\n```bash\n# This script bootstraps a single local testnet.\n# Note that config, data, and keys are created in the ./data/localnet folder and\n# RPC, GRPC, and REST ports are all open.\n$ make localnet\n```\n\n### 1.1 Broadcast transactions using CLI command-line interface\n\nSample scripts are provided in [scripts](https://github.com/tendermint/liquidity/tree/develop/scripts) folder to help you to test the liquidity module interface.\n\n### 2. Manually set up a local testnet\n\n```bash\n# Build\nmake install\n\n# Set Binary name of the app\n# The basic simapp binary of the liquidity module is liquidityd, but set it differently depending on the situation such as gaiad.\nBINARY=liquidityd\n\n# Initialize and add keys\n$BINARY init testing --chain-id testing\n$BINARY keys add validator --keyring-backend test\n$BINARY keys add user1 --keyring-backend test\n\n# Add genesis accounts and provide coins to the accounts\n$BINARY add-genesis-account $($BINARY keys show validator --keyring-backend test -a) 10000000000stake,10000000000uatom,500000000000uusd\n$BINARY add-genesis-account $($BINARY keys show user1 --keyring-backend test -a) 10000000000stake,10000000000uatom,500000000000uusd\n\n# Create gentx and collect\n$BINARY gentx validator 1000000000stake --chain-id testing --keyring-backend test\n$BINARY collect-gentxs\n\n# Start\n$BINARY start\n```\n\n### 2.1 Broadcast transactions using CLI commands\n\n```bash\n# An example of creating liquidity pool 1\n$BINARY tx liquidity create-pool 1 1000000000uatom,50000000000uusd --from user1 --keyring-backend test --chain-id testing -b block -o json -y\n\n# An example of creating liquidity pool 2\n$BINARY tx liquidity create-pool 1 10000000stake,10000000uusd --from validator --keyring-backend test --chain-id testing -b block -o json -y\n\n# An example of requesting swap\n$BINARY tx liquidity swap 1 1 50000000uusd uatom 0.019 0.003 --from validator --chain-id testing --keyring-backend test -b block -o json -y\n\n# An example of generating unsigned tx\nvalidator=$($BINARY keys show validator --keyring-backend test -a)\n$BINARY tx liquidity swap 1 1 50000000uusd uatom 0.019 0.003 --from $validator --chain-id testing --generate-only \u0026\u003e tx_swap.json\ncat tx_swap.json\n\n# Sign the unsigned tx\n$BINARY tx sign tx_swap.json --from validator --chain-id testing --keyring-backend test -y \u0026\u003e tx_swap_signed.json\ncat tx_swap_signed.json\n\n# Encode the signed tx\n$BINARY tx encode tx_swap_signed.json\ntx_bytes=$($BINARY tx encode tx_swap_signed.json)\n```\n\n### 2.2 Broadcast transactions using REST APIs\n\nFor an example of broadcasting transactions using REST API (via gRPC-gateway), see Cosmos SDK [Migrating to New REST Endpoints](https://github.com/cosmos/cosmos-sdk/blob/master/docs/migrations/rest.md#migrating-to-new-rest-endpoints). Testing requires that the API server is enabled in `$HOME/.liquidityapp/config/app.toml`.\n\n```bash\ncurl --header \"Content-Type: application/json\" --request POST --data '{\"tx_bytes\":\"'\"$tx_bytes\"'\",\"mode\":1}' localhost:1317/cosmos/tx/v1beta1/txs\n```\n\n### 2.3 Export Genesis State\n\n`$ $BINARY export`\n\n### Export empty state case\n\n```json\n{\n  \"liquidity\": {\n    \"params\": {\n      \"circuit_breaker_enabled\": false,\n      \"init_pool_coin_mint_amount\": \"1000000\",\n      \"max_order_amount_ratio\": \"0.100000000000000000\",\n      \"max_reserve_coin_amount\": \"0\",\n      \"min_init_deposit_amount\": \"1000000\",\n      \"pool_creation_fee\": [\n        {\n          \"amount\": \"40000000\",\n          \"denom\": \"stake\"\n        }\n      ],\n      \"pool_types\": [\n        {\n          \"description\": \"Standard liquidity pool with pool price function X/Y, ESPM constraint, and two kinds of reserve coins\",\n          \"id\": 1,\n          \"max_reserve_coin_num\": 2,\n          \"min_reserve_coin_num\": 2,\n          \"name\": \"StandardLiquidityPool\"\n        }\n      ],\n      \"swap_fee_rate\": \"0.003000000000000000\",\n      \"unit_batch_height\": 1,\n      \"withdraw_fee_rate\": \"0.000000000000000000\"\n    },\n    \"pool_records\": []\n  }\n}\n```\n\n### Export when some states exist\n\n```json\n{\n  \"liquidity\": {\n    \"params\": {\n      \"circuit_breaker_enabled\": false,\n      \"init_pool_coin_mint_amount\": \"1000000\",\n      \"max_order_amount_ratio\": \"0.100000000000000000\",\n      \"max_reserve_coin_amount\": \"0\",\n      \"min_init_deposit_amount\": \"1000000\",\n      \"pool_creation_fee\": [\n        {\n          \"amount\": \"40000000\",\n          \"denom\": \"stake\"\n        }\n      ],\n      \"pool_types\": [\n        {\n          \"description\": \"Standard liquidity pool with pool price function X/Y, ESPM constraint, and two kinds of reserve coins\",\n          \"id\": 1,\n          \"max_reserve_coin_num\": 2,\n          \"min_reserve_coin_num\": 2,\n          \"name\": \"StandardLiquidityPool\"\n        }\n      ],\n      \"swap_fee_rate\": \"0.003000000000000000\",\n      \"unit_batch_height\": 1,\n      \"withdraw_fee_rate\": \"0.000000000000000000\"\n    },\n    \"pool_records\": [\n      {\n        \"deposit_msg_states\": [],\n        \"pool\": {\n          \"id\": \"1\",\n          \"pool_coin_denom\": \"pool96EF6EA6E5AC828ED87E8D07E7AE2A8180570ADD212117B2DA6F0B75D17A6295\",\n          \"reserve_account_address\": \"cosmos1jmhkafh94jpgakr735r70t32sxq9wzkayzs9we\",\n          \"reserve_coin_denoms\": [\n            \"uatom\",\n            \"uusd\"\n          ],\n          \"type_id\": 1\n        },\n        \"pool_batch\": {\n          \"begin_height\": \"563\",\n          \"deposit_msg_index\": \"2\",\n          \"executed\": false,\n          \"index\": \"3\",\n          \"pool_id\": \"1\",\n          \"swap_msg_index\": \"2\",\n          \"withdraw_msg_index\": \"2\"\n        },\n        \"pool_metadata\": {\n          \"pool_coin_total_supply\": {\n            \"amount\": \"1089899\",\n            \"denom\": \"pool96EF6EA6E5AC828ED87E8D07E7AE2A8180570ADD212117B2DA6F0B75D17A6295\"\n          },\n          \"pool_id\": \"1\",\n          \"reserve_coins\": [\n            {\n              \"amount\": \"1088843820\",\n              \"denom\": \"uatom\"\n            },\n            {\n              \"amount\": \"54551075322\",\n              \"denom\": \"uusd\"\n            }\n          ]\n        },\n        \"swap_msg_states\": [],\n        \"withdraw_msg_states\": []\n      },\n      {\n        \"deposit_msg_states\": [],\n        \"pool\": {\n          \"id\": \"2\",\n          \"pool_coin_denom\": \"poolA4648A10F8D43B8EE4D915A35CB292618215D9F60CE3E2E29216489CF1FAE049\",\n          \"reserve_account_address\": \"cosmos153jg5y8c6sacaexezk34ev5jvxpptk0kscrx0x\",\n          \"reserve_coin_denoms\": [\n            \"stake\",\n            \"uusd\"\n          ],\n          \"type_id\": 1\n        },\n        \"pool_batch\": {\n          \"begin_height\": \"0\",\n          \"deposit_msg_index\": \"1\",\n          \"executed\": false,\n          \"index\": \"1\",\n          \"pool_id\": \"2\",\n          \"swap_msg_index\": \"1\",\n          \"withdraw_msg_index\": \"1\"\n        },\n        \"pool_metadata\": {\n          \"pool_coin_total_supply\": {\n            \"amount\": \"1000000\",\n            \"denom\": \"poolA4648A10F8D43B8EE4D915A35CB292618215D9F60CE3E2E29216489CF1FAE049\"\n          },\n          \"pool_id\": \"2\",\n          \"reserve_coins\": [\n            {\n              \"amount\": \"10000000\",\n              \"denom\": \"stake\"\n            },\n            {\n              \"amount\": \"10000000\",\n              \"denom\": \"uusd\"\n            }\n          ]\n        },\n        \"swap_msg_states\": [],\n        \"withdraw_msg_states\": []\n      }\n    ]\n  }\n}\n```\n\n### Protobuf and Swagger\n\nThe API documentation for the liquidity module is available on `http://localhost:1317/swagger-liquidity/` after you successfully boostrap a testnet in your local computer.\n\nYou must set `swagger` config to `true` in `$HOME/.liquidityapp/config/app.toml`. The public Swagger API docs are also available on [Cosmos SDK Liquidity Module - REST and gRPC Gateway docs](https://app.swaggerhub.com/apis-docs/bharvest/cosmos-sdk_liquidity_module_rest_and_g_rpc_gateway_docs).\n\n```bash\n# Generate `*.pb.go`, `*.pb.gw.go` files from `proto/*.proto`\n$ make proto-gen\n\n# Generate `swagger.yaml` from `proto/*.proto`\n$ make proto-swagger-gen\n```\n\n## Resources\n\nTo learn more about the liquidity module, check out the following resources:\n\n - [Liquidity Module Spec](x/liquidity/spec)\n - [Liquidity Module Lite Paper (English)](doc/LiquidityModuleLightPaper_EN.pdf)\n - [Liquidity Module Lite Paper (Korean)](doc/LiquidityModuleLightPaper_KO.pdf)\n - [Liquidity Module Lite Paper (Chinese)](doc/LiquidityModuleLightPaper_ZH.pdf)\n - [Liquidity Module Security Audit Report of Least Authority](doc/Least_Authority_Liquidity_Module_Security_Audit_Report.pdf)\n - [Proposal and milestone](https://github.com/b-harvest/Liquidity-Module-For-the-Hub)\n - [Swagger HTTP API doc](https://app.swaggerhub.com/apis-docs/bharvest/cosmos-sdk_liquidity_module_rest_and_g_rpc_gateway_docs)\n - [godoc](https://pkg.go.dev/github.com/tendermint/liquidity)\n - [Client doc](doc/client.md)\n - [Performance Testing](doc/Performance%20Testing%20for%20Liquidity%20Module.pdf)\n ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftendermint%2Fliquidity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftendermint%2Fliquidity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftendermint%2Fliquidity/lists"}