Utils

org.blockchainbench.utils is the shared library. It holds the plain data types that every other bundle exchanges, the typed result model that runs are serialised into, and the ConfigManager that reads and writes configuration files. It depends only on Gson and log4j, never on Core or the Palladio platform, which is why both the engine and the front ends can build against it freely.

The bundle exports two packages: org.blockchainbench.utils.models and org.blockchainbench.utils.services.

Configuration inputs

Two types describe what to simulate.

BaseConfig carries the parameters shared by a whole submitted group, and is loaded from a JSON file (data/configuration.json by default). It selects Monte-Carlo versus single simulation, the blockchain length bound and Monte-Carlo round count, an optional group-wide model path, and the four evaluation thresholds used by the Threesim metrics.

SimulationConfig represents a single row of the experiment CSV — one blockchain-system configuration. Its fields map to CSV columns via Gson @SerializedName annotations (config_id, Hnode, Hlink, block_creation_interval, and so on). The blockchainSystemModelFilePath field is marked transient: it is filled in at runtime by the model-path resolution in Core and is not part of the CSV.

Runtime state

Two more types track a submitted group while it runs.

SimulationInfo is the record for one submitted group: its id, its SimulationMode, a start timestamp, the list of RunInfo, a volatile group status, and a CopyOnWriteArrayList of collected SimulationRun results. The result list is populated by the worker as runs complete, and is complete once the status reaches FINISHED or ERROR. hasErrors() reports whether any run failed.

RunInfo is one run within a group: its runId, the SimulationConfig it will execute, a volatile status, an optional result file path, and an optional error message.

RunStatus (QUEUED, RUNNING, FINISHED, ERROR) and SimulationMode (NORMAL, ATTACK) are the two enumerations.

classDiagram
  class BaseConfig {
    +String simulationType
    +int maxAllowedBlockchainLength
    +int numberOfMonteCarloRounds
    +String blockchainSystemModelFilePath
    +double failureThroughputThreshold
    +double shannonEntropyK
    +double nakamotoCoefficientThreshold
    +double reliabilityObservationTimespan
  }
  class SimulationConfig {
    +int configId
    +double hnode
    +double hlink
    +double blockCreationInterval
    +double hashrateConcentration
    +int maxBlockSize
    +int inboundConnections
    +int outboundConnections
    +int numberOfAttackers
    +int validatorCount
    +String blockchainSystemModelFilePath
  }
  class SimulationInfo {
    +int simulationId
    +SimulationMode mode
    +long startedAt
    +RunStatus status
    +hasErrors() boolean
  }
  class RunInfo {
    +int runId
    +RunStatus status
    +String errorMessage
  }
  class RunStatus {
    <<enumeration>>
    QUEUED
    RUNNING
    FINISHED
    ERROR
  }
  class SimulationMode {
    <<enumeration>>
    NORMAL
    ATTACK
  }

  SimulationInfo "1" --> "*" RunInfo : runs
  SimulationInfo "1" --> "*" SimulationRun : results
  RunInfo --> SimulationConfig : config
  SimulationInfo --> SimulationMode
  SimulationInfo --> RunStatus
  RunInfo --> RunStatus

The result data model

SimulationData is a container of Gson-compatible, Serializable model classes that mirror the simulator’s JSON output. The document written per run is a SimulationRun, which nests the typed simulation result together with the inputs and the measured cost.

classDiagram
  class SimulationRun {
    +int runId
    +int configId
    +SimulationConfig inputParameters
    +BaseConfig baseConfig
    +SimulationResult simulationResult
    +long startSimulationTime
    +long stopSimulationTime
    +long simulationTime
    +long memoryUsed
  }
  class SimulationResult {
    +SimulationParameters simulationParameters
    +ThreesimSimulationParameters threesimSimulationParameters
    +generalResults
    +simulationRoundResults
    +averageSimulationRoundResult
  }
  class SimulationParameters {
    +int maxAllowedBlockchainLength
    +int numberOfMonteCarloRounds
    +String blockchainSystemModelFilePath
    +int numberOfAttacker
  }
  class ThreesimSimulationParameters {
    +double failureThroughputThreshold
    +double shannonEntropyK
    +double nakamotoCoefficientThreshold
    +double reliabilityObservationTimespan
  }
  class GeneralResult {
    +String name
    +double value
    +String unit
  }
  class RoundMetric {
    +String name
    +JsonElement value
    +String unit
  }
  class AverageMetric {
    +String name
    +JsonElement average
    +String unit
    +double standardDeviation
    +double coefficientOfVariation
  }

  SimulationRun --> SimulationResult
  SimulationRun --> SimulationConfig : inputParameters
  SimulationRun --> BaseConfig
  SimulationResult --> SimulationParameters
  SimulationResult --> ThreesimSimulationParameters
  SimulationResult --> GeneralResult
  SimulationResult --> RoundMetric
  SimulationResult --> AverageMetric

SimulationResult groups three kinds of output: generalResults (named scalar values with units), simulationRoundResults (per-round metrics, one list per Monte-Carlo round), and averageSimulationRoundResult (aggregates with standard deviation and coefficient of variation). RoundMetric and AverageMetric keep their numeric payload as a Gson JsonElement, so the model can absorb both scalar and structured values without losing type information. The container also defines fault-tolerance value types (FaultToleranceValue, AverageFaultToleranceValue, and their MetricDelta parts) for delta-style metrics.

ConfigManager

ConfigManager is the configuration and model I/O façade. It defines the default file locations and offers symmetric load/save helpers:

• loadBaseConfig / loadJson and saveJson for the BaseConfig JSON.
• loadCsv and saveCsv for the SimulationConfig list. loadCsv reads the header row, then converts each data row into a JsonObject keyed by column name and lets Gson map it onto SimulationConfig, so the CSV column names drive the binding.
• pickModelPath(testmodelsDir, configId) resolves the deterministic model location testmodels/threesim-<config_id>/Net.blockchainsystem and fails fast if it is missing.

Default locations (relative to the process working directory):

Purpose	Default path
Base configuration	data/configuration.json
Experiment CSV	data/optimized_deterministic_lhs_configurations.csv
Model root	data/testmodels/

The concrete file formats and a sample row are shown in Build and run.