Liquidity.Party/lmsr-amm
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

introduction=>README.md

Browse Source
This commit is contained in:
tim
2025-10-27 16:19:21 -04:00
parent cb72042998
commit 687d7f9be0
2 changed files with 85 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
README.md Normal file
View File

@@ -0,0 +1,85 @@
# Introduction
[Liquidity Party](https://liquidity.party) is a new game-theoretic multi-asset AMM based on this research paper:
[Logarithmic Market Scoring Rules for Modular Combinatorial Information Aggregation](https://mason.gmu.edu/~rhanson/mktscore.pdf) (R. Hanson, 2002)
Our formulation and implementation is described in the [Liquidity Party whitepaper.](doc/whitepaper.md)
A Logarithmic Market Scoring Rule (LMSR) is a pricing formula for AMM's that know only their current asset inventories
and no other information, naturally supporting multi-asset pools.
Compared to Constant Product markets, LMSR offers:
1. Less slippage than Constant Product for small and medium trade sizes
2. N-asset pools for trading long-tail pairs in a single hop
3. Lower fees (smaller spread)
## Deeper Liquidity
According to game theory, the initial price slope of a Constant Product AMM is too steep, overcharging takers
with too much slippage at small and medium trade sizes. LMSR pools offer less slippage and cheaper
liquidity for the small and medium trade sizes used by real traders.
## Multi-asset
Naturally multi-asset, Liquidity Party altcoin pools provide direct, one-hop swaps on otherwise illiquid multi-hop pairs. Pools will quote any pair combination available in the pool:
| Assets | Pairs | Swap Gas | Mint Gas |
|-------:|------:|---------:|----------:|
| 2 | 1 | 131,000 | 143,000 |
| 2* | 1 | 118,000 | 143,000 |
| 10 | 45 | 142,000 | 412,000 |
| 20 | 190 | 157,000 | 749,000 |
| 50 | 1225 | 199,000 | 1,760,000 |
| 100 | 4950 | 269,000 | 2,684,000 |
\* Stablecoin pair pool optimization
Liquidity Party aggregates scarce, low market cap assets into a single pool, providing one-hop liquidity for exotic pairs without fragmenting LP assets. CP pools would need 190x the LP assets to provide the same pairwise liquidity as a single 20-asset Liquidity Party pool, due to asset fragmentation.
## Lower Fees
Since market makers offer the option to take either side of the market, they must receive a subsidy or charge a fee (spread) to compensate for adverse selection (impermanent loss). By protecting LP's against common value-extraction scenarios, LMSR pools have a reduced risk premium resulting in lower fees for takers.
### Minimized Impermanent Loss
All AMM's suffer from Impermanent Loss (IL), also known as adverse selection or toxic order flow. Liquidity
Party uses game theory to minimize IL for LPs, by charging lower fees to small legitimate traders and
higher fees to large adversarial traders during market dislocations. This means a higher effective rate
for LP's and cheaper swaps for legitimate small traders.
Liquidity Party swaps guarantee a bounded maximum loss to LP's of `κ\*S\*ln(N)` where `κ` is
the pool's liquidity parameter, `S` is the total size of the pool, and `N` is the
number of assets in the pool.
### No Intra-Pool Arbitrage
Other multi-asset systems can provide inconsistent price quotes, allowing arbitragers to
extract value from LP's by _trading assets inside the same pool against each other._ With Liquidity
Party, no intra-pool arbitrage is possible, because the mathematics guarantee fully consistent price
quotes on all pairs in the pool.
# Installation
1. Install [Foundry](https://getfoundry.sh/) development framework.
2. Update dependencies with `forge install`
3. Run `bin/mock` to launch a test environment running under `anvil` on `localhost:8545`. The mock environment will create several example pools along with mock ERC20 tokens that can be minted by anyone in any amount.
# Integration
Deployment addresses for each chain may be found in `deployment/liqp-deployments.json`, and the `solc` output including ABI information is stored under `deployment/{chain_id}/v1/...`
The primary entrypoint for all Liquidity Party actions is the [PartyPlanner](src/IPartyPlanner.sol) contract, which is a singleton per chain. The `PartyPlanner` contract not only deploys new pools but also indexes the pools and their tokens for easy metadata discovery. After a pool is created or discovered using the `PartyPlanner`, it can be used to perform swaps, minting, and other actions according to the [IPartyPool](src/IPartyPlanner.sol) interface. Due to contract size limitations, most view methods for prices and swaps are available from a separate singleton contract, the [PartyPoolViewer](src/IPartyPoolViewer.sol).
# Implementation Notes
## Non-upgradable Proxy
Due to contract size constraints, the `PartyPool` contract uses `DELEGATECALL` to invoke implementations on the singleton [PartyPoolSwapImpl](src/PartyPoolSwapImpl.sol) and [PartyPoolMintImpl](src/PartyPoolMintImpl.sol) contracts. This proxy pattern is NOT upgradable and the implementation contract addresses used by the pool are immutable. Views implemented in `PartyPoolViewer` have no delegation but simply accept the target pool as an argument, calculating prices etc. from public getters.
## Admin-Only Deployment
`PartyPlanner` allows only the admin to deploy new pools. This decision was made because Liquidity Party is a new protocol that does not support non-standard tokens such as fee-on-transfer tokens or rebasing tokens, and the selection of the `kappa` liquidity parameter is not straightforward for an average user. We hope to offer a version of Liquidity Party in the future that allows regular users to create their pools.
## Killable Contracts
PartyPools may be "killed" by their admin, in which case all swaps and mints are disabled, and the only modifying function allowed to be called is `burn()` to allow LP's to safely withdraw their funds. Killing is irreversible and intended to be used as a last-ditch safety measure in case a critical vulnerablility is discovered.