add back virtual reserves

amm-math.md

@@ -22,9 +22,11 @@ $\phi$ denotes the fee parameter.
 
 $d_b$ denotes the days until maturity that all newly purchases bonds will be purchased at.
 
+$s$ denotes the total supply of lp
+
 $t_{stretch}$ denotes the time stretch parameter.
 
-$k$ is the yield space constant. For a given $\tau$, $k  = \frac{c}{\mu}(\mu z)^{1-\tau} + (y)^{1-\tau}$.
+$k$ is the yield space constant. For a given $\tau$, $k  = \frac{c}{\mu}(\mu z)^{1-\tau} + (y+s)^{1-\tau}$.
 
 Given $d$ days until maturity, $t(d)$ = $\frac{d}{365}$.
 
@@ -33,7 +35,7 @@ Given $d$ days until maturity, $\tau(d) = \frac{t(d)}{t_{stretch}}$.
 The AMM quotes the price of bonds in terms of base using the share reserves $z$, the bond reserves $y$, and a given amount of days until maturity $d$:
 
 $$
-p = (\frac{y}{\mu z})^{-\tau(d)}
+p = (\frac{y+s}{\mu z})^{-\tau(d)}
 $$
 
 ## Add Liquidity
@@ -44,42 +46,42 @@ Suppose an LP supplies $\Delta x$ base tokens. The amount of shares the LP is pr
 
 The share reserves are updated as $z = z + \Delta z$.
 
-Consider as motivating fact:
-
-$$ \frac{y_{old}}{z_{old}} = \frac{y_{new}}{z_{new}} \implies p_{old} = p_{new} \implies r_{old} = r_{new} $$
-
-Since we can calculate the current spot price from the reserves and share prices and the current APR from the current spot price, we can calculate the current pool APR $r$. We can substitute the updated share reserves $z = z + \Delta z$ to calculate the new bond reserves:
-
-$$
-y_{new} = y_{old} \cdot \frac {z+\Delta z}{z}$$
-
-Upon initialization, either the initializer will either explicitly set the value of the bond reserves or they will provide a target interest rate that is used along with the share reserves to solve for the bond reserves:
+Since we can calculate the current spot price from the reserves and share prices and the current APR from the current spot price, we can calculate the current pool APR $r$. Using the calculation from the "Virtual Reserves Calculation" appendix, we can substitute the updated share reserves $z = z + \Delta z$ to calculate the new bond reserves:
 
 $$
-y = \mu z \cdot p^{\frac{-1}{\tau(d)}} = \mu z \cdot (1 - r
-\cdot t(d))^{\frac{1}{\tau(d)}}
+y = \frac{z + \Delta z}{2} \cdot (\mu \cdot (1 + r \cdot t(d))^{\frac{1}{\tau(d)}} - c)
 $$
 
 ### LP Tokens
 
-When the LP token supply is equal to zero, the choice of LP tokens is arbitrary since the new LP will hold all of the LP tokens. In this case, the LP will receive LP tokens $\Delta l = \Delta x$. In all other cases, we must utilize an LP token calculation that ensures fairness for previous LPs. New LPs should be able to withdraw exactly the amount of base they contributed at the time of providing liquidity. Therefore, we need the new LP's maximum withdrawal amount to equal the capital that they put in.
+When the LP token supply is equal to zero, the choice of LP tokens is arbitrary since the new LP will hold all of the LP tokens. In this case, the LP will receive LP tokens $\Delta l = \Delta x$. In all other cases, we must utilize an LP token calculation that ensures fairness for previous LPs. 
 
 From the "Remove Liquidity" section, the amount withdrawn for a given amount of LP tokens $\Delta l$ is:
 
 $$
 c \cdot (z - b_z) \cdot \frac{\Delta l}{l}
 $$
 
+However, we need the LP share to be derived from the total value backing the LP and not just the amount available to withdraw.  To do this, we zero out $b_z$ giving us:
+
+$$
+c \cdot z \cdot \frac{\Delta l}{l}
+$$
+
+:::info:::
+**Note:** Zeroing out the z buffer protects existing LPs from an attack where someone longs, LPs a large amount, sells the bond and removes their LP for a profit at the expense of LPs. The side effect of this is that new LPs shares are diluted by the existing open positions.  
+:::
+
 Substituting in $z = z + \Delta z$ and $l = l + \Delta l$ and setting this equal to $c \cdot \Delta z$, we get:
 
 $$
