Package: carbon-simulator
Carbon SimulatorDISCLAIMERTHIS SIMULATOR IS PROVIDED TO STUDY AND EXAMINE THE CARBON SMART CONTRACT SYSTEM. IT SHOULD
NOT BE RELIED UPON TO TAKE PART IN EXECUTION CHAIN OF SOME ACTUAL TRANSACTIONSThe simulator is a work in progress with potentially broken features, 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. Having said this -- we will make an effort to keep the interface backwards compatible so that existing code will not break.About CarbonCarbon is decentralized exchange infrastructure that gives users the ability to create automated flexible trading strategies on-chain. Its key technical features are adjustable parametric bonding curves, asymmetric concentrated liquidity, and an efficient routing algorithm.This simulator has been developed byBancor Researchto assist in the design, testing, and validation of Carbon strategies. It can be run interactively in a Jupyter notebook environment, or via Python scripting.The permament Github URL for this repo isbancorprotocol/carbon-simulator. There is a second repo that is optimised forBinderand that is located atbancorprotocol/carbon-simulator-binder. The latter uses the version of the library in thePyPi package, so it may be a week or two behind. The Carbon project website is atcarbondefi.xyz. On this site you will find in particular thelitepaper,whitepaper, andinformation disclosurefor the patent application. The simulator in its latest released version can also be accessed as JupyterLite version atsimulator.bancordefi.xyz. The associated repo is atbancorprotocol/carbon-simulator-jupylite.Getting startedIf you already have Python and Jupyter installed, you can launch a Jupyter instance in the root directory of the project by runningjupyter notebookand then opening the notebookCarbonSim-Example.ipynb, or any of the other notebooks in that directory.You may run into missing modules that need to be installed via pip. In this case, either install them manually based on the list inrequirements.txtandrequirements_ui.txtor refer to the instructions below. We also recommend to installJupyText.Project setupThe project should be able to run in anyPython3 environmentwith the correct dependenciesinstalled via pip. If you start from aConda installation, most dependencies should already be available. Nevertheless we recommendsetting up a virtual environmentto ensure libraries installed for this project do not collide with other Python modules installed on the system.Whilst this simulation is designed to run in any Python environment, we strongly recommend running it inJupyter Notebooksfor the convenience they provide.Method 1. Quick setupNavigate to the top level project directory and start the Jupyter server:$ jupyter notebookThen run the notebookCarbonSim-Example.ipynbor any of the other notebooks. If you are getting import errors, make sure all modules fromrequirements.txtandrequirements_ui.txtare installed, eg by running$ pip install -r requirements.txt
$ pip install -r requirements_ui.txtor by installing the required modules manually.The upside of this method is that you get started quickly and easily, and -- more importantly -- you have access to all the bleeding feautures in thebetabranch should you choose to check out beta instead of main. It also allows you to easily make changes to the library code. The downside is that thecarbonlibrary may only work for notebooks and scripts located in the root directory of this project.Method 2. Pip installWe are publishing this repo topypi:carbon-simulatorso you can install it with the usual$ pip install carbon-simulatorThis installs the latest version published on themainbranch of the repo, as well as all dependencies. We also recommend installingJupyTextfor easier management of the notebooks. In the unexpected case of conflicts with your local installation, consider using avirtual environment.When installing this way there will not be any example workbooks provided. We recommend downloading the workbooks fromhereto get started, starting withCarbonSim-Example.ipynb. Note that you will only have access to the features in themainbranch of the repo in this case.Method 3. Installation via setupThis method will install thecarbonpackage as well as all its dependencies on your system. We highly recommend to do thisin a virtual environment, in which case no permanent changes will be made. To install the simulator, navigate to the top level project directory, and run the installation process via$ python setup.py installThen again you launch a Jupyter session running the following command$ jupyter notebookAs thecarbonlibrary is now installed on your system, you can run the simulation code from anywhere whilst the virtual environment is active. Note that outside the project directory, you only have access the branch of the repo that was checked out at the time you ran setup. Inside the project director itshouldpick up whatever branch you have checked out, but this may depend on your system configuration.UsageThere are numerous usage examples in the Jupyter notebooks in the root directory of this project, and we refer to those for more elaborate examples. A very basic example for a simulation is the one fromCarbonSim-Example.ipynb:from carbon import CarbonSimulatorUI

# Set up a simulator instance, with default pair ETHUSDC
Sim = CarbonSimulatorUI(pair="ETHUSDC")

