From 881e0c2173068382264cafe264cf38cfcc739e9f Mon Sep 17 00:00:00 2001 From: akrtws <42371947+AngelaKTE@users.noreply.github.com> Date: Thu, 25 Feb 2021 11:35:45 +0100 Subject: [PATCH] Update NB1-BalancerAMM-V1.0.ipynb - text/instructions - all links checked --- NB1-BalancerAMM-V1.0.ipynb | 141 ++++++++++++++++--------------------- 1 file changed, 60 insertions(+), 81 deletions(-) diff --git a/NB1-BalancerAMM-V1.0.ipynb b/NB1-BalancerAMM-V1.0.ipynb index acb6c7e..a625967 100644 --- a/NB1-BalancerAMM-V1.0.ipynb +++ b/NB1-BalancerAMM-V1.0.ipynb @@ -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/)." ] @@ -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)" ] }, { @@ -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": [ @@ -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" @@ -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" ] }, { @@ -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)." ] }, { @@ -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)." ] }, { @@ -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\u001b[0m in \u001b[0;36m\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", @@ -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" ] }, { @@ -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, @@ -622,7 +601,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.5" + "version": "3.9.1" } }, "nbformat": 4,