@alessiodf/productivity-statistics v1.3.0
Productivity Statistics
Introduction
This repository contains the Productivity Statistics plugin. It augments the delegates API endpoints within Core 3.0 for ARK and ARK-powered blockchains by including statistics to display the number of missed rounds and slots for each delegate, along with a productivity score (forged / (forged + missed)).
The time periods are fully configurable and, by default, there are daily (24 hours), weekly (7 days), monthly (30 days) and quarterly (90 days) statistics.
The statistics are generated and stored in a separate SQLite3 database. This is significantly more performant than running queries on the live Core PostgreSQL database and it also means the Core database remains untouched. However, there must be sufficient disk space to hold the database, which will grow as the blockchain gets larger.
Installation
This is TBC with the new ark plugin:install command.
Once the plugin is installed, we must configure it by modifying app.json. This file is found in ~/.config/ark-core/{mainnet|devnet|testnet|unitnet}/app.json depending on network.
Add a new entry to the end of the plugins section within either the relay or core blocks, depending on whether you wish to use the separate relay/forger processes or the unified Core respectively. Of course, you can also add the plugin to both blocks if you wish to have the freedom to swap between the separate processes and the unified Core. Your entry or entries should look like the following:
"relay": {
"plugins": [
...
{
"package": "@alessiodf/productivity-statistics",
"options": {
"enabled": true
}
}
]
},Or:
"core": {
"plugins": [
...
{
"package": "@alessiodf/productivity-statistics",
"options": {
"enabled": true
}
}
]
},If you wish to set up different time periods, see the Configuration Options section below.
Running
After installation, make sure the app.json file is correctly configured and restart Core. If you are using the CLI, this will probably be ark core:restart (or ark relay:restart if you wish to use the separate processes rather than the unified Core), although ark may be different in the case of bridgechains. If using Core Control, run ccontrol restart relay.
The plugin will start whenever the Core or Relay process is running, as long as the enabled configuration option is true. When the process starts, historical productivity statistics will be calculated, which may take a few minutes to complete for the first run as it must calculate statistics from the genesis block until the current height, however future runs will append to the existing database so should be much quicker. Periodic status updates will be printed to the console during this time.
It is normal for the CPU usage to reach 100% during this calculation process, but this will not affect the node's ability to receive and process blocks.
Once calculated, statistics can be viewed using the /api/delegates endpoint as well as /api/delegates/{username} for statistics about a single delegate. Furthermore, /api/delegates/{username}/missed/{slots|rounds} will show the individual slots or rounds that were missed, including heights and timestamps.
Statistics are also continually updated in real time after every new block is applied.
Examples of some API calls are as follows:
/api/delegates?limit=2:
This shows the productivity statistics for the top 2 delegates by rank.
Similarly for an individual delegate:
/api/delegates/therock:
{"username":"therock","address":"AJC9TuRXGxmqiCs3wmtt9CowfC8s2vMhEF","publicKey":"023a4015f921d8d0248f40362db44e856769a7291224cbd8f2fc14d61be2138174","votes":"705206420619","rank":71,"blocks":{"produced":167891,"last":{"id":"f28a5d9b90a5397c867ba1e01e73a2d2a7e86cc5ac0637cb4fdf456686a7369b","height":9393698,"timestamp":{"epoch":76279200,"unix":1566380400,"human":"2019-08-21T09:40:00.000Z"}}},"production":{"approval":0.01},"forged":{"fees":"315609079238","rewards":"33578200000000","total":"33893809079238"},"statistics":{"day":{"forged":0,"slots":{"missed":0,"productivity":0},"rounds":{"missed":0,"productivity":0}},"week":{"forged":0,"slots":{"missed":0,"productivity":0},"rounds":{"missed":0,"productivity":0}},"month":{"forged":2078,"slots":{"missed":0,"productivity":1},"rounds":{"missed":0,"productivity":1}},"quarter":{"forged":14712,"slots":{"missed":79,"productivity":0.9946302338227297},"rounds":{"missed":70,"productivity":0.995241979336596}},"year":{"forged":70495,"slots":{"missed":2543,"productivity":0.9639265196113199},"rounds":{"missed":1964,"productivity":0.97213986807575}}}}
Here we can see the productivity statistics for therock.
If we want to go deeper, we can see the individual rounds or slots missed by a delegate:
/api/delegates/doc/missed/rounds:
We can see the height and timestamps of all the missed rounds. By changing rounds to slots in the above API call the missed slots would be returned instead.
Slots vs rounds
Most people use the term "missed block" but that is terminology is ambiguous:
Core versions 2.5 and below define a "missed block" as one where a delegate does not forge within the current round. That means, for example, if a delegate is due to forge first in a round but fails to do so, it will get another chance to forge later at the end of the round, and if it forges successfully the second time, it is not considered to have missed a block. Similarly, that delegate will remain green on the explorer and will only be considered to have missed a block if it did not forge at all in the round. This is the definition of a missed round within this plugin.
Core versions 2.6 onwards instead refer to a "missed block" as an incident where a delegate fails to forge within its designated slot, even if it forges successfully later in the same round. This is the definition of a missed slot within this plugin.
Due to the conflicting definitions of "missed block", this plugin avoids that term in its API responses and explicitly refers to missed rounds and slots instead.
Configuration Options
enabled- Should betrueto enable the plugin orfalseto disable it. Default:false.statistics- An object containing the granular timescales for the productivity statistics. Examples of some statistics are below:
"week": {
"time": 604800,
"type": "rolling"
}This will create a new productivity metric called week which is calculated by looking back over the last 604800 seconds, which equates to 7 days. The rolling type means this refers to the last 604800 seconds on a rolling basis. Contrast with the exact type as shown below:
"thisyear": {
"time": 1546300800,
"type": "exact"
}This would calculate productivity statistics for a metric called thisyear which would show statistics since the start of 2019, since the exact type means that it will calculate all blocks since the UNIX timestamp stipulated in the time value, and 1546300800 is the timestamp for 2019-01-01 00:00:00 UTC.
Note that it is not recommended to create a metric that shows productivity statistics for all time on a publicly accessible API as it may incentivise attackers to target certain delegates with the intention of permanently ruining their productivity statistics. Network outages would also permanently damage such statistics. However, the option remains available for those who may need it.