Doc: add over-delegation, expected rights, deactivation

docs/introduction/howtorun.rst

@@ -46,8 +46,139 @@ do not participate in baking.
 Running a delegate
 ------------------
 
-We now explain how to run a delegate, which means running the 3
+A delegate is responsible for baking blocks, endorsing blocks and
-daemons for baking, endorsing and accusing.
+accusing other delegates in case their try to double bake or double
+endorse.
+
+In the network, rights for baking and endorsing are randomly assigned
+to delegates proportionally to the number of rolls they have been
+delegated.
+A roll is just a block of 10kꜩ and all computations with rolls are
+rounded to the nearest lower integer e.g. if you have 16kꜩ it amounts
+to 1 roll.
+
+When you obtain coins from :ref:`the faucet<faucet>`, if you
+are lucky to obtain more than one roll, you can register a delegate
+using this identity.
+Otherwise, you need to ask the faucet for more accounts, originate an
+account for each one and delegate them to the first.
+
+Deposits and over-delegation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When baking or endorsing a block, a *security deposit* (or *bond*) is
+frozen for ``preserved_cycles`` cycles from the account of the
+delegate.
+Hence a delegate must have enough funds to be able to pay security
+deposits for all the blocks it can potentially bake/endorse during
+``preserved_cycles``.
+The current deposits are *512ꜩ* for baked block and *64ꜩ* for
+endorsement.
+Note that being delegated coins doesn't mean that a delegate can spend
+them, they only add up to its rolls count while all the deposits must
+come from the delegate's account.
+
+If a delegate runs out of funds to deposit it won't be able to bake or
+endorse, other than being a missed opportunity for them this has also
+negative consequences on the network.
+Missing baking slots slows the network, as it is necessary to wait one
+minute for the baker at priority 2 to bake, while missing endorsements
+reduce the fitness of the chain, making it more susceptible to forks.
+Running out of funds can happen if a delegate is *over-delegated*,
+that is if the amount of rolls it was delegate is disproportionate
+with respect to its available funds.
+It is the responsibility of every delegator to make sure a delegate is
+not already over-delegated (a delegate cannot refuse a delegation) and
+each delegate should plan carefully its deposits.
+
+.. _expected_rights:
+
+Expected rights, deposits and rewards
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's assume we have 1 roll, we want to estimate our chances to bake
+or endorse in order to prepare the funds for our deposits.
+Our chances depend on how many rolls are currently active in the
+network, once we know that we can estimate how many blocks and
+endorsements we could be assigned in a cycle.
+The number of active rolls can be computed with two RPCs, first we
+list all the active delegates with ``delegates?active``, then we sum
+all their ``stacking_balance`` and we simply divide by the size of a
+roll, 10kꜩ.
+At the time of writing, on Betanet the number of active rolls is ~30k
+so for each block we know that the chance that we get selected for
+baking is ``1/30k`` while for endorsing is 32 times that.
+Given that every draw is with replacement, the distribution that
+describes our chances of being selected is the binomial with
+probability of success ``p=1/30k``.
+The distribution has another parameter ``n`` for the number of times
+we draw, in our case in a cycle the draws for baking are ``n_b =
+4096`` while for endorsing are ``n_e = 4096 * 32``.
+Moreover we could extend ``n`` to cover ``preserved_cycles = 5``.
+Once we have ``p`` and ``n``, the expected number of times that we
+might get selected is ``p * n`` (the mean of the distribution).
+Over many cycles our chances will fall around the mean, in some cycles
+we will unlucky get less rights, but in some cycles we might get lucky
+and be assigned more rights!
+Clearly we would like to plan ahead and have enough deposits to cover
+also the "lucky" cycles so we need to compute a sort of "maximum"
+number of rights that is safe for `most cases`.
+We can compute this maximum using the inverse of Cumulative
+Distribution Function of the Binomial where `most cases` is a value of
+confidence that we can put to 95%.
+There a simple `Python
+script<https://gitlab.com/paracetamolo/utils/blob/master/estimated-rights.py>`_
+that does the computation for us and returns the deposits and rewards,
+expected and maximum, for a cycle and for `preserved_cycles`.
+
+::
+
+   prob success 3.333333e-05
+   confidence   0.95
+   ----------one-cycle--------------------
+   blocks
+    mean 0.14
+    max  1.00
+   endorsements
+    mean 4.37
+    max  8.00
+   deposits
+    mean 69.91 + 279.62
+    max  512.00 + 512.00
+   rewards
+    mean 2.18 + 8.74
+    max  16.00 + 16.00
+   ----------preserved-cycles-------------
+   blocks
+    mean 0.68
+    max  2.00
+   endorsements
+    mean 21.85
+    max  30.00
+   deposits
+    mean 349.53 + 1398.10
+    max  1024.00 + 1920.00
+   rewards
+    mean 10.92 + 43.69
+    max  32.00 + 60.00
+
+As a rule of thumb if we want to have a very high confidence that we
+won't miss any opportunity we should have around ~3kꜩ for deposits,
+on the other hand the expected returns will probably be around ~10ꜩ per cycle.
+
+After ``preserved_cycles``, not only the delegate takes back control of
+its frozen deposits but it also receives the rewards for its hard work
+which amount to 16ꜩ to bake a block and ``ꜩ2 / <block_priority>`` for
+endorsing a block.
+Additionally a baker also receives the fees of the operations it
+included in its blocks.
+While fees are unfrozen after ``preserved_cycles`` like deposits and
+rewards, they participate in the staking balance of the delegate
+immediately after the block has been baked.
+
+
+Register and check your rights
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to run a delegate you first need to register as one using
 your implicit account:
