logos-blockchain-simulations/simlib/blendnet-sims/README.md

# Nomos Blend Simulation

## Features

- The simulation runs multiple Nomos Blend nodes using [netrunner](../netrunner).
- Each node implements the Nomos Blend Tier 1~3 protocols.
    - [Persistent Transmission](https://www.notion.so/Nomos-Blend-Network-Tier-1-Persistent-Transmission-Module-10b8f96fb65c807cb1e8f92a7f41a771?pvs=4)
    - [Message Blending](https://www.notion.so/Nomos-Blend-Network-Tier-2-Message-Blending-Module-1208f96fb65c80e5bcb9df6e27472339?pvs=4)
    - [Cover Traffic](https://www.notion.so/Nomos-Blend-Network-Tier-3-Cover-Traffic-Module-10b8f96fb65c80cab153de10115e0023?pvs=4)
    - Also, each node generates data messages probabilistically (similar as the consensus protocol).
- The simulation prints logs that can be used to analyze the following properties.
    - Latency
    - Bandwidth
    - Anonymity

## Configurations

The simulation can be configured by [config/blendnet.json](./config/blendnet.json).

### `step_time` and `network_settings`

We recommend setting the step time equal to the minimum latency in the network settings,
in order to speed up the simulation.
For example, if all regions are used, and if the minimum latency is 40ms (asia:asia),
we recommend setting the step time to 40ms.

### `wards.sum`

The simulation runs until the `wards.sum` number of messages (data or cover) arrive in
their last blend node and finally fully unwrapped.

### Network Topology

The simulation constructs a network with the `node_count` number of nodes.
Each node establish connections with the `connected_peers_count` number of nodes randomly selected.

Nodes are distributed across multiple regions specified in the `network_settings.regions`.
Conneciton latency between regions can be set by `network_settings.network_behaviors`.

### Protocol Parameters

#### Tier 1: Persistent Transmission

```json
"persistent_transmission": {
  "max_emission_frequency": 1.0,
  "drop_message_probability": 0.0
},
```
We recommend setting `max_emission_frequency` to [1 message per second](https://www.notion.so/Nomos-Blend-Network-Tier-1-Persistent-Transmission-Module-10b8f96fb65c807cb1e8f92a7f41a771?pvs=4#11f8f96fb65c80dfbd23e4400feaaf9c),
which is the same as the expected maximum message frequency configured in the consensus protocol
that will use the Nomos Blend protocol.

To disable [drop messages](https://www.notion.so/Nomos-Blend-Network-Tier-1-Persistent-Transmission-Module-10b8f96fb65c807cb1e8f92a7f41a771?pvs=4#11c8f96fb65c804db7ccfd024f8c44d0), set `drop_message_probability` to 0.

#### Tier 2: Message Blending

```json
"number_of_mix_layers": 2,
"max_delay_seconds": 10
```

The `number_of_mix_layers` is a parameter for the [Cryptographic Processor](https://www.notion.so/Nomos-Blend-Network-Tier-2-Message-Blending-Module-1208f96fb65c80e5bcb9df6e27472339?pvs=4#1208f96fb65c80f8a8d3d2b449953bde). And, the `max_delay_seconds` is for [Temporal Processor](https://www.notion.so/Nomos-Blend-Network-Tier-2-Message-Blending-Module-1208f96fb65c80e5bcb9df6e27472339?pvs=4#1208f96fb65c80dca885dda33fbd599b), which is the same as $\Delta_{max}$ in the specification.

#### Tier 3: Cover Traffic

```json
"epoch_duration": "432000s",
"slot_duration": "20s",
"slots_per_epoch": 21600,
"number_of_hops": 2,
```
These parameters are defined in the [specification](https://www.notion.so/Nomos-Blend-Network-Tier-3-Cover-Traffic-Module-10b8f96fb65c80cab153de10115e0023?pvs=4#12f8f96fb65c80d094b6f31306c65b70).
In short, each node selects the `slots_per_epoch / node_count * (1 / number_of_hops)` number of slots
at the beginning of each epoch. At every selected slot, the node generates a cover message.


## Running the simulation

```bash
cargo build --release
../target/release/blendnet-sims run --input-settings ./config/blendnet.json
```
The simulation prints a bunch of logs that can be used for analysis.
We recommend piping logs to a file.

## Analysis

### Bandwidth

The bandwidth consumed by each node is printed as a log at the end of the simulation.
The unit of bandwidth is `bytes / second`.

```
2025-02-17T11:20:36.540603Z  INFO netrunner::runner::sync_runner: Network state: NetworkState { total_outbound_bandwidth: 1295032320, total_inbound_bandwidth: 1293844480, min_node_total_bandwidth: 7823360.0, max_node_total_bandwidth: 17039360.0, avg_node_total_bandwidth: 12938444.8 }
```

### Latency

The `analyze latency` command reads a log generated by the simulation,
and analyzes the total latency of each message that has reached to its final blend node.

Also, it analyzes the latency of the connections that messages have traveled through.
This is useful to compare the distribution of the used connections with the configured distribution of the nodes.

```bash
# Set the path of a log file printed from the simulation.
# Don't forget to use the step duration used in the simulation.
../target/release/blendnet-sims analyze latency --log-file <path> --step-duration 10ms
```

```json
{
  "message": {
    "count": 101,
    "min": 1160,
    "min_payload_id": "38479093-25ee-4eaa-a055-3817b92c0265",
    "q1": 4050.0,
    "avg": 5448.316831683168,
    "med": 5100.0,
    "q3": 7030.0,
    "max": 10110,
    "max_payload_id": "1efd8780-b574-4aee-9df5-f8732a93e182"
  },
  "connection": {
    "count": 19943,
    "min": 30,
    "q1": 50.0,
    "avg": 111.3152484581056,
    "med": 60.0,
    "q3": 140.0,
    "max": 400
  }
}
```

### Message History

The `analyze message-history` command gathers all events related to a message from the log.
This is useful to investigate how much time was spent in each event (connection, persistent transmission, and temporal processor).

```bash
# Set the path of a log file printed from the simulation.
# Don't forget to use the step duration used in the simulation.
../target/release/blendnet-sims analyze message-history \
    --log-file <path> \
    --step-duration 10ms \
    --payload-id 1efd8780-b574-4aee-9df5-f8732a93e182
```