Package: lnsimulator
LNTrafficSimulator (lnsimulator package)ThelnsimulatorPython package contains the Lightning Network (LN) traffic simulator used in the cryptoeconomicresearchofFerenc Béres,István András Seresand András A. Benczúr.Detailed documentation:https://lnsimulator.readthedocs.io/en/latest/IntroductionIn our work, we designed a traffic simulator to empirically study LN’s transaction fees and privacy provisions. The simulator relies only on publicly available data of the network structure and capacities, and generates transactions under assumptions that we validated based on information spread byblog postsof LN node owners.CiteYou can find our pre-printpaperon arXiv. Please cite our work if you use our traffic simulator or the LN data that we provided.@article{beres2019cryptoeconomic,
  title={A Cryptoeconomic Traffic Analysis of Bitcoin's Lightning Network},
  author={B\'eres, Ferenc and  Seres, Istv{\'a}n Andr{\'a}s and Bencz\'ur, Andr{\'a}s A.},
  journal={arXiv preprint arXiv:1911.09432},
  year={2019}
}What's in it for me?We think that our simulator can be of interest mainly for two types of people: LN node owners and researchers. Hence, the simulator can answer the following questions of interest for these people:i.) LN node owners, routers:What is the optimal fee I could charge for transactions going through my node in order to maximise my routing profits?What is my expected income from routing with respect to certain parameters (topology, traffic, transacted amounts)?How various parameters (topology, traffic, transacted amounts) affect the profitability of my nodes?ii.) Researchers:What is the optimal fee nodes can charge? How far is it (if at all) from on-chain fees?What is the path length distribution of transactions on the LN graph? How much anonymity do they provide?How profitable is it to run a router node? Who are the most profitable ones?Is everyone altruistic on the LN transaction fee market?How various parameters (topology, traffic, transacted amounts) affect the profitability of each node?You can try our simulator in an online docker image using.If you prefer installing thelnsimulatorpackage in your local environment then please follow the instruction below or have a look at thedocumentation.RequirementsUNIX or macOS environmentFor macOS users: you need to have wget (brew install wget)This package was developed in Python 3.5 (conda environment) but it is recommended to use recent Python versions (3.7, 3.8).InstallationAfter cloning the repository you can install the simulator withpip.gitclonehttps://github.com/ferencberes/LNTrafficSimulator.gitcdLNTrafficSimulator
pythonsetup.pyinstallDataBy providing daily LN snapshots as input(you can bring and use your own!), our simulator models the flow of daily transactions.i.) DownloadYou can download the data files, that we used in our research by executing the following command:a.) Linuxbash./scripts/download_data.sh
lsln_datab.) macOSsh./scripts/download_data.sh
lsln_dataii.) ContentAfter running thedownload_data.shscript 4 data files can be observed in theln_datafolder:FileSimulator input?Contentsample.jsonYessample JSON file containing a daily LN snapshotln_edges.csvYespreprocessed LN snapshots in the form of a directed graph1ml_meta_data.csvYesmerchant meta data that we downloaded from1ml.comln.tsvNoedge stream data about LN channelsYou can also download the compressed data file with thislink.UsageYou must download the data as described in the Data section to use our simulator!i.) Parameters:ParameterDescriptionamountvalue of each simulated transaction in satoshiscountnumber of random transactions to sampleepsilonratio of merchants among transactions endpointsdrop_disableddrop temporarily disabled channelsdrop_low_capdrop channels with capacity less thanamountwith_depletionthe available channel capacity is maintained for both endpointsYou can set the value of these parameters in a JSONconfiguration file.ii.) ExecutionYou can run our LN traffic simulator with two different settings.a.) Load data from preprocessed fileThe default input format of the simulator is a directed graph representation of LN snapshots. In this case you must provide thesnapshot_id(e.g. 0) and theoutput folderas parameters.cdscripts
pythonrun_simulator.pypreprocessed0params.jsonYOUR_OUTPUT_DIRb.) Load data from (custom) JSON fileYou can execute the simulator on custom data as well, by providing daily LN snapshot as a JSON file (e.g.lnd). See the example below:cdscripts
pythonrun_simulator.pyraw../ln_data/sample.jsonparams.jsonYOUR_OUTPUT_DIRNote:If you havemultiple CPUsat your disposal then we recommend setting a higher value for themax_threadsparameter in the simulatorscript.Note:runtime decreases significantly if you setfind_alternative_paths=Falsein the simulatorscript. In this case base fee optimization is not executed.iii.) OutputAfter execution you will find the output files in the provided YOUR_OUTPUT_DIR folder. The content of these files are as follows:FileContentparams.jsonTraffic simulator parameter valueslengths_distrib.csvLength distribution of simulated transactionsrouter_incomes.csvContains the total routing income (satoshi) and the  number of routed payments for LN nodes in a simulationsource_fees.csvContains the mean transaction costs (satoshi) and the  number of sent payments for transaction initiator nodesopt_fees.csvFor each router the estimated optimal increase in base fee  and gain in daily routing income is presentedWe provide detailed information on the output fileshere.In order to get stable daily LN node statistics, we recommend to run the simulator for multiple times over several consecutive snapshots!AcknowledgementsTo Antoine Le Calvez (Coinmetrics) and Altangent Labs for kindly providing us their edge stream data and
daily graph snapshots. ToDomokos M. KelenandRene Pickhardtfor insightful discussions. To our reviewers,
Christian Decker, Cyril Grunspan and to our anonymous reviewer for their invaluable comments. Support
from Project 2018-1.2.1-NKP-00008: Exploring the Mathematical Foundations of Artificial Intelligence and
the “Big Data—–Momentum” grant of the Hungarian Academy of Sciences.