CoinJoin simulation setup

A container-based setup for simulating CoinJoins on RegTest network.

Usage

Install Docker and Python.
Install dependencies: pip install -r requirements.txt.
Run the default scenario on the default driver: python manager.py run.
- Scenario definition file can be specified using the --scenario option.

For more complex setups see section Advanced usage.

Scenarios

Scenario definition files can be passed to the simulation script using the --scenario option. The scenario definition is a JSON file with the following structure:

{
    "name": "default",
    "rounds": 0,
    "blocks": 120,
    "backend": {
        "MaxInputCountByRound": 200,
        "MinInputCountByRoundMultiplier": 0.2,
        ...
    },
    "wallets": [
        {"funds": [200000, 50000]},
        {"funds": [3000000], "delay": 10},
        ...
    ],
}

The fields are as follows:

name field is the name of the scenario used for output logs.
rounds field is the number of coinjoin rounds after which the simulation terminates. If set to 0, the simulation will run indefinitely.
blocks field is the number of mined blocks after which the simulation terminates. If set to 0, the simulation will run indefinitely.
backend field is the configuration for the wasabi-backend container used in the simulation. The provided fields update the defaults.
wallets field is a list of wallet configurations. Each wallet configuration is a dictionary with the following fields:
- funds is a list of funds in satoshis that the wallet will use for coinjoins.
- delay is the number of blocks the wallet will wait before joining coinjoins.

Advanced usage

The simulation script enables advanced configuration for running on different container platforms with various networking setups. This section describes the advanced configuration and shows common examples.

Backend driver

Docker

The default driver is docker. Running docker requires Docker installed locally and running.

Podman

Podman support will be likely removed in the future versions.

To run the simulation using podman, specify it as driver using --driver podman option.

The driver requires Podman being installed and you may also need to override default IP addresses to communicate via localhost using --control-ip and --wasabi-backend-ip options.

Kubernetes

To run the simulation on a Kubernetes cluster, use the kubernetes driver. The driver requires a running Kubernetes cluster and kubectl configured to access the cluster.

The kubernetes driver relies on used images being accessible publicly from DockerHub. For that, build the images in containers directory manually and upload them to the registry. Afterwards, specify the image prefix using --image-prefix option when starting the simulation.

In case NodePorts are not supported by your cluster, you may also need to run a proxy to access the services, e.g., Shadowsocks. Use the --proxy option to specify the address of the proxy.

If you need to specify custom namespace, use the --namespace option. If you also need to reuse existing namespace, use the --reuse-namespace option.

Example

Running the simulation on a remote cluster using pre-existing namespace and a proxy reachable on localhost port 8123:

python manager.py run --driver kubernetes --namespace custom-coinjoin-ns --reuse-namespace --image-prefix "crocsmuni/" --proxy "socks5://127.0.0.1:8123" --scenario "scenarios/uniform-dynamic-500-30utxo.json"

crocs-muni/coinjoin-simulator