Configuring Certification Authorities (CAs) - ntallar/plato GitHub Wiki

Slot definition

Time in the Cardano Enterprise client is divided into slots of equal length, being the beginning of the first slot the timestamp of the genesis block. The duration of each slot is defined in mantis.ouroboros.slot-duration.

Configuring initial CAs

The client can be configured with the addresses of the wallets that should be allowed to mine, for example for allowing addresses edde8656c35fcb7126c61fc6e2673734425a72bf and 240653414e3d40764a0fc75af372bb6458f8600a to mine from the start, the client should be configured as follows:

mantis.ouroboros.slot-minerStakeHolders-mapping =
  {
     1:  ["edde8656c35fcb7126c61fc6e2673734425a72bf","240653414e3d40764a0fc75af372bb6458f8600a"]
  }

This means that from slot 1 onwards, the list of CAs allowed to mine will only be the ones with the desired addresses.

Changing the allowed CAs

If it's desired to add or remove addresses from the allowed CAs, it can be done by selecting a future slot number as the starting point from which only the new set of addresses will be allowed to mine. For example, if from slot 20 onwards we want to remove the permission to mine to 240653414e3d40764a0fc75af372bb6458f8600a, the configuration has to be changed as follows:

mantis.ouroboros.slot-minerStakeHolders-mapping =
  {
     1:  ["edde8656c35fcb7126c61fc6e2673734425a72bf","240653414e3d40764a0fc75af372bb6458f8600a"]
     20: ["edde8656c35fcb7126c61fc6e2673734425a72bf"]
  }

Since these configuration changes are regarded as hard forks, this requires not only restarting the client but making this change on all the nodes on the network and restarting them as well.

Note: It is important not to remove the allowed CAs for past slots, only new entries can be added to slot-minerStakeHolders-mapping. Otherwise, validator nodes will not be able to successfully validate past blocks.

Calculating a future slot number from an expected date

Starting from an expected date, the slot number associated with it can be calculated by:

  1. Obtaining the Unix timestamp associated with the expected date (which can be done with https://www.epochconverter.com/ for example); and
  2. Calculating the expected slot number by doing:
expected_slot = (expected_timestamp - slot1StartingTime) / slotDuration + 1

Note:

  • slot1StartingTime = Value of the unixTimestamp field in the genesis block (obtained from the custom file referred to in mantis.blockchain.custom-genesis-file or in the default-genesis.json file if that configuration parameter is set to null).
  • slotDuration = Value of the parameter mantis.ouroboros.slotDuration obtained from the configuration file, which is set to 15 seconds by default.
  • This calculation assumes that the slot duration has not changed since the start of the first slot.

An example

Say that University XYZ wants to join the network on 2018/01/10 (Unix timestamp 1515542400) using a miner account with address 2eF08cE2429d83cd07801d482097a85ab0c89B6D. Also, assume that the system starting time (i.e. the value of theunixTimestamp field in the genesis block) is 2017/12/01 (Unix timestamp 1512086400) and that the slot duration is 10 seconds. Thus, the slot number at which University XYZ should join the network and start mining is calculated as follows:

(1515542400 - 1512086400) / 10 + 1

which is equal to 345601. Therefore, all nodes in the network (including University XYZ's node) should add the following entry in their corresponding mantis.ouroboros.slot-minerStakeHolders-mapping parameter:

345601: ["2eF08cE2429d83cd07801d482097a85ab0c89B6D", ... here follows the list of the current CA addresses]

As explained previously, all nodes in the network should be restarted after performing this configuration change.

Unlocking CA accounts

Currently, when a new account is created, it's locked by default. Whenever an existing account is unlocked, it's unlocked for a specific amount of time (or even forever), being 300 seconds the default value. However, for mining purposes only we would expect the account to be permanently unlocked. Using the current personal_unlockAccount JSON-RPC method with an unlock duration of zero would unlock the account for other purposes besides mining, thus compromising security. Therefore, a new JSON-RPC method is added to unlock an account only for mining purposes, whose specification is shown below:

personal_unlockMinerAccount

Unlocks the given account only for mining purposes.

Parameters:

  1. Address: Address of the account to be unlocked.
  2. Passphrase: Passphrase of the account to be unlocked.
params: [
   '2eF08cE2429d83cd07801d482097a85ab0c89B6D',
   '1234'
]

Returns:

  1. Boolean, an indication that the account was successfully unlocked.

Storage Requirements

For the most part, the storage is used by the database which contains the blockchain. Therefore, the amount of disk space required directly depends on the number of blocks generated during the running of the network. As a rough estimate, a blockchain comprised by 5 million blocks requires approximately 150 GB of disk storage per node. So, for example, if one block is generated per slot and the slot duration is 15 seconds, then 150 GB of disk storage would suffice for running a node during ~2.5 years.

Troubleshooting Guide