# Balancer Research Group - Initial Parameters of LBPs - Sensitivity Analysis
<br></br>


<br></br>

---

Chris Kagabe | [e-artifacts](https:///www.e-artifacts.com),
Vasileios Panagiotidis | [e-swissolar](http://www.e-swissolar.ch)

### **Using the balancerV2cad model we run a sensitivity analysis with cadCAD. Moreover we created a streamlit application that displays the results. With this tool we would like to help newcomers to easily get started with balancer and LBPs**

# Introduction

A Liquidity Bootstraping Pool (LBP) is a use-case (template) of smart-pools in Balancer V2 for Liquidity Bootstrapping also refered as Configurable Rights Pool (CRP). Smart pools are privately controled pools. Owners of LBPs have the flexibility to configure their pools by changing parameters,like weights or swap-fees [[1]](#References).

# Background
LBPs are helping teams to distribute their tokens and create liquidity for their projects. Ideally teams aiming to reach their funding goal by distributing as many tokens as possible as soon as possible.

LBPs were conceived with the following key considerations:
* Be able to build liquidity without a large amounts of upfront capital
* Be able to build a vault for their funds to fit risk profile of stakeholders and funding goal
* Be able to distribute token even the if their unit price stays constant.

LBP can be configured in a way that the price of the token starts high in the beginning and then gradually declines with time [3].

## Examples of Successful LBP Launches

LBPs seems to be an optimal choice for many projects, since they can distribute their tokens with little investment. Some good examples are:

* HydraDX a Polkadot project executed a LBP -> [link](https://medium.com/balancer-protocol/balancer-facilitates-record-high-liquidity-bootstrapping-pool-for-hydradx-f08b6b0a3aee)
* Radical's Liquidity Bootstrapping Event -> [link](https://lbp.radicle.network/)

# Use-Case

Alice have heard about LBPs in balancer und how these can be used to crowdfund her project. She is new in Balancer and she was wandering about how the pool could be optimally set-up.

She and her friend Bod decided to run simulations with cadCAD in order to gain as much information as possible. They want to use all the information during the campaign for developing the best funding strategy and how to respont effectively to possible critical market situations.

## Assumptions
The funding goal of Alice (project owner) has been set to 100 Token_B. Based on an external valuation the value of the token has been estimated to 1 Token_B. As a result she will mint 100 project tokens (Token_A).The sales period will last three weeks. The price of the reserve token (Token_B) will be set constant for all simulations.

## Objective
**Conduct a [Dutch Auction](https://en.wikipedia.org/wiki/Dutch_auction) using a balancer pool to distribute 100 Token_A within 99 hours at an average price of 1 Token_B**

# Research Topics and Question
* Understand how amount of tokens distributed change over sweeping initial parameters.
* Which paramater is the most important for achieving 100% token distribution.

# Research Approach
The best way to answer the research questions is to conduct a a sensitivity analysis.

## Sensitivity Analysis
Sensitivity Analysis is the process of passing different inputs to a model to see how the outputs change. The general model for the sensitivity analysis model as follows:

y=f(X)
X=[x1,x2,...,xn]

**where:**

y: Model output
X: Model input matrix
xi: Value if i-th x variable

# Implementation Approach

## The balancer V2 python model

The BalancerV2 model is a python implementation of the balancerv2 protocol funded by Balancer and the Token Engineering community in collaboration with Ocean Protocol and PowerPool.
Fore more information read the BalancerV2 Simulations Documentation -> [link](https://metavision.gitbook.io/balancerv2-py-twin/)

For our simulation we used the following modules:

* **WeightedMath**: The file contains the calculations for a weighted pool. -> [link](https://metavision.gitbook.io/balancerv2-py-twin/code-and-instructions/balancer_py_edition/weightedpool.py)

With **calc_out_given_in** we computed how many Token_A can be taken out of a pool in `tokenAmountIn` are sent, given the current balances. [link](https://metavision.gitbook.io/balancerv2-py-twin/code-and-instructions/balancer_py_edition/weightedpool.py#calc_out_given_in)

delta_decrease_balance_Token_A = 
	WeightedMath.calc_out_given_in(
	Decimal(bp._balances['Token_B']),						 
	Decimal(bp._weights['Token_B']),
	Decimal(bp._balances['Token_A']),
	Decimal(parameter),
	Decimal(initial_state['amount_token_B']))

* **WeightedPool**: This file contains all the functions that enable a weighted pool to take actions such as swapping or joining a pool. -> [link](https://metavision.gitbook.io/balancerv2-py-twin/code-and-instructions/balancer_py_edition/weightedpool.py-1)

With **join_pool** we created a pool and initialised balances and weights [link](https://metavision.gitbook.io/balancerv2-py-twin/code-and-instructions/balancer_py_edition/weightedpool.py-1#join_pool)

bp.join_pool(
    {'Token_A':100,
     'Token_B':100},
     'Token_A':0.5,
     'Token_B':0.5}
)

## cadCAD

cadCAD (complex adaptive dynamics Computer-Aided Design) is a python based modeling framework for research, validation, and Computer Aided Design of complex systems. For more information visit the web-site of cadCAD -> [link](https://cadcad.org/#rec126507217)

For our simulations we are using the Standard Notbook Layout of cadCAD

## Modelling

### Standard Scenario
**Initial Parameters:**

Binding Tokens: Token_A/Token_B
Balances: 100/100
Weights: 50/50:
SwapFee: 0%

### Initial State

A state variable is one of the set of variables that are used to describe the mathematical “state” of a dynamical system. Intuitively, the state of a system describes enough about the system to determine its future behaviour in the
absence of any external forces affecting the system. [[6]](#References)

The initial state of the model have been set as follows:

initial_state = {
    'balance_of_Token_A': bp._balances['Token_A'],
	'balance_of_Token_B': bp._balances['Token_B'],
	'weight_of_token_A': bp._weights['Token_A'],
	'weight_of_token_B': bp._weights['Token_B'],
    'swap_fee': Decimal(bp._swap_fee),
    'amount_token_B': Decimal(1.0000),
}

### System Parameters
Parameter Sweeping is a cadCAD feature that runs a model under different possible parameterizations. Parameter sweeping is especially helpful in sensitivity analysis, where we are interested in exploring the effects of changing a parameter. [[5]](#References).

For the system parameters and for every parameter we defined the range to sweep for every parameter. For example for the weights of Token_A as follows:

PARAMS_TO_SWEEP = {
    #Creates 5 distict values between 0.5 and 0.99
    "par_weight_token_A": np.linspace(0.5, 0.99, 5),
}

### Policy Function

A Policy Function computes one or more signals to be passed to State Update Functions. Policy functions are passing the decrease of balance Token_A to the state ubdate function

def p_decrease_balance_Token_A(
params, substep, state_history, previous_state):
    parameter = params['par_weight_token_A']    
    delta_decrease_balance_Token_A = WeightedMath.calc_out_given_in(...)
    ...
    return {'update_balance_Token_A': delta_decrease_balance_Token_A}

### State Update Function

State Update Functions represent equations according to which the state variables change over time. We used the signal from the policy function to update the balance of Token_A.

def s_update_balance_of_Token_Α(
params, substep, state_history, previous_state, policy_input):    
    balance_of_token_A = 
    previous_state['balance_of_Token_A'] 
    - policy_input['update_balance_Token_A']        
    return 'balance_of_Token_A', balance_of_token_A

### Partial State Update Blocks

A Partial State Update Block is a set of State Update Functions and Policy Functions. Partial State Update Blocks are passed to `append_configs`.

partial_state_update_blocks = [
    {
        'policies': {
            'update_balance_Token_A': p_decrease_balance_Token_A,
        },
        'variables': {
            'updated_balance_of_token_A': s_update_balance_of_Token_Α,
        }
    }
]

# Resarch Results

We plot the results using the `animation_frame='par_weight_token_A'` of plotly


# Discussion
tbd
# Further Research Questions
* Sensitivity Analysis on Total Value Locked
* More analysis of the results providing
# Possible Next Steps
tbd
# Further Ressources

BalancerV2cad - Sensitivity Analysis Web App -> [link](https://share.streamlit.io/le-kag/balancerv2cad-lbp-web-app/main/app.py)

# References
1. Liquidity Bootstrapping Pools https://balancer.gitbook.io/balancer/guides/smart-pool-templates-gui/liquidity-bootstrapping-pool
2. FAQ Liquidity Bootstrapping Pools https://docs.balancer.fi/v/v1/smart-contracts/smart-pools/liquidity-bootstrapping-faq
3. Building Liquidity into Token Distribution
https://medium.com/balancer-protocol/building-liquidity-into-token-distribution-a49d4286e0d4
4. Copper - A new way forward
https://medium.com/alchemistcoin/copper-a-new-way-forward-f6ac45302b07
5. Parameter Sweeping introduced https://github.com/cadCAD-org/cadCAD/issues/79
6. Definition State Variable
https://en.wikipedia.org/wiki/State_variable