mirror of https://github.com/nucypher/nucypher.git
Initial musings about a write-up for WorkLock v4 including hypothetical scenarios.
derekpierre
parent
50fb513043
commit
cc7af27a71
|
|
@ -13,23 +13,143 @@ WorkLock offers specific advantages over ICO or airdrop as a distribution mechan
|
|||
|
||||
The WorkLock begins with an open bidding period, during which anyone seeking to participate can send ETH to the WorkLock contract to be escrowed on-chain.
|
||||
At any time, WorkLock participants can cancel their bid to forgo NU and recoup their escrowed ETH immediately.
|
||||
Once the bidding period closes, the WorkLock contract doesn't accept more bids, although it still accepts cancellations during an additional time window.
|
||||
Once the bidding period closes, the WorkLock contract does not accept more bids, but it will still accept cancellations during an additional time window.
|
||||
At the end of this cancellation period, stake-locked NU will be distributed according to the following principles:
|
||||
|
||||
- Each bidder receives, at least, the minimum amount of NU needed to stake.
|
||||
- All bids will be greater or equal to the minimum allowed bid.
|
||||
- In addition to the minimum amount of NU, each bidder receives a portion of the remaining NU, distributed pro rata across all participants, taking into consideration their bid surplus with respect to the minimum bid.
|
||||
- If the resulting NU amount is above the maximum allowed NU to stake, then such a bidder has their bid partially refunded until the corresponding amount of NU is within the allowed limits.
|
||||
- All of the tokens held by WorkLock will be distributed.
|
||||
- All bids must be greater than or equal to the minimum allowed bid.
|
||||
- For each bid, the surplus above the minimum allowed bid is called the `bonus`; all bids are composed of a minimum bid (fixed amount) and a `bonus` (variable amount).
|
||||
- Each bidder will receive at least the minimum amount of NU needed to stake.
|
||||
- Once all bidders have been assigned the minimum amount of NU, each bidder with a `bonus` will receive a portion of the remaining NU, distributed pro rata across all participants, taking into consideration only their bonus amounts.
|
||||
- If the resulting NU amount distributed to a bidder is above the maximum allowed NU to stake, then such a bidder has their bid partially refunded until the corresponding amount of NU is within the allowed limits.
|
||||
|
||||
Finally, if WorkLock participants use that stake-locked NU to run a node, the NU will eventually unlock and their escrowed ETH will be returned in full.
|
||||
|
||||
|
||||
Hypothetical Bidding Scenarios
|
||||
------------------------------
|
||||
|
||||
For each scenario, assume that:
|
||||
|
||||
#. WorkLock holds 280,000,000 NU tokens and the minimum bid is 15 ETH.
|
||||
#. The minimum amount of NU required to stake is 15,000 NU and the maximum stake size is 4,000,000 NU.
|
||||
#. The total number of bidders is 1000 bidders (including you) with a total of 50,000 ETH committed (including your bid).
|
||||
#. For our purposes, a `whale` bid is a bid that causes the calculated stake size to be larger than the maximum stake size (4,000,000 NU).
|
||||
|
||||
|
||||
Scenario 1: Resulting stake size does not exceed maximum stake size
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**You submit a bid of 22 ETH i.e. 15 ETH minimum bid + 7 ETH bonus.**
|
||||
|
||||
*How many NU tokens would you receive?*
|
||||
|
||||
- Each of the 1000 bidders (including you) would receive at least the minimum NU to stake (15,000 NU)
|
||||
- Remaining NU in WorkLock after minimum distribution = ``280,000,000 NU - (15,000 NU * 1000 bidders)`` = 265,000,000 NU
|
||||
- Bonus ETH pool (i.e. total ETH not including minimum amounts) = ``50,000 ETH - (15 ETH * 1000 bidders)`` = 35,000 ETH
|
||||
- Your bonus portion of the ETH bonus pool = ``7 ETH / 35,000 ETH`` = 0.02%
|
||||
- Your portion of remaining NU = ``0.02% * 265,000,000 NU`` = 53,000 NU
|
||||
|
||||
**Total NU tokens received = 15,000 NU + 53,000 NU = 68,000 NU**
|
||||
|
||||
Scenario 2: Resulting stake size exceeds maximum stake size (1 whale bid)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**You submit a bid of 715 ETH i.e. 15 ETH minimum bid + 700 ETH bonus.**
|
||||
|
||||
*How many NU tokens would you receive?*
|
||||
|
||||
- Each of the 1000 bidders (including you) would receive at least the minimum NU to stake (15,000 NU)
|
||||
- Remaining NU in WorkLock after minimum distribution = ``280,000,000 NU - (15,000 NU * 1000 bidders)`` = 265,000,000 NU
|
||||
- Bonus ETH pool (i.e. total ETH not including minimum amounts) = ``50,000 ETH - (15 ETH * 1000 bidders)`` = 35,000 ETH
|
||||
- Your bonus portion of the ETH bonus pool = ``700 ETH / 35,000 ETH`` = 2%
|
||||
- Your portion of remaining NU = ``2% * 265,000,000 NU`` = 5,300,000 NU
|
||||
|
||||
However, the total amount of NU tokens to receive ``15,000 NU + 5,300,000 NU`` = 5,315,000 NU is greater than
|
||||
the maximum stake amount (4,000,000 NU). Therefore, the amount of NU tokens distributed to you needs to be reduced,
|
||||
and some of your ETH refunded.
|
||||
|
||||
- Typically the calculation for the NU received from the bonus portion is ``(your bonus ETH / ETH bonus pool) * remaining NU tokens``.
|
||||
- The additional complication here is that refunding ETH reduces your bonus ETH **AND** the bonus ETH pool (35,000 ETH in this example) since the bonus ETH pool includes the bonus ETH portion of your bid.
|
||||
- A more complicated equation arises for the bonus part of the calculation
|
||||
|
||||
``stake size = ( (your bonus ETH - x) / (ETH bonus pool - x) ) * (remaining NU tokens)``, where ``x`` is the refunded ETH
|
||||
- Since you will receive a 15,000 NU minimum, and the maximum stake size is 4,000,000 NU, the most you can receive from the remaining NU is ``4,000,000 NU - 15,000 NU`` = 3,985,000 NU
|
||||
- Therefore, ``3,985,000 NU = ( (700 ETH - x ETH) / (35,000 ETH - x ETH) ) * 265,000,000 NU``.
|
||||
- Reorganizing the equation, ``x = ( 700 ETH * 265,000,000 NU - 35,000 ETH * 3,985,000 NU ) / ( 265,000,000 NU - 3,985,000 NU )`` ~ 176.33 ETH
|
||||
- Therefore, your final bonus bid = ``700 ETH - 176.33 ETH`` = 523.67 ETH
|
||||
- Your bonus portion of the ETH bonus pool = ``523.67 / (35,000 ETH - 176.33 ETH)`` ~ 1.504%
|
||||
- Your portion of remaining NU ~ ``1.504% * 265,000,000 NU`` ~ 3,985,006.46 NU
|
||||
|
||||
|
||||
**Total NU tokens received ~ 3,985,006.46 NU (rounding) + 15,000 NU ~ 4,000,000 NU, and refunded ETH ~ 176.33 ETH (rounding)**
|
||||
|
||||
|
||||
Scenario 3: Resulting stake size exceeds maximum stake size (2 whale bids)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Someone else submitted a bid of 715 ETH (15 ETH + 700 ETH bonus); we'll call them `whale_1`.**
|
||||
|
||||
**You submit a bid of 785 ETH i.e. 15 ETH minimum bid + 770 ETH bonus; you are `whale_2`.**
|
||||
|
||||
*How many NU tokens would you receive?*
|
||||
|
||||
- Each of the 1000 bidders (including you) would receive at least the minimum NU to stake (15,000 NU)
|
||||
- Remaining NU in WorkLock after minimum distribution = ``280,000,000 NU - (15,000 NU * 1000 bidders)`` = 265,000,000 NU
|
||||
- Bonus ETH pool (i.e. total ETH not including minimum amounts) = ``50,000 ETH - (15 ETH * 1000 bidders)`` = 35,000 ETH
|
||||
- Your bonus portion of the ETH bonus pool = ``770 ETH / 35,000 ETH`` = 2.2%
|
||||
- Your portion of remaining NU = ``2.2% * 265,000,000 NU`` = 5,830,000 NU
|
||||
|
||||
However, the total amount of NU tokens to receive 15,000 NU + 5,830,000 NU = 5,845,000 NU which is greater than
|
||||
the maximum stake amount (4,000,000 NU).
|
||||
|
||||
From the previous scenario, the equation arises for the bonus part of the calculation
|
||||
|
||||
- ``stake size = ( (your bonus ETH - x) / (ETH bonus pool - x) ) * (remaining NU tokens)``, where ``x`` is the refunded ETH
|
||||
- However, now there is more than one whale bid, which would also cause the ETH bonus pool to reduce as well
|
||||
- Instead the following `whale resolution` algorithm is followed:
|
||||
|
||||
#. Select the smallest whale bonus ETH bid - in this case 700 ETH from `whale_1` < 770 ETH from `whale_2`
|
||||
#. Equalize the bonus ETH whale bids for all other whales (in this case, just `whale_2` i.e. just you) to all be the smallest whale bonus bid i.e. 700 ETH in this case
|
||||
#. Since your bid (whale_2) is > 700 ETH, you will be refunded 770 ETH - 700 ETH = 70 ETH
|
||||
#. This reduces the resulting bonus ETH pool which will now be 35,000 ETH - 70 ETH = 34,930 ETH
|
||||
#. We now need to calculate the refunds based on the updated ETH bonus pool, and the maximum stake size.
|
||||
#. Remember that everyone receives a 15,000 NU minimum, and the maximum stake size is 4,000,000 NU, so the most you can receive from the remaining NU is ``4,000,000 NU - 15,000 NU`` = 3,985,000 NU
|
||||
#. Since we have multiple bidders, our equation is ``x = (min whale bid * token supply - eth_supply * max stake) / (token supply - n * max stake)``, where ``n`` is the number of whale bidders
|
||||
#. Using values ``x = (700 ETH * 265,000,000 NU - 34,930 ETH * 3,985,000 NU) / (265,000,000 NU - 2 * 3,985,000 NU)`` ~ 180.15 ETH i.e. each whale gets refunded 180.15 ETH
|
||||
#. Therefore `whale_1` is refunded 180.15 ETH and `whale_2` (i.e. you) refunded 180.15 ETH + 70 ETH = 250.15 ETH
|
||||
#. Based on the refunds:
|
||||
|
||||
- The bonus bids for the whales will now be equalized:
|
||||
|
||||
- `whale_1` bonus bid = 700 ETH - 180.15 ETH = 519.85 ETH
|
||||
- `whale_2` bonus bid = 770 ETH - 250.15 ETH = 519.85 ETH
|
||||
|
||||
- The updated ETH Bonus Pool will be ``35,000 ETH - (180.15 ETH + 250.15 ETH)`` = 34,569.70 ETH
|
||||
|
||||
#. Each whale's portion of the ETH bonus pool = ``519.85 ETH / 34,569.70 ETH`` ~ 1.504%
|
||||
#. Each whale's portion of the remaining NU = ``1.504% * 265,000,000 NU`` ~ 3,984,999.86 NU
|
||||
|
||||
**Total NU tokens received ~ 3,984,999.86 NU + 15,000 NU ~ 4,000,000 NU, and refunded ETH ~ 176.33 ETH (rounding)**
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
In Scenario 1 and 2, you will notice that the ETH bonus pool has been reduced. This produces a subtle situation -
|
||||
for previous non-whale bids (bids that in the original ETH bonus pool did not produce a stake larger than the
|
||||
maximum stake) their bids remained unchanged, but the ETH bonus pool was reduced. This means that some bids that
|
||||
were not whales, may become whales once the ETH bonus pool is reduced since their proportion of the bonus pool
|
||||
increased. Therefore, the `whale resolution` algorithm described in Scenario 2 is repeated for multiple rounds
|
||||
until there are no longer any whales. To keep the explanation simple, both Scenario 1 and Scenario 2 ignore this
|
||||
situation since the calculations become even more complex.
|
||||
|
||||
|
||||
WorkLock CLI
|
||||
------------
|
||||
|
||||
The ``nucypher worklock`` CLI command provides the ability to participate in WorkLock. To better understand the
|
||||
commands and their options, use the ``--help`` option.
|
||||
|
||||
Common CLI flags
|
||||
----------------
|
||||
|
||||
All ``nucypher worklock`` commands share a similar structure:
|
||||
|
||||
.. code::
|
||||
|
|
|
|||
Loading…
Reference in New Issue