Skip to content

NB update #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ramarti merged 1 commit into from
Feb 25, 2021
Merged

NB update #66

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 60 additions & 81 deletions NB1-BalancerAMM-V1.0.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@
"\n",
"### Pool address: 0x8b6e6E7B5b3801FEd2CaFD4b22b8A16c2F2Db21a -- 80% WETH - 20% DAI \n",
"\n",
"The Balancer Pool cadCAD model provides a core infrastructure for simulating Balancer Pools in the **Token Engineering design and verification process**.\n",
"The Balancer Pool cadCAD model provides a core infrastructure for simulating Balancer Pools in the **Token Engineering Design and Verification process**.\n",
"\n",
"It allows to simulate all types of Balancer Pool transactions and verify new designs and application cases. \n",
"In this notebook we plug **historical on-chain data** to the cadCAD model, and analyse **Pool Power** and **Pool Characteristics**.\n",
"It allows to simulate Balancer Pool transactions and verify new designs and application cases. \n",
"In this notebook we plug **historical on-chain data** to a cadCAD model, and analyse **Pool Power** and **Pool Characteristics**.\n",
"\n",
"For more information check out the [Balancer Simulations documentation](https://token-engineering-balancer.gitbook.io/balancer-simulations/)."
]
Expand All @@ -27,12 +27,12 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### System Specification\n",
"### A1.1 System Specification\n",
"System specification details are available in the Balancer Simulations documentation:\n",
"- [Differential Specification](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/balancer-simulations/nboverview)\n",
"- [Mathematical Specification](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/additional-code-and-instructions/balancer-the-python-edition/)\n",
"- [Model Architecture](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/balancer-simulations/nboverview)\n",
"- [Naming Convention](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/additional-code-and-instructions/naming-convention)"
"- [Differential Specification](https://token-engineering-balancer.gitbook.io/balancer-simulations/balancer-simulations/v10nboverview)\n",
"- [Mathematical Specification](https://token-engineering-balancer.gitbook.io/balancer-simulations/additional-code-and-instructions/balancer-the-python-edition/balancer_math.py)\n",
"- [Model Architecture](https://token-engineering-balancer.gitbook.io/balancer-simulations/balancer-simulations/v10nboverview)\n",
"- [Naming Convention](https://token-engineering-balancer.gitbook.io/balancer-simulations/additional-code-and-instructions/naming-convention)"
]
},
{
Expand Down Expand Up @@ -70,14 +70,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"This simulation is routing on-chain transaction data through the cadCAD model, adding USD price feeds. \n",
"For more information how to add transaction and price data please visit the [Balancer Simulations documentation](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/additional-code-and-instructions/transactions-pricefeeds). \n",
"(XX - remove spot price reference)"
"In this section you specify the Balancer Pool to be analyzed and run scripts to produce the'genesis_state', based on on-chain data. \n",
"\n",
"More information here: [Balancer Simulations documentation](https://token-engineering-balancer.gitbook.io/balancer-simulations/additional-code-and-instructions/onchaintransactions). "
]
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -86,8 +86,7 @@
"\n",
"from decimal import Decimal\n",
"\n",
"# Spot prices are needed for relevant notebooks and it's needed in the CadCAD model. Ignore this param here\n",
"# Spot price reference must be a symbol of a token in the pool in ALL_CAPS\n",
"# Spot price reference must be a symbol of a token in the pool in ALL_CAPS, you can ignore the spot price parameter for the simulations in this notebook.\n",
"parameters = {\n",
" 'spot_price_reference': ['DAI'],\n",
"}\n"
Expand All @@ -99,9 +98,10 @@
"source": [
"#### Import Pool Transactions and Initialize Pool state\n",
"\n",
"Pool Transactions, initial pool state and USD token prices are pulled from on-chain data collected in a .json file that has to be referenced here. \n",
"Genesis state, pool transactions, and (external) USD token prices are pulled from on-chain/API data collected in a .json file. \n",
"**Choose *your* Balancer Pool, and produce this .json file first, then add the file path below.**\n",
"\n",
"Learn more how to create this file using our parsing scripts in the [documentation](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/additional-code-and-instructions/transactions-pricefeeds).\n"
"Learn more how to create this file using parsing scripts in the [documentation](https://token-engineering-balancer.gitbook.io/balancer-simulations/v/master/additional-code-and-instructions/onchaintransactions).\n"
]
},
{
Expand Down Expand Up @@ -162,39 +162,8 @@
"source": [
"### B1.3 State Update Functions & Policies\n",
"\n",
"cadCAD state update functions replicate the following Balancer Pool Transactions (see system policies.py) \n",
"\n",
"\n",
"\n",
"**a) Add Liquidity**\n",
"= join policy \n",
"- `p_join_pool` (all-asset deposit)\n",
"- `p_join_swap_extern_amount_in` (single-asset deposit)\n",
"\n",
"\n",
"**b) Withdraw Liquidity**\n",
"= exit policy \n",
"- `p_exit_pool` (all-asset withdrawal) \n",
"- `p_exit_swap_extern_amount_out` (single-asset withdrawal) # NOTE, next version will use p_exit_swap_pool_amount_in\n",
"\n",
"**C) Swap**\n",
"= swap policy \n",
"- `p_swap_exact_amount_in` (out-given-in)\n",
"\n",
"\n",
"Balancer Pools offer additional transaction types:\n",
"- `p_swap_exact_amount_out` (in-given-out)\n",
"- `p_join_swap_pool_amount_out` (pool_out_given_single_in)\n",
"- `p_exit_swap_pool_amount_in`(single_out_given_pool_in)\n",
"Which is not applied in Balancer Simulations V1.0 since we are using only data from LOG_JOIN, LOG_EXIT and LOG_SWAP events from BPool contract. This does not provide information of the method selected by pool user.\n",
"\n",
"#### Fees\n",
"\n",
"Each `swap`, `join_swap` and `exit_swap` will have the pool collect a fee in the token goin into it. This fee is proportional to the `swap_fee` pool variable. We extract the token fee value from BMath methods and store it in `generated_fee_token_XX` state variables\n",
"\n",
" \n",
"\n",
"For a detailed description of the transactions, please visit the [Balancer Simulations documentation/Balancer Pool Functions](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/additional-code-and-instructions/balancer-the-python-edition/balancer-pool-functions)."
"Balancer Simulations replicate Balancer Pool Transactions in state update functions.\n",
"For a detailed description on how we implement transactions, please visit the [Balancer Simulations documentation/Balancer Pool Functions](https://token-engineering-balancer.gitbook.io/balancer-simulations/v/master/additional-code-and-instructions/balancer-the-python-edition/balancer-pool-functions)."
]
},
{
Expand All @@ -203,13 +172,12 @@
"source": [
"### B1.4 Partial State Update Blocks\n",
"\n",
"Partial State Update Blocks combine the following steps:\n",
"0. Skip initial action (pool creation)\n",
"1. Parse actions each timestemp and update the pool balances, weights, spot prices\n",
"2. Update external USD prices\n",
"3. Store action datetime\n",
"Partial State Update Blocks combine the following steps: \n",
"1. **Initialize pool**, generate genesis state\n",
"2. Compute subsequent **actions in discrete timesteps**, store datetime and update the pool state variables\n",
"3. Update external **USD prices in discrete timesteps**, and store datetime \n",
"\n",
"For more information please visit the [Balancer Simulations documentation/V1.0 Model Overview](https://app.gitbook.com/@token-engineering-balancer/s/balancer-simulation-portal/v/master/balancer-simulations/nboverview)."
"For more information please visit the [Balancer Simulations documentation/V1.0 Model Overview](https://token-engineering-balancer.gitbook.io/balancer-simulations/v/master/balancer-simulations/v10nboverview)."
]
},
{
Expand All @@ -231,24 +199,27 @@
"source": [
"### B1.5 Configuration\n",
"\n",
"A pool's state is updated by\n",
"- **actions** (such as swaps and external price updates) and\n",
"- **price signals** (USD values of tokens)\n",
"\n",
"These updates are captured in unique **timesteps**. 1 Timestep = 1 action (price signal or pool transaction). Each action has a datetime for time related analysis\n",
"\n",
"**steps_number** is automatically calculated from action json\n",
"\n",
"In most cases you might want to run the simulation across all timesteps included in your .json file - however you can specify any simulation range below.\n",
"\n",
"### Note: You need to start from the pool creation state, as seen in 0x123..._initial_pool_states.json "
"[cadCAD simulations](https://github.com/cadCAD-org/cadCAD/blob/master/documentation/README.md) support Monte Carlo runs, and parameter sweeps which are not applied in this notebook and can be ignored here. \n",
"Timesteps 'T' are defined by your pool's .json file, no need to make edits here."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"execution_count": 2,
"metadata": {},
"outputs": [
{
"ename": "NameError",
"evalue": "name 'result' is not defined",
"output_type": "error",
"traceback": [
"\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
"\u001b[0;31mNameError\u001b[0m Traceback (most recent call last)",
"\u001b[0;32m<ipython-input-2-825212656cea>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0msteps_number\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mresult\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'steps_number'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 2\u001b[0m \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'# Steps '\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msteps_number\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 3\u001b[0m sim_config = config_sim(\n\u001b[1;32m 4\u001b[0m {\n\u001b[1;32m 5\u001b[0m \u001b[0;34m'N'\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;31m# number of monte carlo runs\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
"\u001b[0;31mNameError\u001b[0m: name 'result' is not defined"
]
}
],
"source": [
"steps_number = result['steps_number']\n",
"print('# Steps ', steps_number)\n",
Expand Down Expand Up @@ -285,13 +256,14 @@
"source": [
"### B1.7 Simulation Output Preparation\n",
"\n",
"Post-processing (utils.py) separate complex variables (like pool and token prices) into independent variables, and adds metrics to the data frame, such as \n",
"- `token_k_values` \n",
"based on\n",
"Post-processing (utils.py) splits up state variable dictionaries, and adds metrics to the data frame, such as \n",
"- `token_total_value` (TVL)\n",
"- `generated_fees_(tokensymbol)` (fee collected per transaction)\n",
"- `token_k_values` (token value in USD) \n",
"based on \n",
"- `token_k_balances`\n",
"- `token_k_price` \n",
"and calculates accumulated values, such as\n",
"- `token_total_value` \n"
"\n"
]
},
{
Expand All @@ -318,16 +290,23 @@
"Below we show a range of plots exploring pool states in the simulation:\n",
"\n",
"**a) Pool Power:** \n",
"- D1.1 TVL (Total Value Locked, over time) compared to \n",
"- D1.1 Pool Size Growth (Number of tokens in the pool, over time) \n",
"- D1.2 Token Balances (individual balances, over time)\n",
"- C1.1 TVL (Total Value Locked, over time) compared to \n",
"- C1.1 Pool Size Growth (Number of tokens in the pool, over time) \n",
"- C1.2 Token Balances (individual balances, over time)\n",
"\n",
"**b) Pool Characteristics:** \n",
"- D1.3 Source of Pool Growth (Total Growth vs. Fees collected)\n",
"- D1.4 Token Ratio\n",
"- D1.5 Action Types"
"- C1.3 Source of Pool Growth (Total Growth vs. Fees collected)\n",
"- C1.4 Token Ratio\n",
"- C1.5 Action Types"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
},
{
"cell_type": "code",
"execution_count": null,
Expand Down Expand Up @@ -622,7 +601,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.5"
"version": "3.9.1"
}
},
"nbformat": 4,
Expand Down