{"id":17861707,"url":"https://github.com/0xosiris/cfmm-math-libraries","last_synced_at":"2025-03-20T22:31:06.348Z","repository":{"id":61952575,"uuid":"556424581","full_name":"0xOsiris/cfmm-math-libraries","owner":"0xOsiris","description":"CFMM Fixed Point Math libraries for price simulation, fixed point conversion, and swap simulation on v2/v3 pools.","archived":false,"fork":false,"pushed_at":"2023-01-21T18:53:37.000Z","size":115,"stargazers_count":41,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-09-19T01:51:10.541Z","etag":null,"topics":["defi","fixed-point","mev","solidity","uniswap-v2","uniswap-v3"],"latest_commit_sha":null,"homepage":"https://0xosiris.github.io/cfmm-math-libraries/","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xOsiris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-23T20:24:17.000Z","updated_at":"2024-07-09T09:48:25.000Z","dependencies_parsed_at":"2023-02-12T12:15:42.116Z","dependency_job_id":null,"html_url":"https://github.com/0xOsiris/cfmm-math-libraries","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xOsiris%2Fcfmm-math-libraries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xOsiris%2Fcfmm-math-libraries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xOsiris%2Fcfmm-math-libraries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xOsiris%2Fcfmm-math-libraries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xOsiris","download_url":"https://codeload.github.com/0xOsiris/cfmm-math-libraries/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244703748,"owners_count":20496171,"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":["defi","fixed-point","mev","solidity","uniswap-v2","uniswap-v3"],"created_at":"2024-10-28T08:46:57.264Z","updated_at":"2025-03-20T22:31:06.060Z","avatar_url":"https://github.com/0xOsiris.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"```solidity\n ________  ________ _____ ______   _____ ______           _____ ______   ________  _________  ___  ___\n|\\   ____\\|\\  _____\\\\   _ \\  _   \\|\\   _ \\  _   \\        |\\   _ \\  _   \\|\\   __  \\|\\___   ___\\\\  \\|\\  \\\n\\ \\  \\___|\\ \\  \\__/\\ \\  \\\\\\__\\ \\  \\ \\  \\\\\\__\\ \\  \\       \\ \\  \\\\\\__\\ \\  \\ \\  \\|\\  \\|___ \\  \\_\\ \\  \\\\\\  \\\n \\ \\  \\    \\ \\   __\\\\ \\  \\\\|__| \\  \\ \\  \\\\|__| \\  \\       \\ \\  \\\\|__| \\  \\ \\   __  \\   \\ \\  \\ \\ \\   __  \\\n  \\ \\  \\____\\ \\  \\_| \\ \\  \\    \\ \\  \\ \\  \\    \\ \\  \\       \\ \\  \\    \\ \\  \\ \\  \\ \\  \\   \\ \\  \\ \\ \\  \\ \\  \\\n   \\ \\_______\\ \\__\\   \\ \\__\\    \\ \\__\\ \\__\\    \\ \\__\\       \\ \\__\\    \\ \\__\\ \\__\\ \\__\\   \\ \\__\\ \\ \\__\\ \\__\\\n    \\|_______|\\|__|    \\|__|     \\|__|\\|__|     \\|__|        \\|__|     \\|__|\\|__|\\|__|    \\|__|  \\|__|\\|__|\n\n```\n\n# Overview\n\nCFMM Math Solidity library \u0026 contract for price simulation, fixed point conversion, and swap simulation on v2/v3 pools. The idea behind CFMM math is to provide an out of the box solidity tool suite that allows anyone to simulate, quote, compare, and convert v2/v3 prices seemlessly in a standardized fixed point representation.\n\nThis repository is still very much so a work in progress. The overall goal is to provide a solidity tool suite that acts as an abstraction layer on top of the major dex variants cfmm internal math libraries to allow very simple price comparison, simulation, and conversion by using a standardized fixed point framework. If you have any suggestions or issues, feel free to open an issue and I'll get back to you. Further, collaboration is more than welcome, so feel free to PR :)\n\n# Installation\n\nTo install as an npm package run:\n\n```shell\nnpm install @0xosiris/cfmm-math-libraries@1.1.2\n```\n\nIf you are using foundry add the following to your `foundry.toml`: \u003c/br\u003e\n\n```shell\nremappings=[\"cfmm-math-libraries/=node_modules/@0xosiris/cfmm-math-libraries/\"]\n```\n\nAlternatively add\n\n```json\n\"solidity.remappingsUnix\": [\n        \"cfmm-math-libraries/=node_modules/@0xosiris/cfmm-math-libraries/\",\n   ]\n```\n\nto your `settings.json` in vscode.\n\nFinally, simply import the contract and library into your contract:\n\n```solidity\n// SPDX-License-Identifier: MIT\npragma solidity 0.8.16;\n\nimport \"cfmm-math-libraries/src/CFMMQuoter.sol\";\nimport \"cfmm-math-libraries/src/libraries/CFMMMath.sol\";\n```\n\nInherit `CFMMQuoter` into your contract to access all internal logic:\n\n```solidity\ncontract MyContract is CFMMQuoter {}\n```\n\n# Test Instructions\n\nFrom the project route. \u003c/br\u003e\nRun Test Suite:\n\n```shell\nforge test -f \u003cRPC_ENDPOINT\u003e  --fork-block-number 15233771\n```\n\nRun Gas Snapshot:\n\n```shell\nforge snapshot -f \u003cRPC_ENDPOINT\u003e --fork-block-number 15233771\n```\n\n# Features\n\n## CFMMQuoter\n\n`CFMMQuoter.sol` offers a comprehensive tool suite for quoting amounts yielded from swaps, simulating price changes from input/output quantities, and inferring input/output quantities introduced/removed from a pool based on price changes. `CFMMQuoter` is a contract not a library. So, to cheaply utilize all of its core functions in your contract you can simply inherit `CFMMQuoter`.\n\n### V3 Features\n\nPrecisely quotes the amount yielded from a swap on a v3 pool. This function can be used to determine a precise amountOutMin for a v3 swap on chain, and eliminates the need to use the v3 quoter saving a significant amount of gas.\n\n```solidity\nfunction simulateAmountOutOnSqrtPriceX96(\n    address token0,\n    address tokenIn,\n    address lpAddressAToWeth,\n    uint256 amountIn,\n    int24 tickSpacing,\n    uint128 liquidity,\n    uint24 fee\n) internal returns (int256 amountOut\n```\n\nSimulates `tick` state of a v3 pool after swapping `amountIn` of `tokenIn`.\n\n```solidity\nfunction simulateNewTickOnInputAmountPrecise(\n        address token0,\n        address tokenIn,\n        address lpAddressAToWeth,\n        uint256 amountIn,\n        int24 tickSpacing,\n        uint128 liquidity,\n        uint24 fee\n    ) internal returns (int24 limitTick)\n```\n\nCalculates the exact amount introduced/removed from a v3 pool to move the price from `sqrtRatioAX96` to `sqrtRatioBX96`.\n\n```solidity\nfunction calculateDeltaAddedOnSqrtPriceChange(\n        uint160 sqrtRatioAX96,\n        uint160 sqrtRatioBX96,\n        uint128 liquidity\n    ) internal pure returns (uint256 amountDelta) {}\n\nfunction calculateDeltaRemovedOnSqrtPriceChange(\n        uint160 sqrtRatioAX96,\n        uint160 sqrtRatioBX96,\n        uint128 liquidity\n    ) internal pure returns (uint256 amountDelta) {}\n```\n\n### V2 Features\n\nPrecisely Quotes the amount1 received on a v2 swap.\n\n```solidity\nfunction calculateAmountOutV2(\n        uint256 amount0,\n        uint256 reserve0,\n        uint256 reserve1\n    ) internal pure returns (uint256 amount1) {}\n```\n\nPrecisely calculates the spot price in a v2 pool after swapping `amount0`.\n\n```solidity\nfunction v2SimulateNewSpotFromInput(\n        uint112 reserve0,\n        uint112 reserve1,\n        uint112 amount0\n    ) internal pure returns (uint128) {}\n```\n\n## CFMMMath\n\nCFMMMath provdes a tool suite for mathematical operations in 64.64 fixed point.\n\n### V3 Functions\nCalculates the spot price of token(x) in a pool represented as 64.64 fixed point.\n\n```solidity\nfunction v3SpotPrice64x64(\n        address _lp,\n        bool _zeroForOne,\n        uint8 decimals0,\n        uint8 decimals1\n    ) internal view returns (uint128 priceX64) {}\n```\n\nConverts sqrtRatioX96 (sqrt(spot price)) of form Q96.64 to 64.64 fixed point representation of the spot price normalized by token decimals, and directionally representative of the base/quote token.\n\n```solidity\nfunction fromSqrtX96ToX64(\n        uint8 decimals0,\n        uint8 decimals1,\n        uint160 sqrtPriceX96,\n        bool token0IsReserve0\n    ) internal pure returns (uint128 priceX64) {}\n```\n\nConverts 64.64 fixed point representation of the spotPrice into sqrt(spotPrice) as Q96.64 unnormalized on token decimals.\n\n```solidity\nfunction from64XSpotToSqrtRatioX96(\n        uint8 decimals0,\n        uint8 decimals1,\n        uint128 spot64X,\n        bool zeroForOne\n    ) internal pure returns (uint160 sqrtRatioX96) {}\n```\n\n### V2 Functions\n\nCalculates a v2 spot price from the pool reserves as a 64.64 fixed point number.\n\n```solidity\nfunction v2SpotPrice64x64(\n        uint112 reserve0,\n        uint112 reserve1,\n        uint8 decimals0,\n        uint8 decimals1\n    ) internal pure returns (uint128) {}\n```\n\nNormalizes v2 reserves to a target decimal.\n\n```solidity\nfunction v2NormalizeReserves(\n        uint112 _reserve0,\n        uint112 _reserve1,\n        uint8 decimals0,\n        uint8 decimals1,\n        uint8 _targetDecimals\n    ) internal pure returns (uint112 reserve0, uint112 reserve1) {}\n```\n\n### Extra CFMM Helpers\n\n```solidity\nfunction proportionalPriceDifferenceUnsigned(uint128 x, uint128 y)\n        internal\n        pure\n        returns (uint128)\n    {}\nfunction proportionalPriceDifferenceSigned(uint128 x, uint128 y)\n        internal\n        pure\n        returns (int128)\n    {}\n```\n\n### Standard Operation Functions\n\nConverts unsigned integer to 64.64 fixed point.\n\n```solidity\nfromUInt256(uint256 x)\n```\n\nConverts 64.64 fixed point to unsigned integer.\n\n```solidity\ntoUInt(uint128 x)\n```\n\nConverts 128.128 fixed point to 64.64 fixed point. \u003c/br\u003e\n\n```solidity\nfrom128x128(uint256 x)\n```\n\nAdds two 64.64 fixed point numbers. \u003c/br\u003e\n\n```solidity\nadd64x64(uint128 x, uint128 y)\n```\n\nComputes `a - b` where `a` is 64.64 fixed point, and `b` is a 64.64 fixed point. Returns unsigned 64.64 fixed point. \u003c/br\u003e\n```solidity\nsub64x64U(int128 x, int128 y)\n```\nComputes `a - b` where `a` is 64.64 fixed point, and `b` is  is 64.64 fixed point. Returns signed 64.64 fixed point. \u003c/br\u003e\n\n```solidity\nsub64x64I(int128 x, int128 y)\n```\n\nComputes the product of two 64.64 fixed point numbers. \u003c/br\u003e\n\n```solidity\nmul64x64(uint128 x, uint128 y)\n```\n\nComputes `a/b` where a \u0026 b are both 64.64 fixed point numbers. \u003c/br\u003e\n\n```solidity\ndiv64x64(uint128 x, uint128 y)\n```\n\nComputes `a/b` where a \u0026 b are both unsigned integers and returns the result as 64.64 fixed point number. \u003c/br\u003e\n\n```solidity\ndivuu(uint256 x, uint256 y)\n```\n\nComputes the absolute value of a signed integer. \u003c/br\u003e\n\n```solidity\nabs(int256 x)\n```\n\nComputes the binary exponent of a 64.64 fixed point number. \u003c/br\u003e\n\n```solidity\nexp_2(uint128 x)\n```\n\nComputes the square root of an unsigned integer and returns the result as 64.64 fixed point number.\u003c/br\u003e\n\n```solidity\nsqrtu(uint256 x)\n```\n\n# Additional Features Coming Soon\n\n1.) Derive input quantity from 2 v2 prices. \u003c/br\u003e\n2.) Simulate Tick Change on output V3 \u003c/br\u003e\n3.) Simulate amountIn on exact output sqrtPriceX96 V3. \u003c/br\u003e\n4.) DODO Architecture Integration \u003c/br\u003e\n5.) Curve Architecture Integration \u003c/br\u003e\n\nAdditionally feel free to open an issue on any features you would like integrated!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xosiris%2Fcfmm-math-libraries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xosiris%2Fcfmm-math-libraries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xosiris%2Fcfmm-math-libraries/lists"}