ADR-05: run trace against testnet

[andrey-kuprianov]

Background/Motivation

The user has generated a test trace in the ITF format, and wants to execute it against the testnet, so that to make sure the testnet behaves as expected.

Linked documents: ADR

Description

The format of the proposed CLI command is:

atomkraft run <trace>

where:

• <trace> is the (path to) ITF trace;

Upon successful execution the user is notified about it; no further action is necessary. Upon unsuccessful execution, the error should be presented to the user, and all the information needed to reproduce the error should be saved (details to be clarified).

Prerequisites

• Atomkraft can communicate with the blockchain (init command has been successful)
• The blockchain reactor is available (reactor command has been executed, and the user has filled the reactor stub with the method implementations)
• The reactor has all methods implemented correctly

Technical details

• The implementation should be able to efficiently check the above prerequisites.
  • E.g. for the first two, the project configuration should hold the entries, showing that the respective commands have been executed.
  • The pointers to the setup script, and to the reactor should be present in the configuration, such that they are picked up by this implementation.
• While the above commands could have been executed successfully, it doesn't guarantee that the pieces match together. E.g. the errors below may happen, and should be differentiated from the real errors (mismatch of trace expectations to the behavior of the blockchain)
  • init might have been executed, but the blockchain binary was moved, or vanished from the PATH, or changed.
  • reactor has been executed, but the list of actions for which the stub was generated doesn't cover all actions present in the trace.
  • Reactor stub has been filled, but the file doesn't compile, or some error in one of the action handlers occurs at runtime.
• When a real error in the testnet occurs:
  • the error summary needs to be presented to the user
  • the error details need to be saved, for possible later inspection:
    • the trace
    • the blockchain configuration
    • the setup and reactor scripts
    • the complete output

[ivan-gavran]

The description looks good.

There is one major thing worth discussing in our meeting: this issue uses a lot the statefulness of the CLI.
Is this a good thing, to assume CLI to be stateful? I am unsure.

If we decide to have a stateful CLI, then we need to agree on how all the components would communicate (e.g., a shared config files with flags corresponding to whether prerequisite commands have been executed, which reactor file to use etc.).

If, on the contrary, we decide against sharing state, then the command atomkraft run trace reactor chain.

I am genuinely unsure about whether having a stateful CLI is good or bad (not advocating for the latter).