LNTrafficSimulator (lnsimulator package)

The lnsimulator Python package contains the Lightning Network (LN) traffic simulator used in the cryptoeconomic research of Ferenc Béres, István András Seres and András A. Benczúr.

Detailed documentation: https://lnsimulator.readthedocs.io/en/latest/

Introduction

In 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 by blog posts of LN node owners.

Cite

You can find our pre-print paper on 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 the lnsimulator package in your local environment then please follow the instruction below or have a look at the documentation.

Requirements

• UNIX or macOS environment
  • For 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).

Installation

After cloning the repository you can install the simulator with pip.

git clone https://github.com/ferencberes/LNTrafficSimulator.git
cd LNTrafficSimulator
python setup.py install

Data

By providing daily LN snapshots as input (you can bring and use your own!), our simulator models the flow of daily transactions.

i.) Download

You can download the data files, that we used in our research by executing the following command:

a.) Linux

bash ./scripts/download_data.sh
ls ln_data

b.) macOS

sh ./scripts/download_data.sh
ls ln_data

ii.) Content

After running the download_data.sh script 4 data files can be observed in the ln_data folder:

File	Simulator input?	Content
sample.json	Yes	sample JSON file containing a daily LN snapshot
ln_edges.csv	Yes	preprocessed LN snapshots in the form of a directed graph
1ml_meta_data.csv	Yes	merchant meta data that we downloaded from 1ml.com
ln.tsv	No	edge stream data about LN channels

You can also download the compressed data file with this link.

Usage

You must download the data as described in the Data section to use our simulator!

i.) Parameters:

Parameter	Description
amount	value of each simulated transaction in satoshis
count	number of random transactions to sample
epsilon	ratio of merchants among transactions endpoints
drop_disabled	drop temporarily disabled channels
drop_low_cap	drop channels with capacity less than amount
with_depletion	the available channel capacity is maintained for both endpoints

You can set the value of these parameters in a JSON configuration file.

ii.) Execution

You can run our LN traffic simulator with two different settings.

a.) Load data from preprocessed file

The default input format of the simulator is a directed graph representation of LN snapshots. In this case you must provide the snapshot_id (e.g. 0) and the output folder as parameters.

cd scripts
python run_simulator.py preprocessed 0 params.json YOUR_OUTPUT_DIR

b.) Load data from (custom) JSON file

You 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:

cd scripts
python run_simulator.py raw ../ln_data/sample.json params.json YOUR_OUTPUT_DIR

Note: If you have multiple CPUs at your disposal then we recommend setting a higher value for the max_threads parameter in the simulator script.

Note: runtime decreases significantly if you set find_alternative_paths=False in the simulator script. In this case base fee optimization is not executed.

iii.) Output

After execution you will find the output files in the provided YOUR_OUTPUT_DIR folder. The content of these files are as follows:

File	Content
params.json	Traffic simulator parameter values
lengths_distrib.csv	Length distribution of simulated transactions
router_incomes.csv	Contains the total routing income (satoshi) and the number of routed payments for LN nodes in a simulation
source_fees.csv	Contains the mean transaction costs (satoshi) and the number of sent payments for transaction initiator nodes
opt_fees.csv	For each router the estimated optimal increase in base fee and gain in daily routing income is presented

We provide detailed information on the output files here.

In order to get stable daily LN node statistics, we recommend to run the simulator for multiple times over several consecutive snapshots!

Acknowledgements

To Antoine Le Calvez (Coinmetrics) and Altangent Labs for kindly providing us their edge stream data and daily graph snapshots. To Domokos M. Kelen and Rene Pickhardt for 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.