-c \cdot \Delta z = c \cdot ((z + \Delta z) - b_z) \cdot \frac{\Delta l}{l + \Delta l}
+c \cdot \Delta z = c \cdot (z + \Delta z) \cdot \frac{\Delta l}{l + \Delta l}
 $$
 
 We can solve this for $\Delta l$, the new LP tokens:
 
 $$
-\Delta l = \frac{\Delta z \cdot l}{z - b_z}
+\Delta l = \frac{\Delta z \cdot l}{z}
 $$
 
 We update the LP balances so that $l_t$ (the LP balance of the trader providing liquidity) is $l_t = l_t + \Delta l$ and the global LP balance $l$ is $l = l + \Delta l$.
@@ -96,7 +98,7 @@ Suppose a trader attempts to withdraw liquidity for an amount of LP tokens $\Del
 
 #### Withdrawal
 
-Since this AMM uses a virtual reserves system for the bond reserves, an LP can only ever withdraw base assets. The total amount of withdrawable shares is $z - b_z$ as this is the maximum amount of shares that can be removed while still satisfying the invariant $z \geq b_z$. This implies that the total amount of base that can be withdrawn is given by $c(z - b_z)$. LP withdrawals are executed pro-rata given the amount $\Delta l$ of LP tokens being withdrawn. From this, the amount of base withdrawn by redeeming $\Delta l$ LP tokens is:
+Since this AMM uses a virtual reserves system for the bond reserves, an LP can only ever withdraw base assets. LP withdrawals are executed pro-rata given the amount $\Delta l$ of LP tokens being withdrawn. From this, the amount of base withdrawn by redeeming $\Delta l$ LP tokens is:
 
 $$
 \Delta x = c \cdot \Delta z = c \cdot (z - b_z) \cdot \frac{\Delta l}{l}
@@ -112,10 +114,10 @@ Next we update the trader's LP balance so that $l_t = l_t - \Delta l$ and the gl
 
 The share reserves are updated as $z = z - \Delta z$. 
 
-The $y$ reserves are updated to maintain the current APR. Using the formula in the introduction, we simply preserve the reserve ratio to preserve the price.
+The $y$ reserves are updated to maintain the current APR. Using the calculation from the "Virtual Reserves Calculation" appendix, we can substitute the updated share reserves $z = z - \Delta z$ to calculate the new bond reserves:
 
 $$
-y_{new} = \frac{y_{old}(z - \Delta z)}{z}
+y = \frac{z - \Delta z}{2} \cdot (\mu \cdot (1 + r \cdot t(d))^{\frac{1}{\tau(d)}} - c)
 $$
 
 :::warning
@@ -133,13 +135,13 @@ We can immediately convert the base amount into the amount of shares the trader
 We must solve for $\Delta y$, the amount of bonds that the trader should receive. We'll start by solving for the change in $y$ without accounting for fees, $\Delta y'$. The YieldSpace invariant is given by:
 
 $$
