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