Repository files navigation

The itCoin Payment Channel Network (PCN) Simulator is based on a combination ofCloTH, a state-of-the-art simulator of the Lightning Network, andROSS, a framework for parallel discrete event simulations.The target topology for the simulator is aSemi-Hierarchical PCN, a special topology based on a three-tier structure that corresponds to the traditional financial system. The repo also includes a topology generator for Semi-Hierarchical PCNs.

• Python 3.11 or later (with dev/distutils)

• Poetry: please, follow theofficial installation instructions.

• OpenMPI

  OpenMPI howto on Fedora (click to open)

  If you are runningFedora you will need to execute once:

  dnf install openmpi-devel

  Also,each time you open a new shell to run the project you will need toactivate the openmpi environment, running:

  source /etc/profile.d/modules.shmodule load mpi/openmpi-x86_64

1. Clone theitcoin-pcn-simulator repository:

   cd~git clone https://github.com/bancaditalia/itcoin-pcn-simulator.git

2. Build the simulator:

   cd~/itcoin-pcn-simulatormkdir buildcd buildcmake -DCMAKE_BUILD_TYPE=Release ..make

To generate network topologies, follow these steps:

1. Set up the poetry environment:

   cd~/itcoin-pcn-simulator/utilitiespoetry shellPYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyringpoetry install

2. Generate a topology. In this example, we create a topology representing three nations (Italy, Finland, Cyprus), each with proportions based on their real-world geographic sizes. Different topologies will be generated for each specified--capacity-fractions, using channel capacities defined in the--model-params-file. These topologies will be partitioned into the specified-k number of partitions, and the output will be stored in the--output-dir:

   cd~/itcoin-pcn-simulator/utilitiespoetry shellmkdir -p ../experiments/workspace/topologies/seed_42python plasma_network_generator/commands/generate_all.py \    -k 1 2 4 \    --seed 42 \    --size"3 30 30000 3000" \    --nations"IT,FI,CY" \    --capacity-fractions 0.5 1 \    --model-params-file"plasma_network_generator/defaultModelParams.json" \    --output-dir ../experiments/workspace/topologies/seed_42

1. Run the simulator. The ROSS Kernel requires the following parameters:

   • -np: number of processes (must match the number of partitions used to partition the topology)
   • --synch: synchronization method (options: 1=sequential, 2=conservative, 3=optimistic, 5=real-time optimistic)
   • --end: simulation end time (default 100000.00)

   Additionally, the model accepts these input parameters:

   • --input-dir: directory containing the files defining the simulation parameters. The simulation parameters are read from the following files:plasma_network_channels.csv,plasma_network_edges.csv,plasma_network_nodes.csv,plasma_paths.csv, which can be generated as described above
   • --output-dir: output directory where simulation results are stored (must exist)
   • --tps: constant load mode (transactions per second)
   • --tps-config: variable load mode (configured by a file)
   • --waterfall: enable/disable automatic deposits (1/0)
   • --reverse-waterfall: enable/disable automatic withdrawals (1/0)
   • --submarine-swaps: enable/disable on-chain vs off-chain atomic swaps (1/0)

   Sample command:

   cd~/itcoin-pcn-simulatormkdir -p experiments/workspace/resultsOUTDIR="experiments/workspace/results/$(date +"%Y%m%d%H%M%S")"mkdir"${OUTDIR}"NP=4&& \INDIR="experiments/workspace/topologies/seed_42/capacity-0.5/k_0${NP}"&& \mpirun -np$NP build/itcoin-pcn-simulator \    --input-dir="${INDIR}" \    --output-dir="${OUTDIR}" \    --synch=3 --extramem=400000 \    --max-opt-lookahead=100 --batch=1 \    --waterfall=1 --reverse-waterfall=1 \    --use-known-paths=1 \    --submarine-swaps=1 \    --end=86400000 \    --tps=2 \    --block-size=4 \    --block-congestion-rate=0 \    --submarine-swap-threshold=0.9

1. You can calculate statistical about simulation results using the statistics analyzer utility. For example, after executing the following command, you will find the aggregated results incloth_output.json

   cd~/itcoin-pcn-simulator/utilitiespoetry shellpython statistics_analyzer/commands/analyzer.py \    --input-dir ../"${OUTDIR}" \    --output-dir ../"${OUTDIR}"

For more advanced examples and simulations, see the following files:

• DLT24 notebook (no longer supported: available on an earlier version)
• theCOMCOM25 README.md, andCOMCOM25 notebook