Cardano SL Launcher

Overview

An executable cardano-launcher is a tool for launching Cardano SL. It actually runs the whole Cardano SL system (i.e. a node, a wallet) and handles updates.

You can run it with --help flag to see this usage info:

$ cardano-launcher --help
Usage: cardano-launcher --node PATH [-n ARG] [--node-log PATH] [--wallet PATH]
                        [-w ARG] --updater PATH [-u ARG] [--update-archive PATH]
                        --node-timeout SEC [--report-server URL]
  Tool to launch Cardano SL

Available options:
  -h,--help                Show this help text
  --node PATH              Path to the node executable
  -n ARG                   An argument to be passed to the node
  --node-log PATH          Path to the log where node's output will be dumped
  --wallet PATH            Path to the wallet executable
  -w ARG                   An argument to be passed to the wallet
  --updater PATH           Path to the updater executable
  -u ARG                   An argument to be passed to the updater
  --update-archive PATH    Path to the update archive (will be passed to the
                           updater)
  --node-timeout SEC       Amount of time to wait for the node to exit before killing it
  --report-server URL      Where to send logs in case of failure

For example (run via stack):

$ stack exec cardano-launcher --                     \
    --node /tmp/blah-v000/node                       \
    --node-timeout 5                                 \
    --updater /bin/cardano-updater -u dir -u /tmp/n  \
    --update-archive /tmp/cardano-update.tar

cardano-node is a node application.

cardano-updater is a separate application for the node updates (see an explanation below). Arguments -u and --update-archive will be passed to the updater. Please note that cardano-updater is not the only updater allowed, so arguments -u and --update-archive may appear unnecessary.

Node timeout is explained below.

Scenarios

There are two work scenarios for cardano-launcher: desktop and server. If you provide a path to the wallet (e.g. Daedalus) using --wallet argument during start, cardano-node will run in desktop scenario, otherwise it will run in server one.

Server Scenario

After the start, there are 2 steps:

  1. Running an updater.
  2. Running a node.

Updater’s work is explained below.

A node is spawning as a separate process. After that we just wait until the node stops. After a node exits, its exit code is checked. If it equals 20, we restart the launcher, otherwise we quit.

Log info can be written to the log file before quitting. To do it, we must provide two additional arguments during launcher’s start: --report-server and --node-log. The first argument defines an URL of the report server, the second one defines a path to the log file. We asynchronously send log info to the report server via POST-request. Please note that the file from the --node-log argument must exist.

Desktop Scenario

As the process starts, there are 3 steps:

  1. Running an updater.
  2. Running a node.
  3. Running a wallet.

For steps 1 and 2, see Server Scenario above.

The wallet is spawning as a separate process.

After that, we wait until node or wallet stops. When it stops, we check it:

  1. If the node exits, we write a log (see Server Scenario above for explanations) and wait for the wallet death.
  2. If the wallet exits, we check the exit code, and if it equals 20, we kill the node and restart the launcher in the desktop scenario. Please note that killing the node isn’t executed immediately; the node is killed after some timeout, and its value is obtained from the --node-timeout argument mentioned above.
  3. If the wallet exits and exit code isn’t equal to 20, we kill the node immediately.

Updater

Another important thing cardano-launcher does is updating a node. The first step in both scenarios is running an updater. Please note that if the executable file in the --updater argument doesn’t exist, updating will be skipped.

The core idea is very simple. The node update is a special .tar-archive: it represents the difference between the old (current) version of the node and a new version of it. A path to this archive is obtained via --update-archive argument. So, cardano-updater applies this archive to the node, and after restart a new version of the node can be used.

Please note that when we run cardano-launcher in desktop scenario, a wallet’s user is able to see that an update is ready, and there are two situations possible.

If a user agrees to apply this update, the wallet exits immediately with an exit code 20. In this case, as described above, launcher restarts the node and the update is applied.

If a user doesn’t agree to apply this update, the wallet continues working. But when it is restarted (sooner or later), that update will be applied.

Important: the updater runs synchronously, we start it and then wait for it to finish. If the updater finishes its work successfully, the.tar-archive is deleted.