Cardano SL CLI Options

This guide describes all executables we use in Cardano SL and all corresponding CLI-options/parameters.

cardano-nodes

An executable cardano-node is our main executable, it’s a node.

Usage:

cardano-node [OPTIONS]

Available options:

  1. --version and --help
    Node version and this help info.
     
  2. --db-path FILEPATH
    Path to the directory with node’s database (called Global State).
    If specified path doesn’n exist, directory will be created.
    Default value: none.
     
  3. --rebuild-db
    If the node’s database already exists, discard its contents and create a new one from scratch.
     
  4. --spending-genesis INT
    Define index of using secret key in genesis.
    Default value: none.
     
  5. --vss-genesis INT
    Define index of using VSS key pair in genesis.
    Default value: none.
     
  6. --keyfile FILEPATH
    Path to the file with a secret key (we use it for Daedalus).
    Specified path must exist.
    Default value: secret.key.
     
  7. --backup-phrase PHRASE
    12-word phrase to recover the wallet. This phrase was generated during wallet’s creation.
    Words should be separated by spaces.
    Default value: none.
     
  8. --listen IP:PORT
    Specify IP-address and port node uses to listen requests from other nodes.
    Default value: 0.0.0.0:3000.
    Please make sure that IP-address and port are accessible, otherwise work of the node isn’t guaranteed.
     
  9. --supporter
    Launch DHT supporter instead of full node.
     
  10. --dht-key HOST_ID
    DHT key in Base64-URL format (we use it for Kademlia instance).
    Default value: none
    Example: --dht-key dYGuDj0BrJxCsTC9ntJE7ePT7wUoVdQMH3sKLzQD8bo=
     
  11. --time-lord
    Node is a time lord, i.e. one responsible for system start time decision & propagation.
    This option is used in development mode only.
     
  12. --stats
    Run full node in benchmarking node (with statistics logging).
     
  13. --json-log FILEPATH
    Path to JSON log file.
    If specified path doesn’t exist, file will be created.
     
  14. --attack TYPE
    Attack type to emulate.
    Possible values: NoBlocks and NoCommitments.
    This option can be used more than once.
    Default value: none.
     
  15. --attack-target HOST:PORT|PUBKEYHASH

    Possible values:
    * HOST:PORT - target defined by its network address.
    * PUBKEYHASH - target defined by its public key address (in Base58 format).
    This option can be used more than once.
    Default value: none.
     
  16. --kademlia-dump-path FILEPATH
    Path to file we use to write Kademlia snapshot in.
    If specified path doesn’t exist, file will be created.
    Default value: kademlia.dump.
     
  17. --web
    Run web server (node’s web API, it’s not linked with a wallet web API).
     
  18. --web-port PORT
    Port for web server.
    Please make sure you use --port option as well, otherwise this value will be ignored.
    Default value: 8080.
     
  19. --wallet
    Runs Daedalus Wallet web API (node will be able to accept requests from the wallet).
     
  20. --wallet-port PORT
    Port for Daedalus Wallet web API.
    Please make sure you use --wallet option as well, otherwise this value will be ignored.
    Default value: 8090.
     
  21. --wallet-db-path FILEPATH
    Path to the wallet’s database.
    Specified path must exist.
    Default value: none.
     
  22. --wallet-rebuild-db
    If the wallet’s database already exists, discard its contents and create a new one from scratch.
     
  23. --wallet-debug
    Run wallet with debug parameters (e.g. include all the genesis keys in the set of secret keys).
     
  24. --explicit-initial
    Explicitly connect to initial peers as to neighbors (even if they appeared offline once).
     
  25. --peer HOST:PORT/HOST_ID
    Peer to connect to for initial peer discovery.
    This option can be used more than once.
    Example: --peer localhost:1234/dYGuDj0BrJxCsTC9ntJE7ePT7wUoVdQMH3sKLzQD8bo=
    Default value: none.
     
  26. --peers-file FILEPATH
    Path to file with peers list (peers must be separated by newlines).
    Default value: none.
     
  27. --log-config FILEPATH
    Path to logger configuration file.
    Default value: hardcoded default logger configuration.
     
  28. --logs-prefix FILEPATH
    Prefix to logger output path.
    Specified path must be valid.
    Default value: none.
     
  29. --ssc-algo ALGO
    Shared Seed Calculation algorithm which nodes will use.
    Possible values: GodTossing and NistBeacon.
    Default value: GodTossing.
     
  30. --disable-propagation
    Disable network propagation (transactions, SSC data, blocks). I.e. all data is to be sent only by entity who creates data and entity is yosend it to all peers on his own.
     
  31. --report-server URL
    URL of reporting server to send crash/error logs on.
    This option can be used more than once.
    Example: --report-server https://my.report.server.com:4000
     
  32. --update-server URL
    URL of the server to download updates from.
    This option can be used more than once.
    Example: --update-server https://my.update.server.com:3000
     
  33. --flat-distr (INT,INT)
    Use flat stake distribution with given parameters. Flat distribution means that each node has the same amount of coins.
    Format: (nodes, coins), both numbers must be positive.
    This option is used in development mode only.
    Please make sure you don’t use --bitcoin-distr option with this one.
    Default value: none.
    Example: --flat-distr "(3, 100000)"
     
  34. --bitcoin-distr (INT,INT)
    Use bitcoin stake distribution with given parameters. Bitcoin distribution is a Bitcoin mining pool-style ditribution.
    Format: (nodes, coins), both numbers must be positive.
    This option is used in development mode only.
    Please make sure you don’t use --flat-distr option with this one.
    Default value: none.
    Example: --bitcoin-distr "(3, 100000)"
     
  35. --exp-distr
    Enable exponential distribution. It means that first three nodes get 0.875% of stake.
    This option is used in development mode only.
     
  36. --update-latest-path FILEPATH
    Path to update installer file, which should be downloaded by Update System.
    Default value: update-installer.exe.
     
  37. --update-with-package
    Enable updating via installer.
     
  38. --monitor-port INT
    Port we use to run web monitor on. Monitor mechanism is a part of time-warp-nt package.
     

