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       How much 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 allowed updater, 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.

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

We can write log info in 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

After the start, 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 too.

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

  1. If the node exits, we write a log (see Server Scenario above for explanations) and wait for a wallet death.
  2. If the wallet exits, we check the exit code, and if it equals 20, we kill a node and restart the launcher in the desktop scenario. Please note that killing a node isn’t executed immediately; a 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 a 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 a 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, .tar-archive will be deleted.