Block Keeper Contracts Business-Level Specification
Prepared by Pruvendo
Purpose
The purpose of the present document is to create business-level specification (highest-level of specification) for the Block Keeper set of smart contracts. This document is intended to:
Be thoroughly reviewed by the Customer
Act as a base for the high-level specification
Introduction
The key intention of the Block Keeper set of smart contracts is to let any participant become a Block Keeper either for a single participation (in Acki Nacki protocol as Block Keeper) period (called Epoch) or repeatedly.
Single participation period
In this case the following stages are introduced:
Pre Epoch. This stage is relatively short (a few minutes) and intended to let the Block Keeper to finish synchronizing its node if necessary
Epoch - the main stage where the participant acts as a Block Keeper. Its duration is usually is most than one day
Cooling - the terminating stage where the Block Keeper can still be slashed (up to 30% of Epoch’s duration)
The workflow described below must be followed:
Participant must be registered as a Block Keeper
Stake (exceeding minimally allowed value, which is a dynamic parameter) must be deposited
Pre Epoch must be started and, then, finished
Then, Epoch:
Must be started
Throughout the Epoch, the participant is a Block Keeper
Later Epoch must be finished
Then, Cooling:
Must be started
At any time the Block Keeper can be slashed
Later Cooling must be finished and:
Then, stake can be withdrawn or reinvested
Graphically, the described workflow can be presented by the following chart:
Repeated participation
The main difference with the Single Participation Period is that upon Epoch completion, a new Epoch starts immediately.
The workflow described below must be followed:
Participant must be registered as a Block Keeper
Stake (exceeding minimally allowed value) must be deposited
Pre Epoch must be started and, then, finished
Then, Epoch:
Must be started
Another (additional) stake must be deposited making the workflow repeated thus turning Epoche into continue state
Later Epoch must be finished
Then:
New Epoch (in non-continued state) starts immediately with additional stake
Cooling:
Must be started with the rest of stake
At any time the Block Keeper can be slashed
Later Cooling must be finished and:
Then, stake can be withdrawn or reinvested any time in future
The described workflow is illustrated by the following diagram:
Stake workflow
Throughout the loop, stakes are transferred from one entity to another. For single participation their workflow can be illustrated by the following diagram (the second row indicated what entity the stake belongs to at each stage):
For repeated participation the diagram is more complicated:
It’s important to mention that in case the participant (owner) reinvests each stake for the repeated participation immediately after cooling down by continuing the current Epoch, he gets some kind of a carousel of continuous participation.
Such a carousel is illustrated in the diagram below. For simplicity, all the “gray” periods between ending of the particular stages and external actions are omitted. Green dots stay for the “first” stake, while the red one - for the “second” stake.
Reward
Reward is provided by external request sent any time (probably, multiple times) throughout the Epoch. It is implemented using a special TVM instruction and depends on:
Epoch duration
Stake
Total Stake
Signature
Reputation time (cumulative time of being a Block Keeper)
Details
Common
Before any action any participating system contract must be supplied with gas enough to perform this action, if necessary
Participant registration
External request comes from anybody
New unique BNW (Block Keeper Node Wallet) is created
Newly created BNW is initialized
Stake placement
Owner sends a request to BNW
BNW checks if:
Owner is correct
Stake value is available (in ECC that serves as a secondary currency)
In case of success Root is informed
Root checks if:
Stake exceeds minimally allowed value, otherwise it must be sent back
In case of success BNW is informed
New BKPE (Block Keeper Pre Epoch) created
Stake is moved to Pre Epoch
Pre Epoch
Upon creation:
BKPE is initialized
BNW is moved to “Pre Epoch” state
Then, at any moment external touch message can be received
If time for the next stage still did not come, nothing happens
Otherwise:
New Epoch created
Stake is moved to Epoch
BKPE is self-destructed and all its assets are transferred to Epoch
Epoch
Upon creation:
Epoch is initialized
Root is informed to enlist the Block Keeper
BNW is moved to “Epoch” state
Then, at any moment external touch message can be received
Also, at any moment external slash message can be received, and:
The whole stake will be confiscated
No reward is granted
The participant is blacklisted
If time for the next stage still did not come, nothing happens
Otherwise:
Root is informed
Root checks if it’s possible to end an Epoch and does nothing if negative
Otherwise:
Block Keeper is delisted
Epoch is informed and:
Cooler is created
Stake (with reward) is moved to Cooler
Epoch is self-destructed in favor of Cooler
Cooler
Upon creation:
Cooler is initialized
BNW is moved to “Cooler” state
Then, at any moment external touch message can be received
Also, at any moment external slash message can be received, and:
The whole stake will be confiscated
No reward is granted
The participant is blacklisted
If time for the next stage still did not come, nothing happens
Otherwise:
BNW is moved to initial state
BKPE is self-destructed and all stake transferred to the BNW
Epoch (Repeated)
Upon creation:
Epoch is initialized
Root is informed to enlist the Block Keeper
BNW is moved to “Epoch” state
Then, at any moment additional stake request can be received with continue flag, making the epoch repeated
Then, at any moment external touch message can be received
Also, at any moment external slash message can be received, and:
The whole stake will be confiscated
No reward is granted
The participant is blacklisted
If time for the next stage still did not come, nothing happens
Otherwise:
Root is informed
Root checks if it’s possible to end an Epoch and does nothing if negative
Otherwise:
Epoch is informed and:
New repeated Epoch is created with additional stake
Cooler is created is the rest of stake with reward
Epoch is self-destructed in favor of Cooler
Top-level scenarios
To formally specify the behavior briefly described above, the following top-level scenarios were identified for further creation of high-level and, then, low-level formal specification:
Registration
ECC Withdrawal
Participation
Last updated
