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. To do this, cardano-launcher uses two separate tools: cardano-node and cardano-updater.

Please see cardano-launcher’s description for detailed information about available options.

Scenarios

There are two work scenarios for cardano-launcher: client scenario and server scenario. If you provide a path to the wallet (e.g. Daedalus) using --wallet argument during start, cardano-node will run in client 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. Please note that the file from the --node-log argument must exist.

Client 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’s 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 client 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.

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 the client 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.

Implementation Overview

For more implementation details about Cardano SL Update system please see this chapter.