Nucypher
/
nucypher
mirror of https://github.com/nucypher/nucypher.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Added one more slashing scenario and some ascii diagrams

pull/806/head
szotov 2019-03-13 15:13:18 +03:00
parent 30cad65c99
commit 19a11d0ab1
3 changed files with 105 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.circleci/config.yml
View File

@ -523,7 +523,7 @@ jobs:
at: ~/.local/share/virtualenvs/
- run:
name: Install Documentation Build Dependencies
command: pip3 install --user sphinx recommonmark sphinx-rtd-theme
command: pip3 install --user sphinx recommonmark sphinx-rtd-theme aafigure
- run:
name: Build Sphinx Documentation
command: |

130
docs/source/architecture/slashing.rst
View File

@ -23,8 +23,8 @@ The goal of slashing is to reduce the number of tokens that belongs to a staking
In this case, the main task is not to violate the logic of locking tokens.
The entire stake consists of:
* tokens which the staker can withdraw at any moment
* tokens locked for a specific period
* tokens which the staker can withdraw at any moment
* tokens locked for a specific period
A staker may extend the unlock period for any number of portions of their total stake. This divides the stake into smaller parts, each with a unique unlock date in the future. Stakers may also acquire and lock new tokens. The total stake is represented as the sum of all the different sub-stakes active in a given cycle (new cycle every 24h), which includes locked sub-stakes, and any sub-stakes that have passed their unlock date, and can be freely withdrawn. Each sub-stake has a beginning and duration (lock time). When a staker confirms activity each day, the remaining lock time for relevant sub-stakes is reduced.
@ -32,43 +32,119 @@ Sub stakes get slashed in the order of their remaining lock time, beginning with
**Example:**
A staker has 1000 tokens:
* 1st sub stake = 500 tokens locked for 10 periods
* 2nd sub stake = 200 tokens for 2 periods
* 3rd sub stake = 100 tokens locked starting from the next period
* 200 tokens in an unlocked state (still staked, but can be freely withdrawn).
A staker has 1000 tokens:
* 1st sub stake = 500 tokens locked for 10 periods
* 2nd sub stake = 200 tokens for 2 periods
* 3rd sub stake = 100 tokens locked starting from the next period and locked for 5 periods. The 3rd sub stake is locked for the next period but has not yet been used as a deposit for "work" - not until the next period begins.
* 200 tokens in an unlocked state (still staked, but can be freely withdrawn).
.. aafig::
:proportional:
:textual:
stake
^
|
800| +----+
| | 3rd|
700+-----+----+
600| +-------------+
| 2nd | 3rd |
500+----------+-------------+----------+
| |
| 1st |
| | period
+-----------------------------------+--->
Penalty Scenarios:
* *Scenario 1*: Staker incurs penalty calculated to be worth **100 tokens**:
Only the unlocked tokens will be reduced; from 200 to 100. The values of locked sub-stakes will therefore remain unchanged in this punishment scenario.
Only the unlocked tokens will be reduced; from 200 to 100. The values of locked sub-stakes will therefore remain unchanged in this punishment scenario.
Result:
Result:
* 1st sub stake = 500 tokens locked for 10 periods
* 2nd sub stake = 200 tokens for 2 periods
* 3rd sub stake = 100 tokens locked starting from the next period
* 100 tokens in an unlocked state
* 1st sub stake = 500 tokens locked for 10 periods
* 2nd sub stake = 200 tokens for 2 periods
* 3rd sub stake = 100 tokens locked starting from the next period
* 100 tokens in an unlocked state
* *Scenario 2*: Staker incurs penalty calculated to be worth **300 tokens**:
The unlocked tokens can only cover 200 tokens. In the current period, 700 tokens are locked and 800 tokens are locked for the next period. Therefore, we should reduce amount of locked tokens for the next period and leave unchanged locked amount in the current period. The 3rd sub stake suits for this purpose but it's not the shortest one. So we take the 2nd sub stake (the shortest), reduce it to 100 tokens and add new sub stake with 100 tokens which active only in the current period.
Result:
* 1st sub stake = 500 tokens locked for 10 periods
* 2nd sub stake = 100 tokens for 2 periods
* 3rd sub stake = 100 tokens locked starting from the next period for 5 periods
* 4rd sub stake = 100 tokens for 1 period
* Remaining 0 tokens
.. aafig::
:proportional:
:textual:
stake
^
|
700+-----+----+
| 4th | 3rd|
600+-----+----+-------------+
| 2nd | 3rd |
500+----------+-------------+----------+
| |
| 1st |
| | period
+-----------------------------------+--->
* *Scenario 2*: Staker incurs penalty calculated to be worth **400 tokens**:
* *Scenario 3*: Staker incurs penalty calculated to be worth **400 tokens**:
The remaining tokens can only cover 200 tokens. In the current period, 700 tokens are locked and 800 tokens are locked for the next period. The 3rd sub stake is locked for the next period but has not yet been used as a deposit for "work" - not until the next period begins. Therefore, it will be the next sub stake to be slashed. However, it can only cover 100 tokens for the penalty which is still not enough. The next shortest locked sub stake (2nd) is then reduced by 100 tokens to cover the remainder of the penalty, and the other sub stakes remain unchanged.
The difference from the previous scenario is that should also decrease locked tokens in the current period. At the first step the 2nd sub stake is reduced to 100 tokens. Next step - adjustment for the next period. The shortest sub stake still the same - the 2nd. And we need to deacrese it from 100 to 0 only for the next period. Will be the same if we change duration of the 2nd sub stake from 2 periods to 1 and the other sub stakes remain unchanged.
Result:
Result:
* 1st sub stake = 500 tokens locked for 10 periods
* 2nd sub stake = 100 tokens for 2 periods
* 3rd sub stake = 0 tokens locked starting from the next period
* Remaining 0 tokens
* 1st sub stake = 500 tokens locked for 10 periods
* 2nd sub stake = 100 tokens for 1 period
* 3rd sub stake = 100 tokens locked starting from the next period
* Remaining 0 tokens
.. aafig::
:proportional:
:textual:
stake
^
|
600+----------+-------------+
| 2nd | 3rd |
500+----------+-------------+----------+
| |
| 1st |
| | period
+-----------------------------------+--->
* *Scenario 3*: Staker incurs penalty calculated to be worth **600 tokens**:
* *Scenario 4*: Staker incurs penalty calculated to be worth **600 tokens**:
Reducing the unlocked remaining tokens, 3rd sub stakes, and the shortest sub stake (2nd) is not enough, so they are all removed. The next shortest sub stake is the 1st which is reduced from 500 to 400.
Reducing the unlocked remaining tokens, 3rd sub stakes, and the shortest sub stake (2nd) is not enough, so they are all removed. The next shortest sub stake is the 1st which is reduced from 500 to 400.
Result:
Result:
* 1st sub stake = 400 tokens locked for 10 periods
* 2nd sub stake = 0 tokens for 2 periods
* 3rd sub stake = 0 tokens locked starting from the next period
* Remaining 0 tokens
* 1st sub stake = 400 tokens locked for 10 periods
* 2nd sub stake = 0 tokens for 2 periods
* 3rd sub stake = 0 tokens locked starting from the next period
* Remaining 0 tokens
.. aafig::
:proportional:
:textual:
stake
^
|
400+-----------------------------------+
| |
| 1st |
| | period
+-----------------------------------+--->

1
docs/source/conf.py
View File

@ -51,6 +51,7 @@ extensions = [
'sphinx.ext.napoleon',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'aafigure.sphinxext',
]
# Add any paths that contain templates here, relative to this directory.