@alessiodf/round-monitor NPM

✅ Round Monitor

Introduction

This repository contains the Round Monitor plugin. It provides the following functionality for ARK Core 3.0 and later blockchains:

Logging of:

The full forging order for each round as it starts.
How long is left until your delegate is due to forge in the current round.
The estimated time remaining in the current round.
A list of the next few delegates about to forge.
A visual indicator of whether you forged successfully (✅) or not (❌).

An additional HTTP server with endpoints to:

Execute a safe restart of the node which will only run when there is sufficient time to ensure you do not miss a block.
Cancel a pending safe restart.

Safe restarting when executing any of the following ark CLI commands:

config:cli
monitor:restart
reinstall
update

The logging options are configurable and, by default, the HTTP server is only accessible on the local node for security reasons.

Installation

Execute the following command: ark plugin:install @alessiodf/round-monitor. Once the plugin is installed, you can enable it by executing ark monitor:enable and then restart your processes when prompted. That's all you need to do to run Round Monitor with the default settings.

If you're using a bridgechain or fork, you may need to replace ark in the commands above with the name of your blockchain instead.

If you wish, you can customise its behaviour by configuring it.

Running

The plugin will start whenever the Core or Relay process is running. All being well, additional lines will begin to appear in your Core or Relay log files.

It will automatically detect any configured delegates on the node assuming BIP38 is not used.

Some example log lines are as follows:

INFO : Time until we forge: 8s (alessio) [11/51: geops/alessio/arktoshi] [5m 20s]

This tells us that alessio is 8 seconds away from the opening of its forging slot, that we are currently 11 delegates into the current round of 51, that the next three forgers are geops, alessio and arktoshi and that the round is due to end in 5 minutes and 20 seconds.

INFO : Time until we forge: 6m 40s (alessio) ✅ [6m 40s] [13/51: cactus1549/echo/brohan] [5m 4s]

The check mark shows that alessio forged successfully in this round and the block has been received and accepted by the local relay node.

You may be wondering why we might forge again in 6 minutes and 40 seconds since we've already forged in the round and the round is scheduled to end in only 5 minutes and 4 seconds. That is because the round end time is only an estimate as it depends on 51 delegates (in the case of ARK) forging successfully, so, in theory, if several other delegates miss their blocks, the round time will be extended for each delegate that misses its block, so we could get to forge again in the same round.

INFO : Time until we forge: 3m 28s (alessio) ❌ [3m 28s] [34/51: cams_yellow_jacket/blues_for_alice/kaos] [2m 16s]

The cross tells us that our local relay node did not receive a block from alessio when it was expected, which is indicative that we did not forge successfully.

INFO : Time until we forge: 3m 44s (alessio) ✅ [3m 44s] [46/51: bigfriendlymaniac/friendsoflittleyus/fun] [40s] [Waiting to restart]

We have requested a restart but it is not safe to do so yet, so we are waiting. In this case it is not safe to restart even though we have already forged in the round because the round is due to end in approximately 40 seconds, and we don't know where we will appear in the following round, so the restart may not complete in time if we forge early in the next round.

Safe Restarting

One of the main aims of this plugin is to facilitate safe restarting so we do not miss blocks during restarts. This could be when updating Core or for any other reason that requires the Core, Relay or Forger processes to restart.

To safely restart, run ark monitor:restart. If you no longer wish to restart, and the restart has not yet been executed, you can cancel it with ark monitor:cancel.

The restart procedure restarts the Core, Relay and Forger processes, if they are running.

You can also hit the http://127.0.0.1:XXXX/restart or http://127.0.0.1:XXXX/cancel endpoints with a HTTP POST request, where XXXX is the port that the Round Monitor HTTP server is listening on. By default, the port is 1000 above the P2P port, although you can set it manually by configuring it.

Safe Reinstalling and Updating of ARK Core

When Round Monitor is enabled, the ark config:cli, ark reinstall and ark update commands are enhanced to automatically offer the option of attempting to safely restart all processes when complete:

Would you like to attempt to safely restart all processes? › (y/N)

Upon choosing yes, Round Monitor will trigger a safe restart. If you choose no, you will be presented with the standard options to perform a normal (potentially unsafe) restart operation.

Configuring

Execute the following command: ark monitor:configure. If you're using a bridgechain or fork, you may need to replace ark with the name of your blockchain instead.

You will be asked a series of configuration questions to configure Round Monitor to your requirements:

Whether to add ANSI control characters for clearer output to logs.
Whether to enable the built-in HTTP server for safe restarting via an API.
Which IP address the built-in HTTP server for safe restarting should use - please note that this should not be publicly accessible otherwise anybody on the internet could trigger a safe restart.
Which port the built-in HTTP server should use.
The minimum number of seconds required between now and our forging time and also between now and the end of the round in order to execute a safe restart.
Whether to print the full round order when each new round starts.
How many upcoming forgers should be displayed at the start of each forging slot.
Whether to display the time left until the end of the round.

Remember to restart your processes when prompted to activate the new configuration options.

Updating

To update the plugin, run ark plugin:update @alessiodf/round-monitor. Replace ark with the name of your blockchain if you are using a bridgechain or fork and remember to restart your processes afterwards.

Removing

If you wish to remove the plugin, first run ark monitor:disable and then ark plugin:remove @alessiodf/round-monitor. Replace ark with the name of your blockchain if you are using a bridgechain or fork.