-\frac{c}{\mu} \cdot (\mu \cdot (z + \Delta z))^{1 - \tau(d_b)} + (y - \Delta y')^{1 - \tau(d_b)} = k.
+\frac{c}{\mu} \cdot (\mu \cdot (z + \Delta z))^{1 - \tau(d_b)} + (y +s - \Delta y')^{1 - \tau(d_b)} = k.
 $$
 
 Solving this for $\Delta y'$ yields:
 
 $$
-\Delta y' = y - (k - \frac{c}{\mu} \cdot (z + \Delta z)^{1-\tau(d_b)})^{\frac{1}{1-\tau(d_b)}}
+\Delta y' = y+s - (k - \frac{c}{\mu} \cdot (z + \Delta z)^{1-\tau(d_b)})^{\frac{1}{1-\tau(d_b)}}
 $$
 
 The fees for the purchase we charge on the interest implied by this purchase the face value of the bonds minus what was paid, $f$ are paid in bonds and are given by:
@@ -177,13 +179,13 @@ The amount of base the trader receives is given by $\Delta x = c \cdot \Delta z$
 We must solve for $\Delta z$, the amount of shares the trader should receive. We'll start by solving for the amount of shares the trader would receive without fees $\Delta z'$. The YieldSpace invariant is given by:
 
 $$
-\frac{c}{\mu} \cdot (\mu \cdot (z - \Delta z'))^{1 - \tau(d)} + (y + \Delta y)^{1 - \tau(d)} = k.
+\frac{c}{\mu} \cdot (\mu \cdot (z - \Delta z'))^{1 - \tau(d)} + (y+s + \Delta y)^{1 - \tau(d)} = k.
 $$
 
 Solving this for $\Delta z'$ yields:
 
 $$
-\Delta z' = z - \mu^{-1} \cdot (\frac{\mu}{c} \cdot (k - (y + \Delta y)^{1-\tau(d)}))^{\frac{1}{1-\tau(d)}}
+\Delta z' = z - \mu^{-1} \cdot (\frac{\mu}{c} \cdot (k - (y + s + \Delta y)^{1-\tau(d)}))^{\frac{1}{1-\tau(d)}}
 $$
 
 The fees for the sale, $f$, will be paid in the base asset and are given by:
@@ -241,7 +243,7 @@ The bond buffer will be updated as $b_y = b_y + \Delta y$.
 
 For the remainder of the accounting, we'll consider the accounting to be indexed by the trader and the block timestamp at the time of opening the short.
 
-The trader will add base which will be converted to $ \frac{\Delta y}{c} - \Delta z$ shares in their margin account to cover the maximum loss scenario.
+The trader will add base which will be converted to $\frac{\Delta y}{c} - \Delta z$ shares in their margin account to cover the maximum loss scenario.
 
 The accounts receivable will be increased by $\Delta z$.
 
@@ -260,19 +262,19 @@ Suppose a trader requests to close $\Delta y$ bonds of a short position that mat
 We must solve the YieldSpace invariant to find $\Delta z$. We'll start with solving for the shares that will be paid for the bonds without fees $\Delta z'$. The YieldSpace invariant is given by:
 
 $$
-\frac{c}{\mu} \cdot (\mu \cdot (z + \Delta z'))^{1 - \tau(d)} + (y - \Delta y) ^ {1 - \tau(d)} = k
+\frac{c}{\mu} \cdot (\mu \cdot (z + \Delta z'))^{1 - \tau(d)} + (y + s - \Delta y) ^ {1 - \tau(d)} = k
 $$
 
 Solving this for $\Delta z'$ gives:
 
 $$
-\Delta z' = \mu^{-1} \cdot (\frac{\mu}{c} \cdot (k - (y - \Delta y)^{1 - \tau(d)}))^{\frac{1}{1 - \tau(d)}} - z
+\Delta z' = \mu^{-1} \cdot (\frac{\mu}{c} \cdot (k - (y + s - \Delta y)^{1 - \tau(d)}))^{\frac{1}{1 - \tau(d)}} - z
 $$
 
 Computing the fee for this purchase is more complicated than for other trades because attempting to use the same method yields a potentially intractable algebra problem (TODO: Continute trying to solve this). With this in mind, the following is a good approximation of the other fee calculations. 
 
 $$
-f = \phi \cdot (\Delta y - \Delta x) 
+f = \phi \cdot (1 - p) \cdot \Delta y
 $$
 
 Now that we have $\Delta z'$ and $f$, we can calculate that $\Delta z = \Delta z' + \frac{f}{c}$.
@@ -319,16 +321,16 @@ $$
 p = 1 - r \cdot t(d)
 $$
 
-Combining this with our other expression for $p$, we find that:
+Combining this with our other expression for $p$ and substituting $s \approx y + cz$, we find that:
 
 $$
-(\frac{y}{\mu z})^{-\tau(d)} = 1 - r \cdot t(d)
+(\frac{2y + cz}{\mu z})^{\tau(d)} = 1 + r \cdot t(d)
 $$
 
 Solving this for the bond reserves $y$, we find that the bond reserves need to target a rate of $r$ are given by:
 
 $$
-y = \mu z \cdot (1 - r \cdot t(d))^{\frac{-1}{\tau(d)}}
+y = \frac{z}{2} \cdot (\mu \cdot (1 + r \cdot t(d))^{\frac{1}{\tau(d)}} - c)
 $$
 
 :::warning
@@ -348,23 +350,59 @@ In each of our actions, we ensure that $z \geq b_z$ and that $y \geq b_y$. In th
 ### 1. Adding Liquidity
 
 Let:
+- $c = 2$ (1 share is worth 2 base)
+- $\mu = 1.5$ (1 share was initially worth 1.5 base)
+- $d = 182.5$ (6 months until maturity)
 - $z = 100,000$ (share reserves of 100,000 currently worth 200,000 base)
 - $b_z = 10,000$ (share buffer of 10,000)
 - $y = 150,000$ (bond reserves of 150,000)
 - $l = 100,000$ (LP token supply of 100,000)
+- $t_{stretch} = 22.1868770169$ (a time stretch targeting an APY of 5%)
+- $t(d) = \frac{182.5}{365} = 0.5$ (term length of 6 months)
+- $\tau(d) = \frac{t(d)}{t_{stretch}} = 0.02253584403$ (this follows from the choice of the other values)
 - $\Delta z = 20,000$
 
-Then we calculate the new y as 
+#### Calculating Bond Reserves
 
-$$ y_{new} = \frac{y_{old} \cdot (z + \Delta z)}{z} = \frac{150,000 \cdot (100,000 + 20,000)}{100,000} = 180,000 $$
+To calculate the bond reserves after the liquidity provision, we must first calculate the current pool APR. We'll use the formula for APR in terms of price. The pool's spot price is given by:
 
-The new LP shares are:
+$$
+p = (\frac{2 \cdot 150,000 + 2 \cdot 100,000}{1.5 \cdot 100,000})^{-0.02253584403} = 0.973232237529
+$$
 
-$$ \Delta l = \frac{\Delta z \cdot l}{z - b_z} = \frac{20,000 \cdot 100,000}{100,000 - 10,000} = 22,222.\overline{2} $$
+The pool's current APR is given by:
 
-The depositor was credited with 22,222. We confirm there's no loss on immediate withdraw:
+$$
+r = \frac{1 - 0.973232237529}{0.973232237529 \cdot 0.5} = 0.05500796508528476 \approx 5.5\%
+$$
 
-$$ (z-b_z) \cdot \frac {\Delta l}{l} = 110,000 \cdot \frac{22,222}{122,222} = 19999.83$$
+Now that we have the pool's current APR, we calculate the bond reserves that will preserve the pool's current APR after the new influx of liquidity ($\Delta z$ shares) as:
+
+$$
+y = \frac{100,000 + 20,000}{2} \cdot (1.5 \cdot (1 + 0.05500796508528476 \cdot 0.5)^{\frac{1}{0.02253584403}} - 2 = 180000.00000000032
+$$
+
+To verify that this calculation preserves the pool's APR, we calculate the pool's spot price and see that it is the same as before (the price is the only value that could change in the rate formula):
+
+$$
+p = (\frac{2 \cdot 180000.00000000032 + 2 \cdot 120,000}{1.5 \cdot 120,000})^{-0.02253584403} = 0.973232237529
+$$
+
+#### Calculating New LP Tokens
+
+The new LP tokens are calculated as:
+
+$$
+\Delta l = \frac{20,000 \cdot 100,000}{100,000} = 20,000
+$$
+
+The amount of base that the new LP can withdraw is:
+
+$$
+2 \cdot (120,000) \cdot \frac{20,000}{120,000} = 40,000
+$$
+
+$40,000$ base is equivalent to $20,000$ shares since the share price is $2$, so the LP is able to fully withdraw the capital that they contributed at the time of contribution.
 
 
 ### 2. Removing Liquidity
@@ -389,7 +427,7 @@ $$ (z-b_z) \cdot \frac {\Delta l}{l} = 110,000 \cdot \frac{22,222}{122,222} = 19
 
 ### 7. Current APR Calculation
 
-Let $p^{-1} = 0.96$ (the price of one bond is 0.96 base), $d = 182.5$ (6 months remaining), and $t(d) = \frac{182.5}{365} = 0.5$. 
+Let $p = 0.96$ (the price of one bond is 0.96 base), $d = 182.5$ (6 months remaining), and $t(d) = \frac{182.5}{365} = 0.5$. 
 
 We can calculate the rate as $r = \frac{1 - 0.96}{0.96 \cdot 0.5} = 0.08\overline{3}$.
 
@@ -405,15 +443,10 @@ Let:
 - $t(d) = \frac{182.5}{365} = 0.5$ (term length of 6 months)
 - $\tau(d) = \frac{t(d)}{t_{stretch}} = 0.02253584403$ (this follows from the choice of the other values)
 
-$$
-y = 1.5 \cdot 100,000 \cdot (1 - 0.05 \cdot 0.5)^{\frac{-1}{0.02253584403}} = 461315.17
-$$
-
 
-Then we have that the midpoint price is:
 
-$$ p = (\frac{461315.17}{150000})^{-0.02253584403} = 0.975 $$
+Using the formula from the "Virtual Reserve Calculations" appendix, we calculate the bond reserves as:
 
-This gives an interest rate of just over 5%, because the purchase price of the bond is slighly less than 0.025 cents earned by the bond over the period.
-
-$$ r = \frac{1 - p}{p \cdot t(d)} = \frac {0.025}{0.975 \cdot 0.5} = 0.05128205128 $$ 
+$$
+y = \frac{100,000}{2} (1.5 \cdot (1 + 0.05 \cdot 0.5)^{\frac{1}{0.02253584403}} - 2) \approx 124,346.5
+$$