feat(scripts): integrate tx-firehose as an optional load generator

flake.nix

@@ -11,18 +11,23 @@
     cardano-node-tx-centrifuge = {
       url = "github:IntersectMBO/cardano-node?ref=bench/leios-11.0.1";
     };
+    # tx-firehose only, lives on yet another cardano-node branch.
+    cardano-node-tx-firehose = {
+      url = "github:IntersectMBO/cardano-node?ref=leios-prototype";
+    };
     flake-utils = {
       url = "github:numtide/flake-utils";
     };
   };
 
-  outputs = { self, nixpkgs, flake-utils, cardano-node, cardano-node-tx-centrifuge }:
+  outputs = { self, nixpkgs, flake-utils, cardano-node, cardano-node-tx-centrifuge, cardano-node-tx-firehose }:
     flake-utils.lib.eachDefaultSystem
       (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
           nodePkgs = cardano-node.packages.${system};
           centrifugePkgs = cardano-node-tx-centrifuge.packages.${system};
+          firehosePkgs = cardano-node-tx-firehose.packages.${system};
         in
         {
           devShells = rec {
@@ -40,6 +45,7 @@
                 nodePkgs.bech32
                 nodePkgs.tx-generator
                 centrifugePkgs.tx-centrifuge
+                firehosePkgs.tx-firehose
                 pkgs.bashInteractive
                 pkgs.python313
               ];

src/cardonnay_scripts/scripts/common/common-start-fast

@@ -14,6 +14,7 @@ readonly DREP_DELEGATED=500000000000
 readonly FEE=5000000
 readonly BYRON_INIT_SUPPLY=10020000000
 readonly TX_GENERATOR_MIN_FUNDS=5000000000000000
+readonly TX_FIREHOSE_MIN_FUNDS=5000000000000
 
 readonly INSTANCE_NUM="%%INSTANCE_NUM%%"
 readonly NUM_POOLS=%%NUM_POOLS%%
@@ -112,8 +113,18 @@ initialize_globals() {
   # shellcheck disable=SC1091
   source "${SCRIPT_DIR}/common.sh"
 
-  if is_truthy "${ENABLE_TX_GENERATOR:-}" && is_truthy "${ENABLE_TX_CENTRIFUGE:-}"; then
-    echo "ENABLE_TX_GENERATOR and ENABLE_TX_CENTRIFUGE are mutually exclusive, line $LINENO in ${BASH_SOURCE[0]}" >&2
+  local -a enabled_tx_tools=()
+  local tx_name tx_flag
+  for tx_name in ENABLE_TX_GENERATOR ENABLE_TX_CENTRIFUGE ENABLE_TX_FIREHOSE; do
+    tx_flag="${!tx_name:-}"
+    if is_truthy "$tx_flag"; then
+      enabled_tx_tools+=("$tx_name")
+    fi
+  done
+  if [ "${#enabled_tx_tools[@]}" -gt 1 ]; then
+    local joined
+    printf -v joined '%s, ' "${enabled_tx_tools[@]}"
+    echo "${joined%, } are mutually exclusive, line $LINENO in ${BASH_SOURCE[0]}" >&2
     exit 1
   fi
 
@@ -638,6 +649,7 @@ main() {
   use_genesis_mode
   setup_tx_generator "$TX_GENERATOR_MIN_FUNDS"
   setup_tx_centrifuge
+  setup_tx_firehose "$TX_FIREHOSE_MIN_FUNDS"
 
   : > "$START_CLUSTER_STATUS"
   echo "Cluster started 🚀"

src/cardonnay_scripts/scripts/common/common-start-slow

@@ -116,6 +116,11 @@ initialize_globals() {
     exit 1
   fi
 
+  if is_truthy "${ENABLE_TX_FIREHOSE:-}"; then
+    echo "tx-firehose is not supported in the slow cluster script, line $LINENO in ${BASH_SOURCE[0]}" >&2
+    exit 1
+  fi
+
   readonly FUNDS_PER_GENESIS_ADDRESS="$((MAX_SUPPLY / NUM_BFT_NODES))"
   readonly FUNDS_PER_BYRON_ADDRESS="$((FUNDS_PER_GENESIS_ADDRESS * 8 / 10))"
 }

src/cardonnay_scripts/scripts/common/common.sh

@@ -622,6 +622,21 @@ startsecs=5
 EoF
   fi
 
+  if is_truthy "${ENABLE_TX_FIREHOSE:-}"; then
+    cp "${SCRIPT_DIR}/run-tx-firehose" "${STATE_CLUSTER}"
+
+    cat >> "${STATE_CLUSTER}/supervisor.conf" <<EoF
+
+[program:tx_firehose]
+command=./${STATE_CLUSTER_NAME}/run-tx-firehose
+stderr_logfile=./${STATE_CLUSTER_NAME}/tx-firehose.stderr
+stdout_logfile=./${STATE_CLUSTER_NAME}/tx-firehose.stdout
+autostart=false
+autorestart=false
+startsecs=5
+EoF
+  fi
+
   cat >> "${STATE_CLUSTER}/supervisor.conf" <<EoF
 
 [group:nodes]
@@ -1019,7 +1034,7 @@ use_genesis_mode() {
   supervisorctl -s unix:///"${SUPERVISORD_SOCKET_PATH}" restart nodes:
 }
 
-_fund_tx_gen() {
+_fund_address() {
   : "${STATE_CLUSTER:?STATE_CLUSTER is required}"
   : "${FAUCET_ADDR:?FAUCET_ADDR is required}"
   : "${FAUCET_SKEY:?FAUCET_SKEY is required}"
@@ -1028,16 +1043,17 @@ _fund_tx_gen() {
 
   local addr="${1:?}"
   local fund_amount="${2:?}"
+  local label="${3:-fund-address}"
   local fee=500000
   local stop_txin_amount="$((fund_amount + fee))"
-  local tx_base="${STATE_CLUSTER}/shelley/fund-tx-generator"
+  local tx_base="${STATE_CLUSTER}/shelley/${label}"
   local addr_balance
   local -a txins=()
   local txin_amount=0
 
   addr_balance="$(get_address_balance --address "$addr")"
   if [ "$addr_balance" -ge "$fund_amount" ]; then
-    echo "Tx generator address already has enough funds: $addr_balance lovelace"
+    echo "Address '$addr' already has enough funds: $addr_balance lovelace"
     return
   fi
 
@@ -1172,7 +1188,7 @@ setup_tx_generator() {
   local fund_amount="${1:?}"
   local tps="${TX_TPS:-100}"
 
-  _fund_tx_gen "$(<"${STATE_CLUSTER}/shelley/genesis-utxo2.addr")" "$fund_amount"
+  _fund_address "$(<"${STATE_CLUSTER}/shelley/genesis-utxo2.addr")" "$fund_amount" "fund-tx-generator"
 
   _create_tx_gen_config \
     "${STATE_CLUSTER}/topology-bft1.json" \
@@ -1376,3 +1392,115 @@ setup_tx_centrifuge() {
   echo "Waiting for tx centrifuge to start submitting transactions"
   _wait_for_tx_centrifuge_tx
 }
+
+_create_tx_firehose_config() {
+  if [ $# -lt 4 ]; then
+    echo "Usage: _create_tx_firehose_config <node.socket> <signing.skey> <magic> <tps>" >&2
+    return 1
+  fi
+
+  local socket_path="$1"
+  local skey_file="$2"
+  local magic="$3"
+  local tps="$4"
+
+  jq -n \
+    --arg socket "$socket_path" \
+    --arg skey "$skey_file" \
+    --argjson magic "$magic" \
+    --argjson tps "$tps" \
+    '{
+      socket_path: $socket,
+      testnet_magic: $magic,
+      signing_key_file: $skey,
+      tps: $tps,
+      inputs_per_tx: 1,
+      outputs_per_tx: 1,
+      fee: 200000,
+      max_consecutive_errors: 50
+    }'
+}
+
+_wait_for_tx_firehose_log() {
+  : "${STATE_CLUSTER:?STATE_CLUSTER is required}"
+
+  # tx-firehose writes its trace lines to stderr, unlike tx-generator / tx-centrifuge.
+  local logfile="${STATE_CLUSTER}/tx-firehose.stderr"
+  local _
+
+  for _ in {1..10}; do
+    if [ -f "$logfile" ]; then
+      return 0
+    fi
+    sleep 3
+  done
+  echo "Tx firehose log file was not created, line $LINENO in ${BASH_SOURCE[0]}" >&2
+  exit 1
+}
+
+_wait_for_tx_firehose_tx() {
+  : "${STATE_CLUSTER:?STATE_CLUSTER is required}"
+
+  local logfile="${STATE_CLUSTER}/tx-firehose.stderr"
+  local attempts=360
+  local start_time elapsed_time
+  local success=0
+  local a
+
+  start_time="$EPOCHSECONDS"
+  for ((a=1; a<=attempts; a++)); do
+    if tail -n 100 "$logfile" | grep -q "TxFirehose.Submit.Success"; then
+      success=1
+      break
+    fi
+    sleep 20
+  done
+
+  elapsed_time="$((EPOCHSECONDS - start_time))"
+  if [ "$success" -eq 0 ]; then
+    echo "Tx firehose did not start submitting transactions after $elapsed_time seconds, line $LINENO in ${BASH_SOURCE[0]}" >&2
+    exit 1
+  fi
+  echo "Tx firehose started submitting transactions after $elapsed_time seconds"
+}
+
+setup_tx_firehose() {
+  if ! is_truthy "${ENABLE_TX_FIREHOSE:-}"; then
+    return 0
+  fi
+
+  : "${STATE_CLUSTER:?STATE_CLUSTER is required}"
+  : "${SUPERVISORD_SOCKET_PATH:?SUPERVISORD_SOCKET_PATH is required}"
+  : "${NETWORK_MAGIC:?NETWORK_MAGIC is required}"
+
+  local fund_amount="${1:?}"
+  local tps="${TX_TPS:-100}"
+
+  # Unlike tx-generator / tx-centrifuge, tx-firehose does not need a genesis UTxO
+  # key -- it discovers its own funds by address query, so any funded key will do.
+  cardano_cli_log conway address key-gen \
+    --signing-key-file "${STATE_CLUSTER}/shelley/tx-firehose.skey" \
+    --verification-key-file "${STATE_CLUSTER}/shelley/tx-firehose.vkey"
+  cardano_cli_log conway address build \
+    --payment-verification-key-file "${STATE_CLUSTER}/shelley/tx-firehose.vkey" \
+    --out-file "${STATE_CLUSTER}/shelley/tx-firehose.addr" \
+    --testnet-magic "$NETWORK_MAGIC"
+
+  _fund_address \
+    "$(<"${STATE_CLUSTER}/shelley/tx-firehose.addr")" "$fund_amount" "fund-tx-firehose"
+
+  _create_tx_firehose_config \
+    "./pool1.socket" \
+    "./shelley/tx-firehose.skey" \
+    "$NETWORK_MAGIC" \
+    "$tps" > "${STATE_CLUSTER}/tx-firehose-config.json"
+
+  echo "Starting tx-firehose"
+  supervisorctl -s "unix:///${SUPERVISORD_SOCKET_PATH}" start tx_firehose || \
+    { echo "Failed to start tx firehose, line $LINENO in ${BASH_SOURCE[0]}" >&2; exit 1; }
+  _wait_for_tx_firehose_log
+
+  # The tx firehose setup takes time, so we wait for it to start submitting transactions before proceeding
+  echo "Waiting for tx firehose to start submitting transactions"
+  _wait_for_tx_firehose_tx
+}

src/cardonnay_scripts/scripts/common/run-tx-firehose

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+initialize() {
+  local retval=0
+  local socket_path state_cluster
+
+  if [ -z "${CARDANO_NODE_SOCKET_PATH:-}" ]; then
+    echo "CARDANO_NODE_SOCKET_PATH is not set" >&2
+    retval=1
+  fi
+  if ! command -v tx-firehose &> /dev/null; then
+    echo "tx-firehose is not available in PATH" >&2
+    retval=1
+  fi
+  if [ "$retval" -ne 0 ]; then
+    exit "$retval"
+  fi
+
+  socket_path="$(readlink -m "${CARDANO_NODE_SOCKET_PATH:-}")"
+  state_cluster="${socket_path%/*}"
+  readonly FIREHOSE_CONFIG="${state_cluster}/tx-firehose-config.json"
+
+  if [ ! -f "$FIREHOSE_CONFIG" ]; then
+    echo "Firehose config file not found at $FIREHOSE_CONFIG" >&2
+    exit 1
+  fi
+
+  cd "$state_cluster"
+}
+
+wait_for_socket() {
+  for _ in {1..5}; do
+    if [ -S "${CARDANO_NODE_SOCKET_PATH:-}" ]; then
+      return 0
+    fi
+    echo "Waiting for socket ${CARDANO_NODE_SOCKET_PATH:-} to be available..."
+    sleep 5
+  done
+
+  echo "Socket ${CARDANO_NODE_SOCKET_PATH:-} is not available after waiting" >&2
+  exit 1
+}
+
+run_tx_firehose() {
+  local attempt=1
+  local socket testnet_magic signing_key tps inputs_per_tx outputs_per_tx fee max_errors
+
+  socket="$(jq -r '.socket_path' "$FIREHOSE_CONFIG")"
+  testnet_magic="$(jq -r '.testnet_magic' "$FIREHOSE_CONFIG")"
+  signing_key="$(jq -r '.signing_key_file' "$FIREHOSE_CONFIG")"
+  tps="$(jq -r '.tps' "$FIREHOSE_CONFIG")"
+  inputs_per_tx="$(jq -r '.inputs_per_tx' "$FIREHOSE_CONFIG")"
+  outputs_per_tx="$(jq -r '.outputs_per_tx' "$FIREHOSE_CONFIG")"
+  fee="$(jq -r '.fee' "$FIREHOSE_CONFIG")"
+  max_errors="$(jq -r '.max_consecutive_errors' "$FIREHOSE_CONFIG")"
+
+  while true; do
+    wait_for_socket
+
+    echo "Generating transactions..."
+    if tx-firehose \
+      --socket-path "$socket" \
+      --testnet-magic "$testnet_magic" \
+      --signing-key-file "$signing_key" \
+      --tps "$tps" \
+      --inputs-per-tx "$inputs_per_tx" \
+      --outputs-per-tx "$outputs_per_tx" \
+      --fee "$fee" \
+      --max-consecutive-errors "$max_errors"; then
+      attempt=1
+      sleep 15
+    else
+      if [ $attempt -ge 4 ]; then
+        echo "tx-firehose failed after $attempt attempts, exiting." >&2
+        exit 1
+      fi
+      echo "tx-firehose failed, retrying in 5 seconds..." >&2
+      attempt=$((attempt + 1))
+      sleep 5
+    fi
+  done
+}
+
+initialize
+run_tx_firehose

src/cardonnay_scripts/scripts/leios_fast/testnet.json

@@ -11,7 +11,8 @@
         "PROTOCOL_VERSION": "if set, will use the specified protocol version (e.g., 11 for latest Conway, etc.)",
         "ENABLE_TX_GENERATOR": "if set, will configure and start tx-generator",
         "ENABLE_TX_CENTRIFUGE": "if set, will configure and start tx-centrifuge (higher-load, UTxO-reusing successor of tx-generator)",
-        "TX_TPS": "transactions-per-second rate ceiling for tx-generator / tx-centrifuge, default is 100",
+        "ENABLE_TX_FIREHOSE": "if set, will configure and start tx-firehose (single-node, push-based tx load generator over node-to-client)",
+        "TX_TPS": "transactions-per-second rate ceiling for tx-generator / tx-centrifuge / tx-firehose, default is 100",
         "USE_GENESIS_MODE": "if set, will switch to using GenesisMode and peer snapshot file"
     }
 }

src/cardonnay_scripts/scripts/local_fast/testnet.json

@@ -11,7 +11,8 @@
         "PROTOCOL_VERSION": "if set, will use the specified protocol version (e.g., 11 for latest Conway, etc.)",
         "ENABLE_TX_GENERATOR": "if set, will configure and start tx-generator",
         "ENABLE_TX_CENTRIFUGE": "if set, will configure and start tx-centrifuge (higher-load, UTxO-reusing successor of tx-generator)",
-        "TX_TPS": "transactions-per-second rate ceiling for tx-generator / tx-centrifuge, default is 100",
+        "ENABLE_TX_FIREHOSE": "if set, will configure and start tx-firehose (single-node, push-based tx load generator over node-to-client)",
+        "TX_TPS": "transactions-per-second rate ceiling for tx-generator / tx-centrifuge / tx-firehose, default is 100",
         "USE_GENESIS_MODE": "if set, will switch to using GenesisMode and peer snapshot file"
     }
 }

src/cardonnay_scripts/scripts/mainnet_fast/testnet.json

@@ -11,7 +11,8 @@
         "PROTOCOL_VERSION": "if set, will use the specified protocol version (e.g., 11 for latest Conway, etc.)",
         "ENABLE_TX_GENERATOR": "if set, will configure and start tx-generator",
         "ENABLE_TX_CENTRIFUGE": "if set, will configure and start tx-centrifuge (higher-load, UTxO-reusing successor of tx-generator)",
-        "TX_TPS": "transactions-per-second rate ceiling for tx-generator / tx-centrifuge, default is 100",
+        "ENABLE_TX_FIREHOSE": "if set, will configure and start tx-firehose (single-node, push-based tx load generator over node-to-client)",
+        "TX_TPS": "transactions-per-second rate ceiling for tx-generator / tx-centrifuge / tx-firehose, default is 100",
         "USE_GENESIS_MODE": "if set, will switch to using GenesisMode and peer snapshot file"
     }
 }