Example of cardano-node command:

stack exec -- cardano-node \
    --listen 0.0.0.0:12100 \
    --report-server http://34.146.164.19:5555 \
    --wallet \
    --keyfile secret.kea\
    --logs-prefix "logs/abc" \
    --db-path db-abc \
    --peer 127.0.0.1:3000/S-GJ1HDZyHpIS_ZOFBlZsipkGNXy-tmCDtY_CvaiywE= \
    --kademlia-dump-path kademlia-abc.dump

cardano-web-docs

An executable cardano-web-docs is used for building documentation of cardano-node web API (see cardano-node above).

cardano-web-docs hasn’t any options or parameters, it runs and produce web-api.md file in the current directory.

cardano-launcher

Please read Cardano SL Launcher guide for info about cardano-launcher executable.

cardano-genupdate

An executable cardano-genupdate is used for generation of update. There’s no CLI-options, only 3 mandatory parameters:

cardano-genupdate [OLD_DIR] [NEW_DIR] [OUTPUT_TAR_FILE]

where:

  1. OLD_DIR - path to a directory with a program, old version. Path must exist.
  2. NEW_DIR - path to a directory with a program, new version. Path must exist.
  3. OUTPUT_TAR_FILE - path to output .tar-file with diff (based on a difference between old version and new one).

Both directories must have equal file structure (e.g. they must contain the same files in the same subdirectories correspondingly), otherwise cardano-genupdate will fail.

Example of cardano-genupdate command:

stack exec -- cardano-genupdate /tmp/v000 /tmp/v001 /tmp/update.tar

Important: cardano-genupdate uses bsdiff program, so command bsdiff must be available in the PATH.

cardano-wallet-hs2purs

