Package: curvesim
CurvesimCurvesim simulates Curve pools with optimal arbitrageurs trading against them to determine reasonable risk and reward parameters, such as amplitude (A) and fee, given historical price and volume feeds.Users can re-use simulation components to simulate custom strategies and generate custom metrics.  Pool objects enable simpler integration with Curve pools for both manual and automated analytics usage.Dependencies:Python versions 3.8 - 3.11 are supported.Primary package dependencies: scipy, numpy, pandas, altair, matplotlib, requests, web3, gmpy2When working on the codebase, to avoid dependency issues it is recommended to use the includedrequirements.txtfile in a Python virtual environment (venv).  Python 3.10 is required for this.DocumentationCheck out the full documentation athttps://curvesim.readthedocs.io/.  We recommend starting with the "Quickstart" guide.LicensingPortions of the codebase are authorized derivatives of code owned by Curve.fi (Swiss Stake GmbH).  These are the vyper snippets used for testing (test/fixtures/curve) and the python code derived from them (curvesim/pool/stableswapandcurvesim/pool/cryptoswap); there are copyright notices placed appropriately.  The rest of the codebase has an MIT license.Basic Use: AutosimThe autosim() function simulates existing Curve pools with a range of A and/or fee parameters. The function fetches pool properties (e.g., current pool size) and 2 months of price/volume data, runs multiple simulations in parallel, and returns a results object that can be introspected or generate charts.Curve pools from any chain supported by theConvex Community Subgraphscan be simulated directly by inputting the pool's address.Example:To simulate 3pool with the default configuration:importcurvesimres=curvesim.autosim("0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7")To simulate pools on chains other than Ethereum, use the "chain" argument:importcurvesim# run sim on Arbitrum 2Crvres=curvesim.autosim("0x7f90122BF0700F9E7e1F688fe926940E8839F353",chain="arbitrum")Simulation ResultsThe simulation returns a SimResults object that can plot simulation metrics or return them as DataFrames.Plotting results:#Plot results using Altairres.plot()#Save plot results as results.htmlres.plot(save_as="results.html")Example output:Summary statistics:>>>res.summary()metricpool_value_virtualpool_value...pool_volumeprice_errorstatannualized_returnsannualized_returns...summedian00.0035800.005156...2.286297e+090.00066910.0061580.007741...1.966299e+090.00060020.0077600.009348...1.652965e+090.00077530.0086110.010200...1.377299e+090.00095640.0037600.005439...2.400174e+090.000777.................590.0095230.012018...1.521524e+090.001155600.0037420.006247...2.388746e+090.001063610.0065330.009082...2.084530e+090.000915620.0083440.010894...1.775963e+090.000974630.0094020.011974...1.502494e+090.001133Timeseries data:>>>res.data()runtimestamp...pool_volumeprice_error002023-03-2123:30:00+00:00...15206414.5336330.005310102023-03-2200:30:00+00:00...7278720.409690.002029202023-03-2201:30:00+00:00...6125207.5530720.000100302023-03-2202:30:00+00:00...7066251.032950.000100402023-03-2203:30:00+00:00...3512782.0009450.000299..................93755632023-05-2119:30:00+00:00...879436.3315640.00089393756632023-05-2120:30:00+00:00...0.00.00109193757632023-05-2121:30:00+00:00...720837.8269710.00080093758632023-05-2122:30:00+00:00...445967.5061770.00141493759632023-05-2123:30:00+00:00...391060.9860220.000906Customizing Simulation ParametersBy default, pools are simulated using:on-chain or Curve Subgraph data about the poola broad range of A (16 values, 64 to 11,585) and fee (5 values, 0.02 to 0.06%) valuesCoinGecko price/volume dataall detected CPU coresHowever, all of these can be altered using optional keyword arguments.Custom A and/or Fee RangesCustom A and fee ranges can be specified using the "A" and "fee" arguments. Inputs must be lists or numpy arrays containing lists:importcurvesimimportnumpyasnp#Specify A values:res=curvesim.autosim('0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7',A=range(1000,2001,100))#Specify fees (0.03% and 0.04% with 10 decimal precision):res=curvesim.autosim('0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7',fee=[3000000,4000000])#Specify custom A range and 0.03% feeres=curvesim.autosim('0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7',A=range(1000,2001,100),fee=3000000)Additionally, a small number of A/fee values (2 each) can be set for testing purposes:res=curvesim.autosim('0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7',test=True)Overriding Simulation ParametersThe following parameters are automatically specified by autosim(), but can be overridden with keyword arguments:D: total deposit size; default: fetched from on-chain datavol_mult: multiplied by market volume to produce trade size limits; default: computed from Curve Subraph data (see Volume Limits for details)feemul: fee multiplier used in dynamic fee poolsimportcurvesim#Simulate 3pool assuming total deposit of $10B, fee = 0.03%res=curvesim.autosim('0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7',D=10000000000,fee=3000000)#For metapools, specifying D effects the deposit in the metapool, but not the basepool#Simulate USDN metapool assuming total deposit of $1B, fee = 0.03%res=curvesim.autosim('0x0f9cb53Ebe405d49A0bbdBD291A65Ff571bC83e1',D=1000000000,fee=3000000)#Simulate 3pool, limiting volume to 75% of market volume, fee = 0.03%#Note: it is not reccomended to adjust this parameter, try vol_mode instead (see below)res=curvesim.autosim('0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7',vol_mult=.75,fee=3000000)#Simulate hypothetical 3pool with dynamic fee like AAVE pool, fee = 0.03%res=curvesim.autosim('0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7',feemul=2*10**10,fee=3000000)Volume LimitsTo approximate realistic market conditions, the "vol_mult" argument is used to limit trade volume at each timepoint in the simulation. By default (vol_mode=1), vol_mult is simply the expected proportion of market volume that goes through the Curve pool (e.g., monthly pool volume / monthly price feed volume). At each timepoint, vol_mult is multiplied by the each coin-pair's market volume to produce a volume limit for each pair, thereby appropriately scaling trade volume while retaining natural volume dynamics. For metapools, vol_mult is computed seperately for the base pool and meta-pool.In some cases, it may be helpful to limit trade volume differently. In particular, for new coins with little volume for some (but not all) pairs included in the pool, more robust simulations can be achieved by assuming equal volumes across trading pairs. We therefore provide three volume-limiting modes (vol_mode):vol_mode = 1: limits trade volumes proportionally to market volume for each pair (default)vol_mode = 2: limits trade volumes equally across pairsvol_mode = 3: mode 2 for trades with meta-pool asset, mode 1 for basepool-only tradesWe reccomend using the default vol_mode 1 in most cases. However, if that returns noisy/uninterpretable results, it may be worth trying mode 2 (for normal pools) or mode 3 (for meta-pools).Data SourcesThe "src" argument can be used to choose between two different data sources:src = "coingecko": CoinGecko API (free); defaultsrc = "local": local data stored in the "data" folderNote that Nomics data is no longer supported since they went out of service.Note on CoinGecko DataCoingecko price/volume data is computed using all trading pairs for each coin, with volume summed across all pairs. Therefore, market volume taken from CoinGecko can be much higher than that of any specific trading pair used in a simulation. This issue is largely ameloriated by our volume limiting approach, with CoinGecko results typically mirroring results from pairwise data, but it should be noted that CoinGecko data may be less reliable than more granular data for certain simulations.Technical ParametersAdditionally, one can specify:ncpu: number of CPUs to use for parallel processing (default: all cores); for use with profilers, e.g.cProfile, usencpu=1.days: the number of days worth of data to use in the simulation (default: 60)