Skip to content

docs: Revise Simulator Documentation #1302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

docs: Revise Simulator Documentation #1302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fcd0665
docs: enhance simulator configuration documentation
mustafauzunn Jun 12, 2025
dd5de75
style: formatting
mustafauzunn Jun 12, 2025
a0c10c1
docs: refactor
mustafauzunn Jun 12, 2025
b7e2b6a
docs: refactor PR comments
mustafauzunn Jun 13, 2025
d413617
docs: refactor PR comments
mustafauzunn Jun 13, 2025
df1707f
Merge branch 'main' of github.com:mustafauzunn/hiero-block-node into …
mustafauzunn Jun 13, 2025
03d35cd
docs: enhance consumer config javadoc
mustafauzunn Jun 13, 2025
574cf42
docs: update default values
mustafauzunn Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 65 additions & 19 deletions docs/simulator/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,80 @@
# Configuration

There are 3 configuration sets:
1. [BlockStreamConfig](#blockstreamconfig): contains the configuration for the Block Stream Simulator logic.
1. [GeneratorConfig](#generatorconfig): contains the configuration for the Block Stream Simulator generation module.
1. [GrpcConfig](#grpcconfig): contains the configuration for the gRPC communication with the Block-Node.
2. [BlockGeneratorConfig](#blockgeneratorconfig): contains the configuration for the Block Stream Simulator generation module.

Check notice on line 4 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L4 

Expected: 80; Actual: 126
3. [SimulatorStartupDataConfig](#simulatorstartupdataconfig): contains the configuration for the Block Stream Simulator startup data.
4. [UnorderedStreamConfig](#unorderedstreamconfig): contains the configuration for the Unordered Stream Simulator logic.
5. [ConsumerConfig](#consumerconfig): contains the configuration for the Consumer Simulator logic.

Check notice on line 7 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L7 

Expected: 80; Actual: 98
6. [GrpcConfig](#grpcconfig): contains the configuration for the gRPC communication with the Block-Node.

Check notice on line 8 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L8 

Expected: 80; Actual: 104
7. [PrometheusConfig](#prometheusconfig): contains the configuration for the Prometheus agent.

Check notice on line 9 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L9 

Expected: 80; Actual: 94

## BlockStreamConfig

Uses the prefix `blockStream` so all properties should start with `blockStream.`

| Key | Description | Default Value |
|:-------------------------|:------------------------------------------------------------------------------------------------------------------------------------|----------------:|
| `simulatorMode` | The desired simulator mode to use, it can be either `PUBLISHER` or `CONSUMER`. | `PUBLISHER` |
| `delayBetweenBlockItems` | The delay between each block item in nanoseconds, only applicable when streamingMode=CONSTANT_RATE | `1_500_000` |
| `maxBlockItemsToStream` | exit condition for the simulator and the circular implementations such as `BlockAsDir` or `BlockAsFile` implementations | `10_000` |
| `streamingMode` | can either be `CONSTANT_RATE` or `MILLIS_PER_BLOCK` | `CONSTANT_RATE` |
| `millisecondsPerBlock` | if streamingMode is `MILLIS_PER_BLOCK` this will be the time to wait between blocks in milliseconds | `1_000` |
| `blockItemsBatchSize` | the number of block items to send in a single batch, however if a block has less block items, it will send all the items in a block | `1_000` |
| Key | Description | Default Value |
|:----------------------------|:------------------------------------------------------------------------------------------------------------------------------------|-------------------:|
| `simulatorMode` | The desired simulator mode to use, it can be either `PUBLISHER_SERVER` or `CONSUMER`. | `PUBLISHER_SERVER` |
| `lastKnownStatusesCapacity` | The store capacity for the last known statuses. | `10` |
| `delayBetweenBlockItems` | The delay between each block item in nanoseconds, only applicable when streamingMode is `CONSTANT_RATE` | `1_500_000` |
| `maxBlockItemsToStream` | The maximum number of block items to stream before stopping | `100_000` |

Check notice on line 20 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L20 

Expected: 80; Actual: 184
| `streamingMode` | Can either be `CONSTANT_RATE` or `MILLIS_PER_BLOCK` | `MILLIS_PER_BLOCK` |
| `millisecondsPerBlock` | If streamingMode is `MILLIS_PER_BLOCK` this will be the time to wait between blocks in milliseconds | `1_000` |

Check notice on line 22 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L22 

Expected: 80; Actual: 184
| `blockItemsBatchSize` | The number of block items to send in a single batch, however if a block has less block items, it will send all the items in a block | `1_000` |

Check notice on line 23 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L23 

Expected: 80; Actual: 184
| `midBlockFailType` | The type of failure to occur while streaming. It can be `NONE`, `ABRUPT` or `EOS` | `NONE` |
| `midBlockFailOffset` | The index where the failure will occur, only applicable if midBlockFailType is not `NONE` | `0` |

Check notice on line 25 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L25 

Expected: 80; Actual: 184

## GeneratorConfig
## BlockGeneratorConfig

Uses the prefix `generator` so all properties should start with `generator.`

| Key | Description | Default Value |
|:------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------:|
| `generationMode` | The desired generation Mode to use, it can only be `DIR` or `AD_HOC` | `DIR` |
| `folderRootPath` | If the generationMode is DIR this will be used as the source of the recording to stream to the Block-Node | `` |
| `managerImplementation` | The desired implementation of the BlockStreamManager to use, it can only be `BlockAsDirBlockStreamManager`, `BlockAsFileBlockStreamManager` or `BlockAsFileLargeDataSets` | `BlockAsFileBlockStreamManager` |
| `paddedLength` | on the `BlockAsFileLargeDataSets` implementation, the length of the padded left zeroes `000001.blk.gz` | 36 |
| `fileExtension` | on the `BlockAsFileLargeDataSets` implementation, the extension of the files to be streamed | `.blk.gz` |
| Key | Description | Default Value |
|:--------------------------|:------------------------------------------------------------------------------------------------------------|--------------------------------:|
| `generationMode` | The desired generation Mode to use, it can only be `DIR` or `CRAFT` | `CRAFT` |

Check notice on line 33 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L33 

Expected: 80; Actual: 173
| `minEventsPerBlock` | The minimum number of events per block | `1` |

Check notice on line 34 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L34 

Expected: 80; Actual: 236
| `maxEventsPerBlock` | The maximum number of events per block | `10` |

Check notice on line 35 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L35 

Expected: 80; Actual: 236
| `minTransactionsPerEvent` | The minimum number of transactions per event | `1` |

Check notice on line 36 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L36 

Expected: 80; Actual: 236
| `maxTransactionsPerEvent` | The maximum number of transactions per event | `10` |

Check notice on line 37 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L37 

Expected: 80; Actual: 236
| `folderRootPath` | If the generationMode is `DIR` this will be used as the source of the recording to stream to the Block-Node | `` |

Check notice on line 38 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L38 

Expected: 80; Actual: 236
| `managerImplementation` | The desired implementation of the BlockStreamManager to use | `BlockAsFileBlockStreamManager` |

Check notice on line 39 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L39 

Expected: 80; Actual: 173
| `paddedLength` | On the `BlockAsFileLargeDataSets` implementation, the length of the padded left zeroes `000001.blk.gz` | `36` |
| `fileExtension` | On the `BlockAsFileLargeDataSets` implementation, the extension of the files to be streamed | `.blk.gz` |

Check notice on line 41 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L41 

Expected: 80; Actual: 236
| `startBlockNumber` | The block number to start streaming from | `0` |
| `endBlockNumber` | The block number to stop streaming at | `-1` |

Check notice on line 43 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L43 

Expected: 80; Actual: 236
| `invalidBlockHash` | If set to true, will send invalid block root hash | `false` |

## SimulatorStartupDataConfig

Uses the prefix `simulator.startup.data` so all properties should start with `simulator.startup.data.`

| Key | Description | Default Value |
|:---------------------------|:-----------------------------------------------------------------|-------------------------------------------:|
| `enabled` | Whether the startup data functionality is enabled | `false` |

Check notice on line 52 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L52 

Expected: 80; Actual: 143
| `latestAckBlockNumberPath` | Path to the file containing the latest acknowledged block number | `/opt/simulator/data/latestAckBlockNumber` |

Check notice on line 53 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L53 

Expected: 80; Actual: 143
| `latestAckBlockHashPath` | Path to the file containing the latest acknowledged block hash | `/opt/simulator/data/latestAckBlockHash` |

Check notice on line 54 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L54 

Expected: 80; Actual: 143

## UnorderedStreamConfig

Uses the prefix `unorderedStream` so all properties should start with `unorderedStream.`

| Key | Description | Default Value |
|:-------------------------|:-------------------------------------------------------------------------|--------------:|
| `enabled` | Whether to enable the unordered streaming mode | `false` |

Check notice on line 62 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L62 

Expected: 80; Actual: 119
| `availableBlocks` | The numbers of the blocks which will be considered available for sending | `[1-10]` |

Check notice on line 63 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L63 

Expected: 80; Actual: 119
| `sequenceScrambleLevel` | The coefficient used to randomly scramble the stream | `0` |

Check notice on line 64 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L64 

Expected: 80; Actual: 119
| `fixedStreamingSequence` | The numbers of the blocks which will form the steam | `1,2,4,3` |

## ConsumerConfig

Uses the prefix `consumer` so all properties should start with `consumer.`

| Key | Description | Default Value |
|:------------------------|:--------------------------------------------------------------------------------------------------------|--------------:|
| `startBlockNumber` | The block number from which to start consuming | `-1` |
| `endBlockNumber` | The block number at which to stop consuming | `-1` |
| `slowDownType` | The type of slow down to apply while consuming, it can be `NONE`, `FIXED`, `RANDOM`, `RANDOM_WITH_WAIT` | `NONE` |

Check notice on line 75 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L75 

Expected: 80; Actual: 151
| `slowDownMilliseconds` | The slowdown in milliseconds | `2` |
| `slowDownForBlockRange` | The range of blocks to apply the slowdown | `10-30` |

Check notice on line 77 in docs/simulator/configuration.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

docs/simulator/configuration.md#L77 

Expected: 80; Actual: 151

## GrpcConfig

Expand Down
4 changes: 4 additions & 0 deletions ...s/simulator/src/main/java/org/hiero/block/simulator/config/data/BlockGeneratorConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@
* Defines the configuration for the BlockStreamManager (Generator) of blocks in the Hedera Block Simulator.
*
* @param generationMode the mode of block generation (e.g., directory-based)
* @param minEventsPerBlock the minimum number of events per block
* @param maxEventsPerBlock the maximum number of events per block
* @param minTransactionsPerEvent the minimum number of transactions per event
* @param maxTransactionsPerEvent the maximum number of transactions per event
* @param folderRootPath the root path of the folder containing block files
* @param managerImplementation the implementation class name of the block stream manager
* @param paddedLength the length to which block identifiers are padded
Expand Down
2 changes: 2 additions & 0 deletions ...ests/simulator/src/main/java/org/hiero/block/simulator/config/data/BlockStreamConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@
* @param streamingMode the mode of streaming for the block stream (e.g., time-based, count-based)
* @param millisecondsPerBlock the duration in milliseconds for each block when using time-based streaming
* @param blockItemsBatchSize the number of block items to stream in each batch
* @param midBlockFailType the type of failure to occur while streaming
* @param midBlockFailOffset the index of the failing block
*/
@ConfigData("blockStream")
public record BlockStreamConfig(
Expand Down
9 changes: 9 additions & 0 deletions ...d-tests/simulator/src/main/java/org/hiero/block/simulator/config/data/ConsumerConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,15 @@
import org.hiero.block.simulator.config.logging.Loggable;
import org.hiero.block.simulator.config.types.SlowDownType;

/**
* Defines the configuration data for the consumer.
*
* @param startBlockNumber the block number from which to start consuming
* @param endBlockNumber the block number at which to stop consuming
* @param slowDownType the type of slowdown to apply while consuming
* @param slowDownMilliseconds the slowdown in milliseconds
* @param slowDownForBlockRange the range of blocks to apply the slowdown
*/
@ConfigData("consumer")
public record ConsumerConfig(
@Loggable @ConfigProperty(defaultValue = "-1") long startBlockNumber,
Expand Down
Loading