An executable cardano-wallet-hs2purs is used for generating PureScript types based on Haskell types. We use it to build Daedalus wallet.

cardano-wallet-hs2purs hasn’t any options or parameters, it runs in Cardano SL root directory and produce .purs files in daedalus/src/Generated subdirectory.

cardano-analyzer

An executable cardano-analyzer is an analyzer of JSON log files. It extracts TPS info and store statistics in .csv-file.

Available options:

  1. --version and --help
    Show version and this help info.
     
  2. --file FILEPATH
    Path to JSON log to analyze.
    Specified path must exist.
    Mandatory option.
    This option can be used more than once.
    Default value: none.
     
  3. --tx-file FILEPATH
    Path to JSON file generated by txSender (txSenderMap).
    If this option is defined, cardano-analyzer shows a number of transactions which are sent and accepted.
     
  4. -k, --confirmation ARG
    How many blocks are needed for confirmation.
    Default value: none.
     

Example of cardano-analyzer command:

stack exec -- cardano-analyzer --file node2.json

Name of the result file is formed from the value of --file option. Thus, in this example result will be written in node2-tps.csv file.

cardano-avvmmigrate

An executable cardano-avvmmigrate is an AVVM converter. AVVM is a mechanism people buy ADA-certificates with. ADA-certificate is a special document with seed for generation of key pair. We’re storing public key only and bind money to it. So cardano-avvmmigrate takes JSON file with “address + money” pairs and generates special binary file with that info. Based on this binary file the node knows genesis utxo.

Example of part of an input JSON file:

