diff --git a/docs/osmosis-core/modules/concentrated-liquidity/README.md b/docs/osmosis-core/modules/concentrated-liquidity/README.md index ad70b47c3..daebddf99 100644 --- a/docs/osmosis-core/modules/concentrated-liquidity/README.md +++ b/docs/osmosis-core/modules/concentrated-liquidity/README.md @@ -23,7 +23,7 @@ similar to a limit order with order-books. The traditional Balancer AMM relies on the following curve that tracks current reserves: -$$xy = k$$ +![eq-1](./img/eq-1.png) This formula allows for distributing liquidity along the $xy=k$ curve and across the entire price range of (0, ∞). @@ -35,42 +35,47 @@ it functions as the traditional `xy = k` within that range. In the new architecture, real reserves are described by the following formula: -$$(x + L / \sqrt P_u)(y + L \sqrt P_l) = L^2$$ +![eq-2](./img/eq-2.png) Where `P_l` is the lower tick, `P_u` is the upper tick, and `L` is the amount -of liquidity provided, $$L = \sqrt k$$ +of liquidity provided, +![eq-4](./img/eq-4.png) + This formula stems from the original $xy = k$ but with a limited range. In the traditional design, a pool's `x` and `y` tokens are tracked directly. However, with the concentrated design, we only track $L$ and $\sqrt P$, which can be calculated with: +![eq-5](./img/eq-5.png) + By rearranging the above, we obtain the following formulas to track virtual reserves: +![eq-6](./img/eq-6.png) + Note the square root around price. By tracking it this way, we can utilize the following core property of the architecture: -$$L = \Delta y / \Delta \sqrt P$$ +![eq-7](./img/eq-7.png) Since only one of the following changes at a time: - $L$: When an LP adds or removes liquidity -- $\sqrt P$: When a trader swaps +- sqrt P: When a trader swaps We can use the above relationship to calculate the outcome of swaps as well as pool joins that mint shares. Conversely, we calculate liquidity from the other token in the pool: -$$\Delta x = \Delta \frac {1}{\sqrt P} L$$ +![eq-8](./img/eq-8.png) + Overall, the architecture's goal is to enable LPs to provide concentrated liquidity within a specific range while maintaining high capital efficiency. @@ -84,7 +89,8 @@ in a concentrated liquidity pool. The price [p] corresponding to a tick [t] is defined by the equation: -$$ p(t) = 1.0001^t $$ +![eq-9](./img/eq-9.png) + This results in a .01% difference between adjacent tick prices. This does not, however, allow for control over the specific prices that the ticks correspond @@ -111,30 +117,30 @@ since only every 100 ticks are able to be initialized. When $exponentAtPriceOne = -6$ (and tick spacing is 100), each tick starting at 0 and ending at the first factor of 10 will represents a spot price increase of 0.0001: -- $tick_{0} = 1$ -- $tick_{100} = 1.0001$ -- $tick_{200} = 1.0002$ -- $tick_{300} = 1.0003$ +- tick_{0} = 1 +- tick_{100} = 1.0001 +- tick_{200} = 1.0002 +- tick_{300} = 1.0003 This continues until the pool reaches a spot price of 10. At this point, since the pool has increased by a factor of 10, the $exponentAtCurrentTick$ increases from -4 to -3 (decreasing the incremental precision), and the ticks will increase as follows: -- $tick_{8999900} = 9.9999$ -- $tick_{9000000} = 10.000$ -- $tick_{9000100} = 10.001$ -- $tick_{9000200} = 10.002$ +- tick_{8999900} = 9.9999 +- tick_{9000000} = 10.000 +- tick_{9000100} = 10.001 +- tick_{9000200} = 10.002 For spot prices less than a dollar, the precision factor decreases (increasing the incremental precision) at every factor of 10: -- $tick_{-100} = 0.99999$ -- $tick_{-200} = 0.99998$ -- $tick_{-500100} = 0.94999$ -- $tick_{-500200} = 0.94998$ -- $tick_{-9000100} = 0.099999$ -- $tick_{-9000200} = 0.099998$ +- tick_{-100} = 0.99999 +- tick_{-200} = 0.99998 +- tick_{-500100} = 0.94999 +- tick_{-500200} = 0.94998 +- tick_{-9000100} = 0.099999 +- tick_{-9000200} = 0.099998 This goes on in the negative direction until it reaches a spot price of 0.000000000000000001 or in the positive direction until it reaches a spot @@ -154,40 +160,46 @@ since $exponentAtPriceOne$ is fixed), we can then calculate how many ticks must be crossed in order for $k$ to be incremented ( $geometricExponentIncrementDistanceInTicks$ ). -$$geometricExponentIncrementDistanceInTicks = 9 * 10^{(-exponentAtPriceOne)}$$ +![eq-10](./img/eq-10.png) + -Since we define $exponentAtPriceOne$ and utilize this as the increment starting +Since we define exponentAtPriceOne and utilize this as the increment starting point instead of price zero, we must multiply the result by 9 as shown above. In other words, starting at 1, it takes 9 ticks to get to the first power of 10. Then, starting at 10, it takes 9\*10 ticks to get to the next power of 10, etc. Now that we know how many ticks must be crossed in order for our -$exponentAtPriceOne$ to be incremented, we can then figure out what our change -in $exponentAtPriceOne$ will be based on what tick is being traded at: +exponentAtPriceOne to be incremented, we can then figure out what our change +in exponentAtPriceOne will be based on what tick is being traded at: -$$geometricExponentDelta = ⌊ tick / geometricExponentIncrementDistanceInTicks ⌋$$ +![eq-11](./img/eq-11.png) + -With $geometricExponentDelta$ and $exponentAtPriceOne$, we can figure out what -the $exponentAtPriceOne$ value we will be at when we reach the provided tick: +With geometricExponentDelta and *exponentAtPriceOne*, we can figure out what +the *exponentAtPriceOne* value we will be at when we reach the provided tick: -$$exponentAtCurrentTick = exponentAtPriceOne + geometricExponentDelta$$ + +![eq-13](./img/eq-13.png) -Knowing what our $exponentAtCurrentTick$ is, we must then figure out what power +Knowing what our *exponentAtCurrentTick* is, we must then figure out what power of 10 this $exponentAtPriceOne$ corresponds to (by what number does the price gets incremented with each new tick): -$$currentAdditiveIncrementInTicks = 10^{(exponentAtCurrentTick)}$$ +![eq-12](./img/eq-12.png) + Lastly, we must determine how many ticks above the current increment we are at: -$$numAdditiveTicks = tick - (geometricExponentDelta * geometricExponentIncrementDistanceInTicks)$$ +![eq-14](./img/eq-14.png) + With this, we can determine the price: -$$price = (10^{geometricExponentDelta}) + (numAdditiveTicks * currentAdditiveIncrementInTicks)$$ +![eq-15](./img/eq-15.png) + -where $(10^{geometricExponentDelta})$ is the price after $geometricExponentDelta$ -increments of $exponentAtPriceOne$ (which is basically the number of decrements +where (10^{geometricExponentDelta}) is the price after $geometricExponentDelta$ +increments of *exponentAtPriceOne* (which is basically the number of decrements of difference in price between two adjacent ticks by the power of 10) ### Tick Spacing Example: Tick to Price @@ -195,7 +207,8 @@ of difference in price between two adjacent ticks by the power of 10) Bob sets a limit order on the `USD<>BTC` pool at tick 36650010. This pool's $exponentAtPriceOne$ is -6. What price did Bob set his limit order at? -$$geometricExponentIncrementDistanceInTicks = 9 * 10^{(6)} = 9000000$$ +![eq-16](./img/eq-16.png) + Bob set his limit order at price $16,500.10 @@ -214,12 +227,14 @@ Bob set his limit order at price $16,500.10 Bob sets a limit order on the `USD<>BTC` pool at price $16,500.10. This pool's $exponentAtPriceOne$ is -6. What tick did Bob set his limit order at? -$$geometricExponentIncrementDistanceInTicks = 9 * 10^{(6)} = 9000000$$ +![eq-17](./img/eq-17.png) + We must loop through increasing exponents until we find the first exponent that is greater than or equal to the desired price -$$currentPrice = 1$$ +![eq-18](./img/eq-18.png) + 10 is less than 16,500.10, so we must increase our exponent and try again -$$currentAdditiveIncrementInTicks = 10^{(-5)} = 0.00001$$ +![eq-19](./img/eq-19.png) + 100 is less than 16,500.10, so we must increase our exponent and try again. This goes on until... -$$currentAdditiveIncrementInTicks = 10^{(-2)} = 0.01$$ +![eq-20](./img/eq-20.png) + 100000 is greater than 16,500.10. This means we must now find out how many additive tick in the currentAdditiveIncrementInTicks of -2 we must pass in order to reach 16,500.10. +![eq-21](./img/eq-21.png) + Bob set his limit order at tick 36650010 @@ -287,11 +306,12 @@ As explained previously, the exponent at price one determines how much the spot price increases or decreases when traversing ticks. The following equation will assist in selecting this value: -$$exponentAtPriceOne=log_{10}(\frac{D}{P})$$ +![eq-22](./img/eq-22.png) + ### Example 1 @@ -301,12 +321,12 @@ BTC is trading at $28,000 per BTC We want to create a SHIB/BTC concentrated liquidity pool where SHIB is the baseAsset (asset0) and BTC is the quoteAsset (asset1). In terms of the quoteAsset, we want to increment in 10 cent values. - -$$P=(\frac{0.00001070}{28,000})=0.000000000382142857$$ +![eq-23](./img/eq-23.png) + We can therefore conclude that we can use an exponent at price one of -5 (slightly under precise) or -6 (slightly over precise) for this base/quote pair @@ -319,11 +339,13 @@ Flipping the quoteAsset/baseAsset, for BTC/SHIB, lets determine what the exponentAtPriceOne should be. For SHIB as a quote, centralized exchanges list prices at the 10^-8, so we will set our desired increment to this value. -$$P=(\frac{28,000}{0.00001070})=2616822429$$ + +![eq-24](./img/eq-24.png) + We can therefore conclude that we can use an exponent at price one of -3 for this base/quote pair and desired price granularity. This means we would diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-1.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-1.png new file mode 100644 index 000000000..b6e7bada0 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-1.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-10.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-10.png new file mode 100644 index 000000000..71ee328ce Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-10.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-11.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-11.png new file mode 100644 index 000000000..8fdcf71f4 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-11.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-12.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-12.png new file mode 100644 index 000000000..27d2afec0 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-12.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-13.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-13.png new file mode 100644 index 000000000..43dec4fc6 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-13.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-14.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-14.png new file mode 100644 index 000000000..dad63d52c Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-14.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-15.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-15.png new file mode 100644 index 000000000..67acd71d9 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-15.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-16.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-16.png new file mode 100644 index 000000000..d5f746a49 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-16.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-17.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-17.png new file mode 100644 index 000000000..eaad164b4 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-17.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-18.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-18.png new file mode 100644 index 000000000..890e9269d Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-18.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-19.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-19.png new file mode 100644 index 000000000..d6d619ead Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-19.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-2.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-2.png new file mode 100644 index 000000000..ceb22542b Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-2.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-20.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-20.png new file mode 100644 index 000000000..b8cbd6269 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-20.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-21.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-21.png new file mode 100644 index 000000000..e43d57f0e Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-21.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-22.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-22.png new file mode 100644 index 000000000..87de41714 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-22.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-23.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-23.png new file mode 100644 index 000000000..fa095031a Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-23.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-24.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-24.png new file mode 100644 index 000000000..0e7987410 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-24.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-3.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-3.png new file mode 100644 index 000000000..ced6349ff Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-3.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-4.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-4.png new file mode 100644 index 000000000..b2593eb59 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-4.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-5.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-5.png new file mode 100644 index 000000000..6c1c9ad24 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-5.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-6.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-6.png new file mode 100644 index 000000000..928b46c87 Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-6.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-7.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-7.png new file mode 100644 index 000000000..9d5b5643a Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-7.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-8.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-8.png new file mode 100644 index 000000000..ee5cd275b Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-8.png differ diff --git a/docs/osmosis-core/modules/concentrated-liquidity/img/eq-9.png b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-9.png new file mode 100644 index 000000000..a903fb54d Binary files /dev/null and b/docs/osmosis-core/modules/concentrated-liquidity/img/eq-9.png differ