diff --git a/docs/source/.static/img/period_commitment.png b/docs/source/.static/img/period_commitment.png new file mode 100644 index 000000000..a6e2a12c0 Binary files /dev/null and b/docs/source/.static/img/period_commitment.png differ diff --git a/docs/source/architecture/period_duration.rst b/docs/source/architecture/periods.rst similarity index 66% rename from docs/source/architecture/period_duration.rst rename to docs/source/architecture/periods.rst index a51509df1..e8d5341b8 100644 --- a/docs/source/architecture/period_duration.rst +++ b/docs/source/architecture/periods.rst @@ -1,12 +1,50 @@ -Period Duration -=============== +Periods +======= -In the NuCypher Network, a *Period* is the minimum unit for policy duration. This applies to sharing policy durations +In the NuCypher Network, a *Period* is the minimum unit of time for policy duration. This applies to sharing policy durations and also corresponds to the frequency that Workers must make an on-chain commitment to being online and available. Periods begin at UTC midnight. + +Worker Period Commitment +------------------------ +Once per period, Workers commit to being available to the Network for the next period via the ``commitToNextPeriod()`` +operation in the ``StakingEscrow`` contract. This operation is performed automatically by a running Worker node and +consists of two parts: + +#. Indicate availability for work in the next period. +#. Mint staking rewards for the previous period if availability was previously indicated. + +In other words, committing to a period is prospective, and minting rewards is retrospective. To illustrate the process, +here is a simplified example: + +.. image:: ../.static/img/period_commitment.png + :target: ../.static/img/period_commitment.png + +* *Period 5*: A stake is created, and a Worker is initiated and started. +* *Period 5*: Worker calls ``commitToNextPeriod()`` to indicate availability for Period 6 (the next period) - the + first period of availability. The Worker was unavailable during Period 4 (previous period), so there are no staking + rewards to mint. +* *Period 6*: Worker calls ``commitToNextPeriod()`` to indicate availability for Period 7 (the next period). The Worker + did not indicate availability for Period 5 (previous period) since it only started in Period 5, so there are no + staking rewards to mint. +* *Period 6*: Worker successfully provides availability for work. +* *[Repeat]* + + * *Period 7*: Worker calls ``commitToNextPeriod()`` to indicate availability for Period 8. Since the Worker + indicated its availability for the previous period (Period 6), staking rewards are minted for Period 6 + * *Period 7*: Worker successfully provides availability for work + +.. note:: + + The last two bullet points are repeated for subsequent periods moving forward. + + +Period Duration +--------------- + Genesis -------- ++++++++ At the Network launch on October 15th, 2020, the duration of a period was 24 hours. As a result, before UTC midnight, Workers needed to make a per period (daily) on-chain commitment transactions indicating availability for the subsequent @@ -35,7 +73,7 @@ competitive break-even policy fee price points for network usage which is likely 7-Day Period ------------- +++++++++++++ A `proposal to increase the protocol period duration `_, outlining the pros and cons, was put forth to the :doc:`NuCypher DAO `, and a 7-day period duration diff --git a/docs/source/index.rst b/docs/source/index.rst index 3b2359afb..de715a9fc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -134,7 +134,7 @@ Whitepapers architecture/rewards_and_service_fees architecture/sub_stakes architecture/slashing - architecture/period_duration + architecture/periods architecture/staking_contracts .. TODO perhaps categorize architecture section diff --git a/docs/source/support/faq.rst b/docs/source/support/faq.rst index 2ce645c5a..b95bab08f 100644 --- a/docs/source/support/faq.rst +++ b/docs/source/support/faq.rst @@ -36,7 +36,7 @@ to provide service. 1 period is 7 days, and periods always start on Thursdays at midnight UTC. At Network launch, 1 period was 24 hours, but this was updated by a NuCypher DAO proposal to be -7 days (see :doc:`/architecture/period_duration`). +7 days (see :doc:`/architecture/periods`). Using the Network