README.md

---

Bancor Simulator

---

Bancor Simulator is an open-source python package developed by Bancor Research. It aims to assist the design, testing, and validation of Bancor v3 tokenomics.

See official documentation for complete details.

Warning: The docs are a work in progress with potentially broken links, unfinished sections, and a non-exhaustive overview of commands and example usage. Moreover, the entirety of the codebase and documentation is subject to change without warning.

---

Introduction

All state transition functions and accompanying data structures described in the product specification BIP15: Proposing Bancor 3 are the core system level operations of this library.

Organization

This is the project directory structure:

bancor_research/                   <------- ** General Research Project **
└───── bancor_emulator/            <------- Solidity Emulation Project
   └── bancor_simulator/           <------- ** Spec & Simulation Project **
      │   ├── v3/                  <------- Current Version
      │   └── simulation/          <------- Agent-based simulation module
      │   │     └── agents.py      <------- Mesa Agent-based implementations of the Bancor protocol.
      │   │     └── batch_run.py   <------- Script used to perform a parameter sweep.
      │   │     └── model.py       <------- Main Bancor Simulation module interface.
      │   │     └── random_walk.py <------- Generalized behavior for random walking
      │   │     └── run.py         <------- Runs the simulation server with browser-based UI
      │   │     └── server.py      <------- Configures the browser-based interface.
      │   │     └── utils.py       <------- Misc utility functions
      │   │ 
      │   └── spec/                <------- State transition functions and data structures described in BIP15.
      │         └── actions.py     <------- Deposit, trade, & withdrawal algorithm logic.
      │         └── emulation.py   <------- Verifies solidity result parity.
      │         └── network.py     <------- Main BancorDapp application interface.
      │         └── rewards.py     <------- Autocompounding and standard rewards logic.
      │         └── state.py       <------- State variables, constants, data structures, and CRUD interfaces.
      │         └── utils.py       <------- Misc utility functions
      │ 
      └── main.py                  <------- Application

** These docs apply.

Notation

Code snippets appearing in this style are to be interpreted as Python 3 code.

Formatting & Style

Code is formatted according to PEP8, which is the official Python style guide. In order to overcome the burden on the developers to fix formatting, we use Black which reports on format errors and automatically fixes them.

Project setup

If you don't already have one, create a virtualenv using these instructions

Install

Bancor3 Simulation is available for Python 3.6+

To install using pypi, run this command:

$ pip install bancor-research

Documentation

In addition to the codebase, this repository holds the Jupyter Book source for Bancor v3 Simulation: A hands-on demo of features described in BIP15: Proposing Bancor 3.

To make a change to the jupyter book and update:

1. Get your copy of this repository:

   git clone https://github.com/bancorprotocol/research
   

Build and preview the jupyter-book text locally

To build locally, pip install -r requirements.txt and then jupyter-book build .

Follow the build instructions on the Jupyter Book guide. The guide has information on how to use the Jupyter Book CLI to build this book. You can find the Jupyter Book build instructions here.

Build and preview the text locally

To build locally, pip install -r requirements.txt and then jupyter-book build .

Follow the build instructions on the Jupyter Book guide. The guide has information on how to use the Jupyter Book CLI to build this book. You can find the Jupyter Book build instructions here.