# Add a strategy. This strategy is initially seeded with 10 ETH
# and 10000 USDC. It will selling ETH between 2000-2500 USDC per ETH,
# making the received USDC available for sale. It will also be buying ETH 
# between 1000-750 USDC per ETH.
Sim.add_strategy("ETH", 10, 2000, 2500, 10000, 1000, 750)

# We can look at this order by examining the simulator state
Sim.state()["orders"]

# Someone is now trading against the pool, BUYING 1 ETH.
# The price will be driven by the 2000-2500 range.
Sim.trader_buys("ETH", 1)

# We see that that 1 ETH disappeared from the ETH curve,
# and reappeared as USDC on the other curve
Sim.state()["orders"]

# Someone is trading against the pool, SELLING 1 ETH.
# The price will be driven by the 1000-750 range
Sim.trader_sells("ETH", 1)

# Now the ETH curve is at 10 ETH, where it was initially.
# We have however taken profits of about USD 2021 on the 
# USDC account.
Sim.state()["orders"]Branches and versioningBranchesThis repo contains two key branches,main, andbeta. Their respective properties are as follows:main. The main branch is the main release branch of this project, and this is the only branch that is available onPyPi. It is currently updated from beta every 1-2 weeks. The main branch will never be rewritten.beta. The beta branch contains the latest features of the project. It will have usually passed the test suite, so should not be broken in obvious ways. The beta branch will usually be rewritten before it is merged into main, which happens every 1-2 weeks.VersioningWe usesemantic versioning(major.minor.patch), so the major number is changed on backward incompatible API changes, the minor number on compatible changes, and the patch number for patches and incremental changes that do not merit an increase in the minor version number.The API in this respect is defined as"all public methods in theSimulationUI"object, as well as those in the objects it returns (currentlyCarbonPairandCarbonOrderUI).Note that all modules contained incarbon.helpersarenotpart of the public API, and breaking changes can occur in those at any point in time. If you are using them in your own code, we recomend copying the module(s) you are using into your own codebase.The in-library location of those objects isnotpart of the API, they need to be imported from the top level. There may be additional objects in the top-level of the library that are not currently considered part of the API. As of version 1.0, those objects areExactRouterX0Y0Nandanalyticswhich we do not currently consider in a state suitable for semantic versioning.Modules may have version numbers of their own. Those are mostly for use of the dev team and they do not follow any specific policies.Change logv2.4.1added resources/routing area; cleaned up resources; SDK encode, decode; CarbonOrderUI yzABS; removed deprecated notebooks; CPC serialization, constructors and plots; benchmark bugfixv2.4README; CarbonOrderUI prettification; precision analysis; BaseRouter parameters as dict; benchmarks; SDK; HOURLY data set; SharedVar; ConstantProductCurve with reference NB063; additional parameters for CarbonOrderUI and as_cpc and reference book NB062; iseq; matching method test; CPCContainerv2.3.2CarbonPair display, decimals; strategy from_dct improvements; sim-related helpers including soltest, floatint; CarbonOrderUI yzABSv2.3.1cryptocompare; run_shift parameter fix; sim: colors and local use; ubuy/sell; various sim improvements; cryprocompare aggregate query; routing and benchmarking; workflowsv2.3consolidation and benchmark release with minor fixes (including for uni v3 style strategies) to the features introduced since v2.2v2.2.5-6pdcompare allows inversion; dealing with numeric issues; params improvements; path interpolation; removed yaml; print_version, plt_style; numeric bugfixv2.2.4marginal price at init; also yint, but still issues; added HODL and better legend to sim; strategy object; SharedVar; NBTest bugfix; adding PathGenerator to helpers; adding StartConditions to simulation; adding uniswap constructor to strategy; adding CryptoCompare to data and helpers; updated various helpers for market data, including scalingv2.2.1-3- created Demo 7-3 (key sim); created carbon.helpers module; widgets (for Demo 7-4 which is 7-3 with widgets); Binder optimizationsv2.2- benchmarks, alpha optimizer, fls, fast router, ob test, partial fill, limit amounts, CarbonOrderUI v1.6, notes folder; NBTest 46-51; Demo 3-8, 4-2, 4-3, 5-8, 7-1, 7-2v2.1- new order book methodology, improved NBTest, added functionality to CarbonOrderUY, added CarbonCurves notebook, updated demo 3-2 to the new order book codev2.0- slash notation for pair (breaking); disabled curves; remove aliases; order book functions and marginal price routing in CarbonOrderUIv1.1-5- order books; alpha router and other routers; thresholds; analytics; more examples and demoes; binder links; match constant; exclude futurev1.0- initial release