{
    "utxo": [{
        "coin": {
                "coinAmount": 413368,
                "coinColor": {
                        "getColor": 10
                }
        },
        "address": "0TXMbbVfRFCfkWCklo9Qc3V71HlsTAQNQXDPryOE5kk="
    }, {
        "coin": {
                "coinAmount": 421370,
                "coinColor": {
                        "getColor": 10
                }
        },
        "address": "47gm-3YJrxBW4tROcNu5Mi6mfc4Fe8RxDgQjGaFIgEA="
    ...
}

There’s no options, just 3 mandatory parameters:

cardano-avvmmigrate PATH_TO_JSON BIN_OUTPUT_FILE CERT_INFO

where - random certificate will be generated.:

  1. PATH_TO_JSON - path to JSON file with AVVM data. Path must exist.
  2. BIN_OUTPUT_FILE - path to output binary file (recommend extension is .bin).
  3. CERT_INFO - flag whether to generate random certificates. Possible values - nocerts and randcerts. If the value is randcerts - random certificate will be generated.

Example of cardano-avvmmigrate command:

stack exec -- cardano-avvmmigrate /tmp/utxo.json /tmp/avvm.bin nocerts

cardano-checks

An executable cardano-checks is an extractor of special check-comments. We need it to review all checks and verifications we have, such as receiving block/tx/whatever.

These comments are based on CHECK word, for example in Pos.Txp.Toil.Utxo.Pure module:

-- CHECK: @TxUtxoPure

cardano-checks extracts all such comments from our modules and store them in result document.

Usage:

cardano-checks SOURCE_DIR OUTPUT_FILE

where:

  1. SOURCE_DIR - path to a directory with Haskell source code.
  2. OUTPUT_FILE - path to result document, in Markdown format.

Example of cardano-checks command:

stack exec -- cardano-checks /tmp/cardano-sl /tmp/checks.md

Example of result document:

## Module Pos.Crypto.SecretSharing
Verify an encrypted share using SecretSharingExtra.
_(line 182)_
Verify that Share has been decrypted correctly.
_(line 188)_
Verify that SecretProof corresponds to Secret.
_(line 194)_
## Module Pos.Crypto.Signing
Verify a signature.

cardano-keygen

An executable cardano-keygen is a generator of keyfiles.

Available options:

  1. -h and --help
    Show this help info and exit.
     
  2. -f, --file-pattern PATTERN
    Filename pattern for generated keyfiles. Symbols {} is a placeholder for keyfile’s number (not index). Pattern cannot be empty.
    Mandatory option.
    Default value: none.
    Example: -f "key{}".
    For instance, if we generate two keyfiles, result will be key1 and key2.
     
  3. --genesis-file FILEPATH
    Path to file to dump binary shared genesis data in.
    Default value: genesis.bin.
     
  4. -n, --total-stakeholders INT
    Total number of keyfiles to generate.
    Mandatory option.
    Default value: none.
     
  5. -m, --richmen INT
    Number of richmen among stakeholders.
    Mandatory option.
    Default value: none.
     
  6. --total-stake INT
    Total coins number in genesis.
    Mandatory option.
    Default value: none.
     

Example of cardano-keygen command:

stack exec -- cardano-keygen -f "key{}" -n 1 -m 1 --total-stake 1

cardano-dht-keygen

An executable cardano-dht-keygen is a generator of random key for Kademlia DHT.

cardano-dht-keygen hasn’t any options, only 1 mandatory parameter NONCE, 14-characters string.

Example of cardano-dht-keygen command:

cardano-dht-keygen 00000000000001

Example of result:

Y94xf23cG8as4ycA9R-cvo9zMDAwMDAwMDAwMDAwMDE=

Please make sure that nonce’ lenght has exactly 14 characters.

cardano-wallet

An executable cardano-wallet is a CLI-based wallet + node. You can think of cardano-wallet as a node wrapped by wallet’s functionality (without Daedalus).

Usage:

cardano-wallet [OPTIONS] COMMAND

Available options:

  1. -h and --help
    Show this help info and exit.
     
  2. --db-path FILEPATH
    Path to the directory with wallet’s database.
    Specified path must exist.
    Default value: none.
     
  3. --rebuild-db
    If the wallet’s database already exists, discard its contents and create a new one from scratch.
     
  4. --listen IP:PORT
    Specify IP-address and port node uses to listen requests.
    Default value: 0.0.0.0:24961.
    Please make sure these IP-address and port are accessible, otherwise work of the node isn’t guaranteed.
     
  5. --peer HOST:PORT/HOST_ID
    Peer to connect to for initial peer discovery.
    This option can be used more than once.
    Example: --peer localhost:1234/dYGuDj0BrJxCsTC9ntJE7ePT7wUoVdQMH3sKLzQD8bo=
    Default value: none.
     
  6. --peers-file FILEPATH
    Path to file with peers list (peers must be separated by newlines).
    Default value: none.
     
  7. --log-config FILEPATH
    Path to logger configuration file.
    Default value: hardcoded default logger configuration.
     
  8. --logs-prefix FILEPATH
    Prefix to logger output path.
    Specified path must be valid.
    Default value: none.
     
  9. --ssc-algo ALGO
    Shared Seed Calculation algorithm which nodes will use.
    Possible values: GodTossing and NistBeacon.
    Default value: GodTossing.
     
  10. --report-server URL
    URL of reporting server to send crash/error logs on.
    This option can be used more than once.
    Example: --report-server https://my.report.server.com:4000.
     
  11. --update-server URL
    URL of the server to download updates from.
    This option can be used more than once.
    Example: --update-server https://my.update.server.com:3000.
     
  12. --flat-distr (INT,INT)
    Use flat stake distribution with given parameters.
    Format: (nodes, coins), both numbers must be positive.
    This option is used in development mode only.
    Please make sure you don’t use --bitcoin-distr option with this one.
    Default value: none.
    Example: --flat-distr "(3, 100000)"
     
  13. --bitcoin-distr (INT,INT)
    Use bitcoin stake distribution with given parameters.
    Format: (nodes, coins), both numbers must be positive.
    This option is used in development mode only.
    Please make sure you don’t use --flat-distr option with this one.
    Default value: none.
    Example: --bitcoin-distr "(3, 100000)"
     
  14. --json-log FILEPATH
    Path to JSON log file.
    If specified path doesn’t exist, file will be created.
     
  15. --explicit-initial
    Explicitly connect to initial peers as to neighbors (even if they appeared offline once).
     
  16. --disable-propagation
    Disable network propagation (transactions, SSC data, blocks). I.e. all data is to be sent only by entity who creates data and entity is yosend it to all peers on his own.
     
  17. --exp-distr
    Enable exponential distribution.
    This option is used in development mode only.
     
  18. --keys-path FILEPATH
    Path to the file with secret keys.
     
  19. --debug
    Run in debug mode (with genesis keys included).
     

Avaliable commands:

  1. repl
    Run REPL mode in console to evaluate additional commands.
     
  2. cmd
    Execute a list of predefined additional commands (if more than one command, they must be comma-separated).
    Option cmd is used with an additional --commands option.
    Example: cardano-wallet cmd --commands "propose-update 0 0.0.0 0 7 2000000 cardano-1".

     
  3. serve
    Serve Daedalus web API on a given port.
     

Avaliable additional commands with parameters:

  1. balance ADDRESS
    Check balance on a given ADDRESS.
     
  2. send OWN_ADDRESS_INDEX [ADDRESS COINS]+
    Create and send transaction with given outputs (formed from ADDRESS and COINS number) from own address OWN_ADDRESS_INDEX.
    We can send transactions to more than one address.
     
  3. vote OWN_ADDRESS_INDEX DECISION UPDATE_PROPOSAL_ID
    Send a vote with given hash of UPDATE_PROPOSAL_ID (in Base64 format) and DECISION, from own address OWN_ADDRESS_INDEX.
    Positive DECISION can be formed as +, y or yes.
    Negative DECISION can be formed as -, n or no.
     
  4. propose-update OWN_ADDRESS_INDEX BLOCK_VERSION SCRIPT_VERSION SLOT_DURATION MAX_BLOCK_SIZE SOFTWARE_VERSION [PROPOSE_FILE]
    Propose an update with given versions and other data with one positive vote for it, from own address OWN_ADDRESS_INDEX.
    Parameter BLOCK_VERSION must be formed as INT.INT.INT, for example 0.2.0.
    Parameters SCRIPT_VERSION, SLOT_DURATION and MAX_BLOCK_SIZE are integers.
    Parameter SOFTWARE_VERSION must be formed as APP_NAME-VERSION, for example cardano-2.
    Parameter PROPOSE_FILE is an optional one.
     
  5. listaddr
    Show a list of own addresses.
     
  6. delegate-light SECRET_KEY_INDEX PUBLIC_KEY_INDEX
    Delegate issuer’s secret key SECRET_KEY_INDEX (genesis) to delegate’s PUBLIC_KEY_INDEX (genesis), light version.
     
  7. delegate-heavy SECRET_KEY_INDEX PUBLIC_KEY_INDEX
    Delegate issuer’s secret key SECRET_KEY_INDEX (genesis) to delegate’s PUBLIC_KEY_INDEX (genesis), heavyweight version.
     
  8. help
    Show this message and exit.
     
  9. quit
    Shutdown node wallet.
     

cardano-smart-generator

An executable cardano-smart-generator is a generator for transaction. You can think of cardano-smart-generator as of “node in the real world”, because we start a stress test for a node to see an actual number of generated transactions per seconds (TPS). Please read this guide’s part for more info about cardano-smart-generator.

Usage:

cardano-smart-generator [OPTIONS]

Please be careful, some options are mandatory, see below. Most of the options are the same as for cardano-node executable.

Available options:

  1. -h, --help
    Print this help info and exit.
     
  2. --listen IP:PORT
    Specify IP-address and port node uses to listen requests.
    Default value: 0.0.0.0:24962.
    Please make sure these IP-address and port are accessible, otherwise work of the node isn’t guaranteed.
     
  3. --exp-distr
    Enable exponential distribution.
    This option is used in development mode only.
     
  4. --flat-distr (INT,INT)
    Use flat stake distribution with given parameters.
    Format: (nodes, coins), both numbers must be positive.
    This option is used in development mode only.
    Please make sure you don’t use --bitcoin-distr option with this one.
    Default value: none.
    Example: --flat-distr "(3, 100000)"
     
  5. --bitcoin-distr (INT,INT)
    Use bitcoin stake distribution with given parameters.
    Format: (nodes, coins), both numbers must be positive.
    This option is used in development mode only.
    Please make sure you don’t use --flat-distr option with this one.
    Default value: none.
    Example: --bitcoin-distr "(3, 100000)"
     
  6. --report-server URL
    URL of reporting server to send crash/error logs on.
    This option can be used more than once.
    Example: --report-server https://my.report.server.com:4000
     
  7. --update-server URL
    URL of the server to download updates from.
    This option can be used more than once.
    Example: --update-server https://my.update.server.com:3000
     
  8. --peer HOST:PORT/HOST_ID
    Peer to connect to for initial peer discovery.
    This option can be used more than once.
    Example: --peer localhost:1234/dYGuDj0BrJxCsTC9ntJE7ePT7wUoVdQMH3sKLzQD8bo=
    Default value: none.
     
  9. --peers-file FILEPATH
    Path to file with peers list (peers must be separated by newlines).
    Default value: none.
     
  10. --log-config FILEPATH
    Path to logger configuration file.
    Default value: hardcoded default logger configuration.
     
  11. --logs-prefix FILEPATH
    Prefix to logger output path.
    Specified path must be valid.
    Default value: none.
     
  12. --json-log FILEPATH
    Path to JSON log file.
    If specified path doesn’t exist, file will be created.
     
  13. --disable-propagation
    Disable network propagation (transactions, SSC data, blocks). I.e. all data is to be sent only by entity who creates data and entity is yosend it to all peers on his own.
     
  14. --explicit-initial
    Explicitly connect to initial peers as to neighbors (even if they appeared offline once).
     
  15. --ssc-algo ALGO
    Shared Seed Calculation algorithm which nodes will use.
    Possible values: GodTossing and NistBeacon.
    Default value: GodTossing.
     
  16. -i, --index INT
    Index in list of genesis key pairs.
    This option can be used more than once.
    Default value: none.
     
  17. -R, --round-period-rate ARG
    R, where duration of one round is ((k + P) * (R + 1)) * slotDuration. k is a security parameter from the protocol’s paper.
    Default value: 2.
     
  18. -N, --round-number ARG
    Number of testing rounds.
    Mandatory option.
     
  19. -p, --round-pause ARG
    Pause between rounds (in seconds).
    Default value: 0.
     
  20. --init-money ARG
    How many coins node has in the beginning.
    Mandatory option.
     
  21. -t, --tps DOUBLE
    TPS value (transactions per second).
    Mandatory option.
     
  22. -S, --tps-step DOUBLE
    TPS increase delta on stable system.
    Default value: 10.
     
  23. -P, --propagate-threshold ARG
    Approximate number of slots needed to propagate transactions across the network.
    Default value: 1.
     
  24. --recipients-share ARG
    Which portion of neighbours to send on each round.
    Default value: 1.
     
  25. --m-of-n (M, N)
    If enabled, send M-of-N transactions instead of regular ones.
     

Example cardano-smart-generator command:

stack exec -- cardano-smart-generator \
    -i 0 \
    --explicit-initial \
    --disable-propagation \
    --peer 35.157.97.210:3000/MHdrsP-oPf7UWl0007QuXnLK5RD= \
    -R 4 \
    -N 100 \
    -p 30 \
    --init-money 60000000 \
    -t 1 \
    -S 1 \
    -P 2 \
    --recipients-share 0.3 \
    --log-config static/txgen-logging.yaml \
    --json-log txgen.json \
    --mempool-validation \
    --ssc-algo NistBeacon \
    --flat-distr "(80,60000000)"