@@ -56,62 +187,40 @@ your implicit account:
 
    tezos-client register key bob as delegate
 
-Once registered, a delegate can participate in the network
+Once registered, you need to wait ``preserved_cycles + 2 = 7`` cycles
-proportionally to how many rolls it is delegated, that is
+for your rights to be considered.
-its own balance plus the balance of originated accounts and
-contracts that are delegated to it.
 
-Rolls
+There is a simple rpc that can be used to check your rights for every
-~~~~~
+cycle, up to 5 cycles in the future.
-
-In the network, rights for baking and endorsing are randomly assigned
-to delegates proportionally to the number of rolls they have been
-delegated.
-A roll is just a block of 10K tezzies.
-
-To know when you will be allowed to bake in the current cycle, you
-might try the following RPCs (use ``tezos-client list known
-addresses`` to check the address of your account *bob*).
 
 ::
 
-   tezos-client rpc post /chains/main/blocks/head/helpers/rights/baking/delegate/tz1_xxxxxxxxxxx with {}
+   tezos-client rpc get /chains/main/blocks/head/helpers/baking_rights\?cycle=300\&delegate=tz1_xxxxxxxxxxx\&max_priority=2
-   { "ok":
-        [ { "level": 1400.000000, "priority": 2.000000,
-            "timestamp": "2017-05-19T03:21:52Z" },
-          ...  ] }
 
-When you obtain Alphanet coins from :ref:`the faucet<faucet>`, if you
+Sometimes a delegate skips its turn so it is worth considering also
-are lucky to obtain more than one roll, you can register a delegate
+baking rights at priority 2 like in the example above.
-using this identity.
+There is no priority for endorsements, every missed endorsement is
-Otherwise, you need to ask the faucet for more accounts, orginate a
+lost.
-account for each one and delegate them to the first.
 
+Inactive delegates
+~~~~~~~~~~~~~~~~~~
 
-Deposits
+If a delegate doesn't show any sign of activity for `preserved_cycles`
-~~~~~~~~
+it is marked **inactive** and its rights are removed.
-
+This mechanism is important to remove inactive delegates and reallocate
-When baking or endorsing a block, a *security deposit* (or *bond*) is
+their rights to the active ones so that the network is always working
-frozen for ``preserved_cycles`` cycles from the account of the
+smoothly.
-delegate.
+Normally even a baker with one single roll should perform enough
-Hence a delegate must have enough funds to be able to pay security
+operations during 5 cycles to remain active.
-deposits for all the blocks it can potentially bake/endorse during
+If for some reason you delegate is marked inactive you can reactivate
-``preserved_cycles``.
+it simply by re-registering again like above.
-The current deposits are *512tz* for baked block and *64tz* for
-endorsement.
-
-Being delegated coins doesn't mean that a delegate can spend them,
-they only add up to its rolls count.
-All the deposits that are necessary to run the deamons can only be put
-down from the delegate account.
-
 
 Baker
 ~~~~~
 
 The baker is a daemon that once connected to an account, computes the
 baking rights for that account, collects transactions from the mempool
-and bakes a block at priority zero.
+and bakes a block.
 Note that the baker is the only program that needs direct access to
 the node data directory for performance reasons.
 
@@ -136,7 +245,6 @@ all accounts.
 
    tezos-endorser-alpha run
 
-
 Accuser
 ~~~~~~~
 
@@ -163,15 +271,6 @@ bake/endorse there are other ways than duplicating your credentials.
 **Never** use the same account on two daemons.
 
 
-Rewards
-~~~~~~~
-
-After ``preserved_cycles``, not only the delegate takes back control of
-its frozen deposits but it also receives the rewards for its hard work
-which amount to 16ꜩ to bake a block and ``ꜩ2 / <block_priority>`` for
-endorsing a block.
-
-
 Docker
 ~~~~~~