By now every Cardano stake pool operator probably knows about pooltool.io where you can track various statistics about stake pools and the overall status of the Cardano blockchain. The site is not just for stake pool operators though. Based on the data published on Pooltool (PT) delegators can make a better decision to which pool they want to delegate their hard earned ADAs.

The purpose of this post is to present one piece of that data – the number of assigned slots and minted blocks. This information reveals how effective was a pool in a given epoch and how many slots it got assigned. There are still many stake pools out there which don’t have this information published. In fact, this information might not help your pool very much to stand out but it will certainly help to avoid that it gets unnoticed. Since many delegators are very much interested in this information it would be a good idea to consider sending the information to Pooltool. Let’s see how it works.

Leaders logs

Leaders logs show for how many slots has a pool been elected. The more slots assigned to the stake pool (SP) the better, as SP has a chance to mint a block for each slot assigned. The following example shows 2 slots for which Tilia I/O SP was elected to mint the blocks on the Incentivized Testnet (ITN).

[
  {
    "created_at_time": "2020-04-07T19:13:54.488491024+00:00",
    "enclave_leader_id": 1,
    "finished_at_time": null,
    "scheduled_at_date": "116.33908",
    "scheduled_at_time": "2020-04-08T14:03:53+00:00",
    "status": "Pending",
    "wake_at_time": null
  },
  {
    "created_at_time": "2020-04-07T19:13:54.488484178+00:00",
    "enclave_leader_id": 1,
    "finished_at_time": null,
    "scheduled_at_date": "116.26120",
    "scheduled_at_time": "2020-04-08T09:44:17+00:00",
    "status": "Pending",
    "wake_at_time": null
  }
]

As you can see, “crated_at_time” field shows at what time the slots schedule was created by the SP. “scheduled_at_date” is composed by two numbers where the first number is the epoch number and the second number is the assigned slot number. “scheduled_at_time” shows the time at which the block is expected to be minted. With leaders logs you can prove to PT how many slots your pool got assigned.

PoolTool

PT does not know at what time a particular SP creates a block unless you tell it. If PT had bad intentions or got hacked it could organize for example a DOS attack on the SP. That would slow down the SP and it could prevent it from creating a block right at the time when the pool was due to mint the block. In order for PT to avoid such problems and still provide validated information about pool’s block minting performance, they provided a shell script that encrypts the SP leaders logs data.

A few minutes in the new epoch the SP retrieves the leaders logs (see previous section) and encrypts it. The encrypted data is then assembled into a json data package which holds some additional information:

{
"currentepoch":"116", 
"poolid":"ef85ef04dcc80c245499dd4c313f175b6369e14fac94c3fca9ca44a772ae9635",
"genesispref":"8e4d2a343f3dcf93",
"userid":"f41d876a-6d97-434d-a027-a8447c230fb7",
"assigned_slots":"2",
"previous_epoch_key":"",
"encrypted_slots":"-----BEGIN PGP MESSAGE-----\n\njA0ECQMCnZP3EMhPMnz90sAvASl/dRljGhgVoMgj0wcVu7j3gJiuhebSwwFo9HOv\nKmAhzBTScqDeferb7a7+e4lVWZpTqUQ9DYK+3Ue2mXn5xpV7kqO7UQGcqN9M6H3B\n4aVr+HJKntG56ZbCCa+OzQrG0NOs0WT8EnI/YmsyqQXiII6dMN6xgWVfVEFmWmN7\nu8i26MFi3Gb7HvQWP23M2H+wKwBBx33ASAMGPP6asX8fYFocFywNYm7mJd6WhPB9\ncaxJAsbIuUmOWVE8RwlzzM2/mP3am2hP4YP6/U04eMxKWbm3MfXStDuBD/05p6nM\nyEJqGwBuhkfu/Z9YonapJAE=\n=sBku\n-----END PGP MESSAGE-----"
}

Don’t get too exicted, pooltool’s userid in the example above is fake 🙂

The data needs to be sent to PT in the first 10 minutes of the epoch. By that time each pool should have already received the leaders logs schedule so that should not be a problem.

You probably noticed that “previous_epoch_key” field is empty. This happens when sending the leaders logs for the first time. The passphrase generated to encrypt the data is stored by the script into passphrase_<epoch> file. When the script is run in the next epoch, the key is sent to PT so it can decrypt the leaders logs from previous epoch. PT can verify that the stake pool really created the blocks specified in the encrypted file. The whole process is repeated for each new epoch.

If the SP is successful creating all the assigned slots it gets a star. Yay! 🙂

If you don’t want to use the encryption you can still use the script with:

• hashing – instead of encrypting your logs, a hash of those will be created. In the current epoch the hash of the logs is sent and in the next epoch, the leaders logs from previous epoch is sent
• plain number of slots assigned – with this method, PT cannot really validate your data but can still display it on the page.

Python implementation

At Tilia I/O we have created a python script based on the shell script provided by PoolTool for those who prefer Python over shell.

For the Python script you don’t have to edit the script and enter any specific information there. All the needed parameters can be specified via command line:

python send_slots.py -p 3101 -g 1 -s 0 -u f41d876a-6d97-434d-a027-a8447c230fb7 -i $(cat stake_pool.id)

Help is also available:

python send_slots.py --help
send_slots.py [ -g [0|1] | -s [0|1] ] [OPTION]....

Mandatory parameters (without any defaults):
-i, --pool-id=POOL_ID              Stake pool id
-u, --user-id=USER_ID              PoolTool user id

Optional parameters with defaults fallback values:
-g, --verify-gpg=BOOL              Determines what you upload to pooltool, default: 0, BOOL:[0,1]
-s, --verify-hash=BOOL             Determines what you upload to pooltool, default: 0, BOOL:[0,1]
-r, --jormungandr_restapi=URL      Jormungandr rest api url, default: http://127.0.0.1:5001/api/v0
-p, --restapi-port=PORT            Port number for jormungandr rest api, default: 5001
-i, --pool-id=POOL_ID              Stake pool id
-u, --user-id=USER_ID              PoolTool user id
-t, --genesis=THIS_GENESIS         Genesis hash, default: 8e4d2a343f3dcf93
-k, --key-path=KEY_PATH            Location where the temporary files generated by this tool will be stored, default: /tmp/keystorage
If neither -g nor -s are specified the number of slots will be sent to pooltool but pooltool won't be able to verify the number of blocks processed by the pool.

The script was implemented in Python3.6 but will probably work also with other versions 3.x. Haven’t tested it though.

To get the script head over to PoolTool’s github repository. You will need the script send_slots.py and requirements file. To run it, you first need to install the dependencies:

pip install -r requirements

The other file is send_slots_alternative.py is not ours but it is there as an alternative should you prefer that.

Conclusion

PoolTool is a great tool for both stake pool operators and delegators. While official Cardano wallet Daedalus for ITN has a pool performance indicator Pooltool can provide more detailed information. Daedalus for mainnet does not have this feature yet but we can expect it when Shelley is released.

If you find this post useful and want to support us you are welcome to delegate to Tiliaio I/O (pool ticker TILX).

Drop us a comment and til the next time, happy staking 😉