cloth - a lightning network simulator

  1. Why
  2. State of the art
  3. Lightning Network performance
  4. What is CLoTH
  5. How it works
  6. What can be tested
  7. What it can answer
  8. Upcoming experiments
  9. Paper preview


In the past 10 years Bitcoin established itself as a digital store of value. In order to also establish itself as a digital medium of exchange, its maximum transaction throughput needs to greatly increase. While the Lightning Network has the potential to address this scalability issue, it is an emergent network: lack of central coordination may hinder its healthy growth. The LN protocol is characterised by features that, if not properly understood, implemented and controlled, might undermine the development of a healthy payment network, i.e. a network that supports fast and successful payments.

To prevent that we believe it’s critical to simulate the Lightning Network in a controlled environment. A Lightning Network simulator can be useful in:

  • engineering: prioritiziation of new features to be developed, steering toward the best network topology, understanding tradeoffs between performance and decentralization, exploring different payment use cases, researching routing algorithms, etc
  • business: finding out best nodes policies, forecasting returns on investments in setting up new hubs, etc
  • community: resolving disputes around scalability and decentralization

and more

State of the art

Lightning Network “simulators” have already been described in literature. Two of them are available on GitHub, but they only simulate specific aspects of the protocol and don’t aim at generality.

Instead CLoTH runs a map of the actual lnd code, which is compliant with BOLT specifications. This guarantees full accuracy of its simulations.

CLoTH is a simulator, not a testbed: no actual Lightning Network node is launched. A simulator is cheaper than a testbed, therefore allowing for more research freedom.

Lightning Network performance

Bitcoin and the Lightning Network are different architectures with different attributes.

Bitcoin Lightning Network
global state? yes no
fee model tx size tx value
performance tx cost, time, success tx cost, time, success
factors affecting performance mempool queue various (payer, payee, tx amount, tx route, etc)
throughput yes no

In both architectures performance can be defined in terms of cost, time and success rate of transactions.

While throughput is also an interesting metric to measure performance of the Bitcoin blockchain, it can’t be used as a measure of Lightning Network performance given the lack of a global state.

In other words, any attempt to measure throughput on the Lightning Network could be easily manipulated by colluding nodes transacting with each other.

What is CLoTH

CLoTH is a discrete-events simulator: events represent state changes of the simulated system. Quality of the simulation is ensured by a mapping of lnd, the Golang implementation of the Lightning Network.

In CLoTH time is simulated: simulated time is reduced to computation time.

How it works

This is the CLoTH simulator workflow:

CLoTH workflow

Each simulation goes through three phases:

  1. pre-processing: it generates a complete topology and payments script based on few inputs
  2. simulation
  3. post-processing: it statistically reduces fine-grained data into human-readable indicators.

Network generator inputs:

NpN_p Number of peers
NchN_{ch} Average number of channels per peer
σt\sigma_t Tuner of network topology
Pc¯bP_{\bar{c}_b} Uncooperative peers probability before HTLC establishment
Pc¯aP_{\bar{c}_a} Uncooperative peers probability after HTLC establishment
CchC_{ch} Average channel capacity
GG Gini index of channel capacity

Payments generator inputs:

rπr_{\pi} Transactions per second (off-chain)
NπN_{\pi} Number of payments
σa\sigma_a Tuner of payment amounts
FsrF_{sr} Fraction of same-recipient payments

CLoTH output

As output, CLoTH produces performance measures in the form of payment-related statistics (e.g., the probability of payment failures and the mean payment complete time).

What can be tested

A CLoTH simulation has three main components:

  • Nodes: nodes can have different policies or uptime, and the simulator can be upgraded to different LN specification versions. More interestingly, CLoTH can simulate new features that haven’t been already implemented in the protocol.
  • Network: simulations can run on snapshots of the LN mainnet, as well as on new, different networks in terms of topology and/or channel capacity
  • Payments: a large range of payment models can be simulated

What it can answer

Some questions CLoTH can answer:

  • How many channels per peer are required to have a well connected network?
  • How do peers going offline affect performance?
  • How does payment amount influence the chance of payment failure?
  • How does mean payment time decrease by adding a peer with a specific set of payment channels in a specific section of the network?

Upcoming experiments

We plan to run experiments and publish their result in an upcoming work.
We’re particlarly interested in understanding how performance is affected by network centralization, channels quantity and capacity, payments amounts and flows.

Here are some scenarios we plan to explore:

  • Current network: various payment scripts on a snapshot of current mainnet topology
  • Hub and spoke: hubs serving thousands of clients each
  • Few merchants: payment scripts where payment flows are directed toward a minority (< 1%) of nodes

Paper preview

Get our research updates