Transaction Generator - input-output-hk/iohk-monitoring-framework GitHub Wiki

Generating a transaction is selecting inputs (UTxO), outputs, and amounts to transfer. (+ digitally signed)

The input selection is only valid on the set of unspent transaction outputs (UTxO). The transaction will create new UTxO that can be reused in future transactions. Some amount will be spent for the transaction costs and will reduce the available coins in the UTxO. (can we control tx costs? or set to zero?)

Prepare addresses

We receive (at least) 3 signing keys from CLI argument --sig-key. These keys will be used to create 3 addresses:

  1. genesisAddress - an address we send an initial (genesis) funds to. This is the very first transaction.
  2. sourceAddress - an address we use as a source for all further transactions.
  3. recepientAddress - an address we use as a recipient for all further transactions.

Genesis generation

Genesis UTxO is generated from genesis signing key, in extractGenesisFunds function. Currently it's 1.4 billion ADA. Then we prepare initial funds using prepareInitialFunds function: we perform the very first transaction to move all initial funds from genesisAddress to sourceAddress.

Creating additional UTxO entries

Since sourceAddress (after initial transaction) contains all genesis funds, we have one single UTxO entry with 1.4 billion ADA. Now we have to split this amount to required number of UTxO entries, i.e.:

1 UTxO entry (sourceAddress and amount X) -> N UTxO entries (sourceAddress and amount X/N).

So we perform M splitting transactions in createMoreFundCoins function, where M is calculated as N/60. 60 is a number of outputs per 1 splitting transaction (technically 60 is near the upper bound but not exceed the transaction size limit).

The number N of UTxO entries is equal to (or more than) the number of transaction we want to generate (this number is taken from CLI argument --num-of-txs).

Input selection

After we performed splitting transactions, we have N of UTxO entries. All these entries is storing in availableFunds. And when we prepare an input for a new transaction, we just find the first available output that contains sufficient amount of ADA. After we found it, it will be removed from availableFunds.

Transaction generation

After we prepared required number of UTxO entries, we generate defined number of transactions.

All these transactions has the same output(s): recipientAddress and amount A, where A is fixed amount of ADA. Currently A is hardcoded, probably it should be taken from CLI argument.

TPS control

We receive TPS rate from CLI argument --tps. Submitter part is controlling TPS rate.

Configuration

There are following CLI arguments we use to set generator up:

  1. --target-node-id is an id of node we'll send transactions to. Can be specified multiple times.
  2. --sig-key is a path to .key-file (which contains signing key).
  3. --num-of-txs is a number of benchmarking transactions we'll generate.
  4. --inputs-per-tx is a number of inputs per 1 benchmarking transaction.
  5. --outputs-per-tx is a number of outputs per 1 benchmarking transaction.
  6. --tx-fee is a fee per transaction (in Lovelaces).
  7. --tps is a TPS (transactions per second) rate.
  8. --add-tx-size is an additional size of transaction, using TxAttributes (in bytes).

Please note that currently we have to provide at least 3 keys (using --sig-key argument): for genesis address, for source address and for recipient address.

To get help info about generator-related arguments use this command:

$ stack exec -- cardano-cli generate-txs --help

or this one:

$ cabal new-run -- cardano-cli generate-txs --help

Launch

Transaction generator is a part of cardano-cli executable (generate-txs command). It can be launched using scripts/generator.sh script. Example of command:

$ ./scripts/generator.sh --target-node-id 0

where 0 is an id of a node we will send transaction to. Option --target-node-id can be defined multiple times.

Please make sure that local cluster is already launched (for example, using scripts/shelley-testnet.sh script).