Skip to content

Transaction Generator: Usage Guide

Jump to bottom
Denis Shevchenko edited this page Sep 25, 2019 · 32 revisions

This page describes how to build transaction generator, launch it and check the results.

Generator command

Currently transaction generator is a part of cardano-cli executable and corresponds to generate-txs subcommand.

Build generator

$ git clone [email protected]:input-output-hk/cardano-node.git
$ cd cardano-node
$ cabal new-update
$ cabal new-build all

Now cardano-cli executable is available via cabal new-run command.

Launch a Cluster

The purpose of transaction generator is to generate a lot amount of transactions, so we need a cluster from cardano-nodes to submit these transactions to. Currently we can run minimal local cluster (only 3 nodes) using scripts/shelley-testnet.sh from the root of cardano-node repository. Example of command:

$ tmux
$ ./scripts/shelley-testnet.sh

Please note that you have to launch this cluster in the tmux session. By default you will see 4 tmux panes with 3 running cardano-nodes.

Launch a Generator

To launch a generator use scripts/generator.sh script from the root of cardano-node repository. Example of command:

$ ./scripts/generator.sh -n 0

where -n 0 is an index of the node we're going to talk with. Since we already have a working cluster (see above) we have to choose some node to submit generated transactions to, by default we take the first node.

CLI arguments

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

  1. --sig-key is a path to .key-file (which contains signing key).
  2. --num-of-txs is a number of benchmarking transactions we'll generate.
  3. --outputs-per-tx is a number of outputs per 1 benchmarking transaction.
  4. --tx-fee is a fee per transaction (in Lovelaces).
  5. --tps is a TPS (transactions per second) rate.

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.

Transactions

Transacrion generator generates 3 "kinds" of transactions:

  1. genesis transaction,
  2. splitting transactions,
  3. benchmarking transactions.

Genesis transaction is a very first transaction: we move huge amount of ADA from genesisAddress to sourceAddress. And sourceAddress will be used as a source for all further transactions.

The purpose of splitting transactions is to split huge amount of ADA on sourceAddress to sufficient number of "coins" we will use for further transactions. Technically we split initial amount of money M to N equal parts, as a result we'll have N UTxO entries, and alltogether these entries will contain the same amount M (e.g. 1 initial entry * 1000 ADA -> 10 entries * 100 ADA). These UTxO entries will be used as inputs for benchmarking transactions.

Benchmarking transactions are the main ones because they will be used for a system benchmarking. CLI arguments --num-of-txs and --outputs-per-tx specify total number of benchmarking transactions and number of outputs in each of them. Currently each benchmarking transaction has only 1 input and K outputs (corresponding to --outputs-per-tx value), each output sends fixed amount of money to recipientAddress.

Check blockchain: local Cardano Explorer

Since we have a local cluster we are sending transactions to, it is possible to launch cardano-explorer-node to check our local blockchain.

It is recommended to use nix to build cardano-explorer-node:

$ git clone [email protected]:input-output-hk/cardano-explorer.git
$ cd cardano-explorer
$ nix-build -A scripts.mainnet.exporter -o launch_mainnet_exporter

Then set CARDANO_NODE_SOCKET_PATH variable:

export CARDANO_NODE_SOCKET_PATH=/path/to/socket

where /path/to/socket is an absolute path to a socket of some node from our local cluster. For example, in my case it is:

export CARDANO_NODE_SOCKET_PATH=/home/shevchenko/cardano-node/socket/node1.socket

It will be used to connect to the node and listen to the blockchain.

Now explorer can be launched by launch_mainnet_exporter script. But please make sure it contains a valid genesis hash value! cardano-explorer-node executable has a CLI argument --genesis-hash, and this value should be equal to genesis hash of the node we are going to connect to. To get this hash use following commands:

$ cd cardano-node
$ cabal new-run -v0 -- cardano-cli --log-config configuration/log-configuration.yaml --real-pbft print-genesis-hash --genesis-json configuration/33873/genesis.json --socket-path socket/node1.socket

You will see something like this:

33873aeaf8a47fefc7c2ea3f72e98a04459e07ec3edfb63c9ca709f540f69503

This value should be provided to cardano-explorer-node via CLI argument --genesis-hash.

In case of success, right after launching you will see something like this:

$ ./launch_mainnet_exporter
/home/shevchenko/Code/cardano-explorer/pgpass
[iohk.cardano.explorer-db-node:Info:1] [2019-09-25 06:56:43.97 UTC] Initial genesis distribution present and correct
[iohk.cardano.explorer-db-node:Info:1] [2019-09-25 06:56:44.00 UTC] Total genesis supply of Ada: 7998949166.000000
[iohk.cardano.explorer-db-node:Info:1] [2019-09-25 06:56:44.00 UTC] Starting node client
[iohk.cardano.explorer-db-node:Info:1] [2019-09-25 06:56:44.00 UTC] localInitiatorNetworkApplication: connecting to node via "/home/shevchenko/Code/cardano-node/socket/node1.socket"
[iohk.cardano.explorer-db-node:Info:39] [2019-09-25 06:56:44.00 UTC] Starting chainSyncClient
[iohk.cardano.explorer-db-node:Info:39] [2019-09-25 06:56:44.01 UTC] Explorer DB tip is at slot 131826

Cardano Explorer DB

Since Cardano Explorer uses database to store an information, it is assumed that you have installed and configured PostgreSQL. You can find database schema here.

To drop Explorer's database completely:

postgres@linux:~$ dropdb cexplorer -U cexplorer

To create Explorer's database from scratch:

postgres@linux:~$ createdb cexplorer -U cexplorer

To work with this database:

postgres@linux:~$ psql cexplorer -U cexplorer

Current structure of this database is this one:

cexplorer=# \dt
              List of relations
 Schema |      Name      | Type  |   Owner
--------+----------------+-------+-----------
 public | block          | table | cexplorer
 public | meta           | table | cexplorer
 public | schema_version | table | cexplorer
 public | slot_leader    | table | cexplorer
 public | tx             | table | cexplorer
 public | tx_in          | table | cexplorer
 public | tx_out         | table | cexplorer
(7 rows)

To check blocks:

cexplorer=# SELECT * FROM block;

As you can see, hash of the first block is equal to --genesis-hash (see above).

Cardano Explorer DB: troubleshooting

If you stuck with an error psql: FATAL: Peer authentication failed for user "cexplorer", you probably need to change PostgreSQL configuration files. Examples:

$ cat pg_hba.conf
local all all ident map=explorer-users
local all shevchenko trust
local all all ident

host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5

$ cat pg_ident.conf
explorer-users /root cexplorer
explorer-users /postgres cexplorer
explorer-users /shevchenko cexplorer

$ cat postgresql.conf
data_directory = '/var/lib/postgresql/11/main'          
hba_file = '/etc/postgresql/11/main/pg_hba.conf'        
ident_file = '/etc/postgresql/11/main/pg_ident.conf'    
log_destination = 'stderr'
listen_addresses = 'localhost'
port = 5432
Clone this wiki locally