Update NB1-BalancerAMM-V1.0.ipynb

- text/instructions
- all links checked

Author: AngelaKTE

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<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",
@@ -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,