From 6144405175243b6ad5e2ab4e04b25b2a6d8f7741 Mon Sep 17 00:00:00 2001
From: Kris O'Shea <91485468+krisoshea-eth@users.noreply.github.com>
Date: Tue, 17 Sep 2024 03:30:54 +0100
Subject: [PATCH] add LiquidityAmounts Reference guide with mdx formatting
 (#759)

---
 .../v4/reference/core/LiquidityAmounts.mdx    | 133 ++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 docs/contracts/v4/reference/core/LiquidityAmounts.mdx

diff --git a/docs/contracts/v4/reference/core/LiquidityAmounts.mdx b/docs/contracts/v4/reference/core/LiquidityAmounts.mdx
new file mode 100644
index 000000000..641741dbd
--- /dev/null
+++ b/docs/contracts/v4/reference/core/LiquidityAmounts.mdx
@@ -0,0 +1,133 @@
+---
+title: LiquidityAmounts
+---
+
+The `LiquidityAmounts` library provides functions for computing liquidity amounts from token amounts and prices in Uniswap V4.
+
+# Key Concept: sqrtPriceX96
+
+`sqrtPriceX96` represents the square root of the price ratio of token1 to token0, multiplied by 2^96. This representation allows for precise price calculations across a wide range of values while using fixed-point arithmetic. It's more efficient than using ticks for intermediate calculations, as it avoids frequent conversions between prices and ticks.
+
+# Functions
+
+## getLiquidityForAmount0
+
+```solidity
+function getLiquidityForAmount0(uint160 sqrtPriceAX96, uint160 sqrtPriceBX96, uint256 amount0)
+internal
+pure
+returns (uint128 liquidity)
+```
+
+Computes the amount of liquidity received for a given amount of token0 and price range.
+
+| Param Name     | Type    | Description                                   |
+|----------------|---------|-----------------------------------------------|
+| sqrtPriceAX96  | uint160 | Square root of price at first tick boundary   |
+| sqrtPriceBX96  | uint160 | Square root of price at second tick boundary  |
+| amount0        | uint256 | The amount of token0 being sent in            |
+
+Returns the amount of liquidity received.
+
+## getLiquidityForAmount1
+
+```solidity
+function getLiquidityForAmount1(uint160 sqrtPriceAX96, uint160 sqrtPriceBX96, uint256 amount1)
+internal
+pure
+returns (uint128 liquidity)
+```
+
+Computes the amount of liquidity received for a given amount of token1 and price range.
+
+| Param Name     | Type    | Description                                   |
+|----------------|---------|-----------------------------------------------|
+| sqrtPriceAX96  | uint160 | Square root of price at first tick boundary   |
+| sqrtPriceBX96  | uint160 | Square root of price at second tick boundary  |
+| amount1        | uint256 | The amount of token1 being sent in            |
+
+Returns the amount of liquidity received.
+
+## getLiquidityForAmounts
+
+```solidity
+function getLiquidityForAmounts(
+uint160 sqrtPriceX96,
+uint160 sqrtPriceAX96,
+uint160 sqrtPriceBX96,
+uint256 amount0,
+uint256 amount1
+) internal pure returns (uint128 liquidity)
+```
+
+Computes the maximum amount of liquidity received for given amounts of token0 and token1, the current pool prices, and the prices at the tick boundaries.
+
+| Param Name     | Type    | Description                                   |
+|----------------|---------|-----------------------------------------------|
+| sqrtPriceX96   | uint160 | Current square root price of the pool         |
+| sqrtPriceAX96  | uint160 | Square root of price at first tick boundary   |
+| sqrtPriceBX96  | uint160 | Square root of price at second tick boundary  |
+| amount0        | uint256 | The amount of token0 being sent in            |
+| amount1        | uint256 | The amount of token1 being sent in            |
+
+Returns the maximum amount of liquidity received.
+
+## getAmount0ForLiquidity
+
+```solidity
+function getAmount0ForLiquidity(uint160 sqrtPriceAX96, uint160 sqrtPriceBX96, uint128 liquidity)
+internal
+pure
+returns (uint256 amount0)
+```
+
+Computes the amount of token0 for a given amount of liquidity and a price range.
+
+| Param Name     | Type    | Description                                   |
+|----------------|---------|-----------------------------------------------|
+| sqrtPriceAX96  | uint160 | Square root of price at first tick boundary   |
+| sqrtPriceBX96  | uint160 | Square root of price at second tick boundary  |
+| liquidity      | uint128 | The liquidity being valued                    |
+
+Returns the amount of token0.
+
+## getAmount1ForLiquidity
+
+```solidity
+function getAmount1ForLiquidity(uint160 sqrtPriceAX96, uint160 sqrtPriceBX96, uint128 liquidity)
+internal
+pure
+returns (uint256 amount1)
+```
+
+Computes the amount of token1 for a given amount of liquidity and a price range.
+
+| Param Name     | Type    | Description                                   |
+|----------------|---------|-----------------------------------------------|
+| sqrtPriceAX96  | uint160 | Square root of price at first tick boundary   |
+| sqrtPriceBX96  | uint160 | Square root of price at second tick boundary  |
+| liquidity      | uint128 | The liquidity being valued                    |
+
+Returns the amount of token1.
+
+## getAmountsForLiquidity
+
+```solidity
+function getAmountsForLiquidity(
+uint160 sqrtPriceX96,
+uint160 sqrtPriceAX96,
+uint160 sqrtPriceBX96,
+uint128 liquidity
+) internal pure returns (uint256 amount0, uint256 amount1)
+```
+
+Computes the token0 and token1 value for a given amount of liquidity, the current pool prices, and the prices at the tick boundaries.
+
+| Param Name     | Type    | Description                                   |
+|----------------|---------|-----------------------------------------------|
+| sqrtPriceX96   | uint160 | Current square root price of the pool         |
+| sqrtPriceAX96  | uint160 | Square root of price at first tick boundary   |
+| sqrtPriceBX96  | uint160 | Square root of price at second tick boundary  |
+| liquidity      | uint128 | The liquidity being valued                    |
+
+Returns the amount of token0 and token1.
\ No newline at end of file