---
title: "Introduction to Weighted AMM Impermanent Loss"
author: "Amber Krause"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to Weighted AMM Impermanent Loss}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction to Weighted AMM Impermanent Loss

### The Practical Justification 
Impermanent loss is a form of opportunity cost in which individuals who lend assets through Automated Market Maker lending pools can see a decrease in the currency value of their assets compared to the value they would have received by holding (HODL) their assets outside of the lending pool. When considering whether to lend or HODL, individuals balance the projected impermanent loss against the projected fees they will earn from lending. 

The **impermanentlosscalc** package allows users to calculate hypothetical Impermanent Loss (IL) and Net Profit and Loss (PnL) projections under a variety of projected price scenarios. 

A single function handles the more commonly used two asset Constant Function Market Maker (CFMM) pools, such as Uniswap and extends to $\mathbf{N}$-asset pools, such as Balancer.

---

### The Mathematical Principle

Tiruviluamala et al. (2023) showed that impermanent loss for an $\mathbf{N}$-asset pool can be calculated as $$
\text{IL} = \frac{\text{Geometric Mean of the } t_j\text{'s}}{\text{Arithmetic Mean of the } t_j\text{'s}} - 1
$$ where the $t_{j}$ represent the relative price changes for each asset in the pool. 


### Function: Impermanent Loss Calculation

As demonstrated in the referenced literature, impermanent loss is determined solely by the ratio of price change for each asset, making the calculation straightforward regardless of the number of assets. This function takes the following arguments:

* **prices_old** ($P_0$): The vector or array of **initial** asset prices for each token in the pool.
* **prices_new** ($P_t$): The vector or array of **final** asset prices for each token in the pool.
* **weights** ($w$): The relative weight of each asset in the pool (must sum to 1).
* **investment** ($V_0$): The total currency value of the initial investment.
* **fees**: The expected currency value of trading fees earned by the liquidity provider.

The function then produces the following outputs:

* **Value if held** ($V_H$): The final value of the portfolio if the given mix of assets were held outside the lending pool (the **Hold Portfolio**).
* **Value in pool** ($V_P$): The final value of the assets in the pool (the **Pool Portfolio**).
* **Impermanent loss percent** ($\text{IL\%}$): The percent of impermanent loss ($\frac{V_H - V_P}{V_H}$).
* **Nominal impermanent loss** ($\text{IL}$): The currency value of impermanent loss ($V_H - V_P$).
* **Fee offset**: The currency value of the trading fees earned for providing liquidity.
* **Net gain**: The final performance difference: $(\text{Value in pool} + \text{Fees}) - \text{Value if held}$.

---

#### Function Demonstration: Broad Applicability

###### Example 1: Standard Two-Asset Pool (50/50 Uniswap)

The most common AMMs use a **50/50** weight between two assets. If one asset doubles in price, we expect IL to be approximately **$5.7\%$**. This shows the package can be used as a standard IL calculator.

```{r ex1-5050, eval=TRUE}
# 50/50 Pool, Token 1 price doubles (100 -> 200)
library(impermanentlosscalc)
impermanent_loss(
  prices_old = c(100, 10),
  prices_new = c(200, 10),
  weights = c(0.5, 0.5), # Standard 50/50 weights
  investment = 1000,
  fees = 0,
  plot = FALSE
)
```

###### Example 2: Multi-Asset Pool (Balancer Type)
Though less common, multi asset AMM lending pools with unequal asset weights also exist. This function allows users to calculate impermanent loss for $\mathbf{N}$-asset pools with unequal weights. 

```{r ex2-multiasset, eval=TRUE}
# 20/40/40 Pool, Token 1 price triples (10 -> 30).
library(impermanentlosscalc)
impermanent_loss(
  prices_old = c(10, 10, 10),
  prices_new = c(30, 10, 10),
  weights = c(0.2, 0.4, 0.4), # Unequal weights for three assets
  investment = 1000,
  fees = 0,
  plot = FALSE
)
```

### Reference
Tiruviluamala, N., Port, A., & Lewis, E. (2022). A general framework for impermanent loss in automated market makers. arXiv preprint arXiv:2203.11352.

```{r session-info, echo=FALSE}
sessionInfo()

```