diff --git a/docs/spec/nomination.rst b/docs/spec/nomination.rst index 558366f..05fc191 100644 --- a/docs/spec/nomination.rst +++ b/docs/spec/nomination.rst @@ -274,7 +274,7 @@ Specification * ``getTotalNominatedCollateral(vaultId)`` must return zero. * For all nominators, ``getNominatorCollateral(vaultId, userId)`` must return zero. * Staking pallet ``nonce`` must be incremented by one. -* The return value of calling :ref:`staking_computeRewardAtIndex` parameterized with ``(nonce - 1, INTERBTC, vaultId, userId)`` must be equal to the user's nomination just before the vault opted out. +* The return value of calling :ref:`staking_function_compute_reward_at_index` parameterized with ``(nonce - 1, INTERBTC, vaultId, userId)`` must be equal to the user's nomination just before the vault opted out. .. _depositNominationCollateral: diff --git a/docs/spec/staking.rst b/docs/spec/staking.rst index d501029..c2dd011 100644 --- a/docs/spec/staking.rst +++ b/docs/spec/staking.rst @@ -8,7 +8,7 @@ Overview This pallet is very similar to the :ref:`rewards` pallet - it is also based on the `Scalable Reward Distribution `_ algorithm. The reward pallet keeps track of how much rewards vaults have earned. However, when nomination is enabled, there needs to be a way to relay parts of the vault's rewards to its nominators. Furthermore, the nominator's collaterals can be consumed, e.g., when a redeem is cancelled. This pallet is responsible for both tracking the rewards, and the current amount of contributed collaterals of vaults and nominators. -The idea is to have one reward pool per vault, where both the vault and all of its nominators have a stake equal to their contributed collateral. However, when collateral is consumed, either in :ref:`cancelRedeem` or :ref:`liquidateVault`, the collateral of each of these stakeholders should decrease proportionally to their stake. To be able to achieve this without iteration, in addition to tracking ``RewardPerToken``, a similar value ``SlashPerToken`` is introduced. Similarly, in addition to ``RewardTally``, we now also maintain a ``SlashTally`` is for each stakeholder. When calculating a reward for a stakeholder, a compensated stake is calculated, based on ``Stake``, ``SlashPerToken`` and ``SlashTally``. +The idea is to have one reward pool per vault, where both the vault and all of its nominators have a stake equal to their contributed collateral. However, when collateral is consumed, either in :ref:`cancelRedeem` or :ref:`liquidateVault`, the collateral of each of these stakeholders should decrease proportionally to their stake. To be able to achieve this without iteration, in addition to tracking :ref:`staking_map_reward_per_token`, a similar value ``SlashPerToken`` is introduced. Similarly, in addition to :ref:`staking_map_reward_tally`, we now also maintain a ``SlashTally`` is for each stakeholder. When calculating a reward for a stakeholder, a compensated stake is calculated, based on ``Stake``, ``SlashPerToken`` and ``SlashTally``. When a vault opts out of nomination, all nominators should receive their collateral back. This is achieved by distributing all funds from the vault's shared collateral as rewards. However, a vault is free to opt back into nominator after having opted out. It is possible for the vault to do this before all nominators have withdrawn their reward. To ensure that the bookkeeping remains intact for the nominators to get their rewards at a later point, all variables are additionally indexed by a nonce, which increases every time a vault opts out of nomination. Effectively, this create a new pool for every nominated period. @@ -24,62 +24,62 @@ Maps TotalStake .......... -Maps ``(currencyId, nonce, vaultId)`` to the total stake deposited by the given vault and its nominators, with the given nonce and currencyId. +Maps ``(currency_id, nonce, vault_id)`` to the total stake deposited by the given vault and its nominators, with the given nonce and currency_id. TotalCurrentStake ................. -Maps ``(currencyId, nonce, vaultId)`` to the total stake deposited by the given vault and its nominators, with the given nonce and currencyId, excluding stake that has been slashed. +Maps ``(currency_id, nonce, vault_id)`` to the total stake deposited by the given vault and its nominators, with the given nonce and currency_id, excluding stake that has been slashed. TotalRewards ............ -Maps ``(currencyId, nonce, vaultId)`` to the total rewards distributed to the vault and its nominators. This value is currently only used for testing purposes. +Maps ``(currency_id, nonce, vault_id)`` to the total rewards distributed to the vault and its nominators. This value is currently only used for testing purposes. -.. _RewardPerToken: +.. _staking_map_reward_per_token: RewardPerToken .............. -Maps ``(currencyId, nonce, vaultId)`` to the amount of reward the vault and its nominators get per unit of stake. +Maps ``(currency_id, nonce, vault_id)`` to the amount of reward the vault and its nominators get per unit of stake. -.. _RewardTally: +.. _staking_map_reward_tally: RewardTally ........... -Maps ``(currencyId, nonce, vaultId, nominatorId)`` to the reward tally the given nominator has for the given vault's reward pool, in the given nonce and currency. The tally influences how much the nominator can withdraw. +Maps ``(currency_id, nonce, vault_id, nominator_id)`` to the reward tally the given nominator has for the given vault's reward pool, in the given nonce and currency. The tally influences how much the nominator can withdraw. Stake ..... -Maps ``(currencyId, nonce, vaultId, nominatorId)`` to the stake the given nominator has in the given vault's reward pool, in the given nonce and currency. Initially, the stake is equal to its contributed collateral. However, after a slashing has occurred, the nominator's collateral must be compensated, using :ref:`computeStakeAtIndex`. +Maps ``(currency_id, nonce, vault_id, nominator_id)`` to the stake the given nominator has in the given vault's reward pool, in the given nonce and currency. Initially, the stake is equal to its contributed collateral. However, after a slashing has occurred, the nominator's collateral must be compensated, using :ref:`staking_function_compute_stake_at_index`. SlashPerToken .............. -Akin to :ref:`RewardPerToken`: maps ``(currencyId, nonce, vaultId)`` to the amount the vault and its nominators got slashed for per unit of stake. It is used for computing the effective stake (or equivalently, its collateral) in :ref:`computeStakeAtIndex`. +Akin to :ref:`staking_map_reward_per_token`: maps ``(currency_id, nonce, vault_id)`` to the amount the vault and its nominators got slashed for per unit of stake. It is used for computing the effective stake (or equivalently, its collateral) in :ref:`staking_function_compute_stake_at_index`. SlashTally ........... -Akin to :ref:`RewardTally`: maps ``(currencyId, nonce, vaultId, nominatorId)`` to the slash tally the given nominator has for the given vault's reward pool, in the given nonce and currency. It is used for computing the effective stake (or equivalently, its collateral) in :ref:`computeStakeAtIndex`. +Akin to :ref:`staking_map_reward_tally`: maps ``(currency_id, nonce, vault_id, nominator_id)`` to the slash tally the given nominator has for the given vault's reward pool, in the given nonce and currency. It is used for computing the effective stake (or equivalently, its collateral) in :ref:`staking_function_compute_stake_at_index`. .. _Nonce: Nonce ..... -Maps ``(currencyId, vaultId)`` current value of the nonce the given vault uses in the given currency. The nonce is increased every time :ref:`forceRefund` is called, i.e., when a vault opts out of nomination. Since nominators get their collateral back as a withdrawable reward, the bookkeeping must remain intact when the vault once again opts into nomination. By incrementing this nonce, effectively a new reward pool is created for the new session. All externally callable functions use the nonce stored in this map, except for the reward withdrawal function :ref:`withdrawRewardAtIndex`. +Maps ``(currency_id, vault_id)`` current value of the nonce the given vault uses in the given currency. The nonce is increased every time :ref:`staking_function_force_refund` is called, i.e., when a vault opts out of nomination. Since nominators get their collateral back as a withdrawable reward, the bookkeeping must remain intact when the vault once again opts into nomination. By incrementing this nonce, effectively a new reward pool is created for the new session. All externally callable functions use the nonce stored in this map, except for the reward withdrawal function :ref:`staking_function_withdraw_reward_at_index`. Functions ~~~~~~~~~ -.. _staking_depositStake: +.. _staking_function_deposit_stake: -depositStake ------------- +deposit_stake +------------- Adds a stake for the given account and currency in the reward pool. @@ -88,32 +88,32 @@ Specification *Function Signature* -``depositStake(currencyId, vaultId, nominatorId, amount)`` +``depositStake(currency_id, vault_id, nominator_id, amount)`` *Parameters* -* ``currencyId``: The currency for which to add the stake -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency for which to add the stake +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator * ``amount``: The amount by which the stake is to increase *Events* -* :ref:`staking_DepositStakeEvent` +* :ref:`staking_event_deposit_stake` *Postconditions* -* ``Stake[currencyId, nonce, vaultId, nominatorId]`` MUST increase by ``amount`` -* ``TotalStake[currencyId, nonce, vaultId]`` MUST increase by ``amount`` -* ``TotalCurrentStake[currencyId, nonce, vaultId]`` MUST increase by ``amount`` -* ``RewardTally[currencyId, nonce, vaultId, nominatorId]`` MUST increase by ``RewardPerToken[currencyId, nonce, vaultId] * amount``. -* ``SlashTally[currencyId, nonce, vaultId, nominatorId]`` MUST increase by ``SlashPerToken[currencyId, nonce, vaultId] * amount``. +* ``Stake[currency_id, nonce, vault_id, nominator_id]`` MUST increase by ``amount`` +* ``TotalStake[currency_id, nonce, vault_id]`` MUST increase by ``amount`` +* ``TotalCurrentStake[currency_id, nonce, vault_id]`` MUST increase by ``amount`` +* ``RewardTally[currency_id, nonce, vault_id, nominator_id]`` MUST increase by ``RewardPerToken[currency_id, nonce, vault_id] * amount``. +* ``SlashTally[currency_id, nonce, vault_id, nominator_id]`` MUST increase by ``SlashPerToken[currency_id, nonce, vault_id] * amount``. -.. _staking_withdrawStake: +.. _staking_function_withdraw_stake: -withdrawStake -------------- +withdraw_stake +-------------- Withdraws the given amount stake for the given nominator or vault. This function also modifies the nominator's ``SlashTally`` and ``Stake``, such that the ``Stake`` is once again equal to its collateral. @@ -122,25 +122,25 @@ Specification *Function Signature* -``withdrawStake(currencyId, vaultId, nominatorId, amount)`` +``withdraw_stake(currency_id, vault_id, nominator_id, amount)`` *Parameters* -* ``currencyId``: The currency for which to add the stake -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency for which to add the stake +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator * ``amount``: The amount by which the stake is to decrease *Events* -* :ref:`staking_withdrawStakeEvent` +* :ref:`staking_event_withdraw_stake` *Preconditions* -* Let ``nonce`` be ``Nonce[currencyId, vaultId]``, and -* Let ``stake`` be ``Stake[nonce, currencyId, vaultId, nominatorId]``, and -* Let ``slashPerToken`` be ``SlashPerToken[currencyId, nonce, vaultId]``, and -* Let ``slashTally`` be ``slashTally[nonce, currencyId, vaultId, nominatorId]``, and +* Let ``nonce`` be ``Nonce[currency_id, vault_id]``, and +* Let ``stake`` be ``Stake[nonce, currency_id, vault_id, nominator_id]``, and +* Let ``slashPerToken`` be ``SlashPerToken[currency_id, nonce, vault_id]``, and +* Let ``slashTally`` be ``slashTally[nonce, currency_id, vault_id, nominator_id]``, and * Let ``toSlash`` be ``stake * slashPerToken - slashTally`` Then: @@ -149,56 +149,56 @@ Then: *Postconditions* -* Let ``nonce`` be ``Nonce[currencyId, vaultId]``, and -* Let ``stake`` be ``Stake[nonce, currencyId, vaultId, nominatorId]``, and -* Let ``slashPerToken`` be ``SlashPerToken[currencyId, nonce, vaultId]``, and -* Let ``slashTally`` be ``slashTally[nonce, currencyId, vaultId, nominatorId]``, and +* Let ``nonce`` be ``Nonce[currency_id, vault_id]``, and +* Let ``stake`` be ``Stake[nonce, currency_id, vault_id, nominator_id]``, and +* Let ``slashPerToken`` be ``SlashPerToken[currency_id, nonce, vault_id]``, and +* Let ``slashTally`` be ``slashTally[nonce, currency_id, vault_id, nominator_id]``, and * Let ``toSlash`` be ``stake * slashPerToken - slashTally`` Then: -* ``Stake[currencyId, nonce, vaultId, nominatorId]`` MUST decrease by ``toSlash + amount`` -* ``TotalStake[currencyId, nonce, vaultId]`` MUST decrease by ``toSlash + amount`` -* ``TotalCurrentStake[currencyId, nonce, vaultId]`` MUST decrease by ``amount`` -* ``SlashTally[nonce, currencyId, vaultId, nominatorId]`` MUST be set to ``(stake - toSlash - amount) * slashPerToken`` -* ``RewardTally[nonce, currencyId, vaultId, nominatorId]`` MUST decrease by ``rewardPerToken * amount`` +* ``Stake[currency_id, nonce, vault_id, nominator_id]`` MUST decrease by ``toSlash + amount`` +* ``TotalStake[currency_id, nonce, vault_id]`` MUST decrease by ``toSlash + amount`` +* ``TotalCurrentStake[currency_id, nonce, vault_id]`` MUST decrease by ``amount`` +* ``SlashTally[nonce, currency_id, vault_id, nominator_id]`` MUST be set to ``(stake - toSlash - amount) * slashPerToken`` +* ``RewardTally[nonce, currency_id, vault_id, nominator_id]`` MUST decrease by ``rewardPerToken * amount`` -.. _slashStake: +.. _staking_function_slash_stake: -slashStake ----------- +slash_stake +----------- -Slashes a vault's stake in the given currency in the reward pool. Conceptually, this decreases the stakes, and thus the collaterals, of all of the vault's stakeholders. Indeed, :ref:`computeStakeAtIndex` will reflect the stake changes on the stakeholder. +Slashes a vault's stake in the given currency in the reward pool. Conceptually, this decreases the stakes, and thus the collaterals, of all of the vault's stakeholders. Indeed, :ref:`staking_function_compute_stake_at_index` will reflect the stake changes on the stakeholder. Specification ............. *Function Signature* -``slashStake(currencyId, vaultId, amount)`` +``slash_stake(currency_id, vault_id, amount)`` *Parameters* -* ``currencyId``: The currency for which to add the stake -* ``vaultId``: Account of the vault +* ``currency_id``: The currency for which to add the stake +* ``vault_id``: Account of the vault * ``amount``: The amount by which the stake is to decrease *Preconditions* -* ``TotalStake[currencyId, Nonce[currencyId, vaultId], vaultId]`` MUST NOT be zero +* ``TotalStake[currency_id, Nonce[currency_id, vault_id], vault_id]`` MUST NOT be zero *Postconditions* -Let ``nonce`` be ``Nonce[currencyId, vaultId]``, and ``initialTotalStake`` be ``TotalCurrentStake[currencyId, nonce, vaultId]``. Then: +Let ``nonce`` be ``Nonce[currency_id, vault_id]``, and ``initialTotalStake`` be ``TotalCurrentStake[currency_id, nonce, vault_id]``. Then: -* ``SlashPerToken[currencyId, nonce, vaultId]`` MUST increase by ``amount / TotalStake[currencyId, nonce, vaultId]`` -* ``TotalCurrentStake[currencyId, nonce, vaultId]`` MUST decrease by ``amount`` -* if ``initialTotalStake - amount`` is NOT zero, ``RewardPerToken[currencyId, nonce, vaultId]`` MUST increase by ``RewardPerToken[currencyId, nonce, vaultId] * amount / (initialTotalStake - amount)`` +* ``SlashPerToken[currency_id, nonce, vault_id]`` MUST increase by ``amount / TotalStake[currency_id, nonce, vault_id]`` +* ``TotalCurrentStake[currency_id, nonce, vault_id]`` MUST decrease by ``amount`` +* if ``initialTotalStake - amount`` is NOT zero, ``RewardPerToken[currency_id, nonce, vault_id]`` MUST increase by ``RewardPerToken[currency_id, nonce, vault_id] * amount / (initialTotalStake - amount)`` -.. _computeStakeAtIndex: +.. _staking_function_compute_stake_at_index: -computeStakeAtIndex -------------------- +compute_stake_at_index +---------------------- Computes a vault's stakeholder's effective stake. This is also the amount collateral that belongs to the stakeholder. @@ -207,26 +207,26 @@ Specification *Function Signature* -``computeStakeAtIndex(nonce, currencyId, vaultId, amount)`` +``compute_stake_at_index(nonce, currency_id, vault_id, amount)`` *Parameters* * ``nonce``: The nonce to compute the stake at -* ``currencyId``: The currency for which to compute the stake -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency for which to compute the stake +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator *Postconditions* -Let ``stake`` be ``Stake[nonce, currencyId, vaultId, nominatorId]``, and -Let ``slashPerToken`` be ``SlashPerToken[currencyId, nonce, vaultId]``, and -Let ``slashTally`` be ``slashTally[nonce, currencyId, vaultId, nominatorId]``, then +Let ``stake`` be ``Stake[nonce, currency_id, vault_id, nominator_id]``, and +Let ``slashPerToken`` be ``SlashPerToken[currency_id, nonce, vault_id]``, and +Let ``slashTally`` be ``slashTally[nonce, currency_id, vault_id, nominator_id]``, then * The function MUST return ``stake - stake * slash_per_token + slash_tally``. -.. _staking_distributeReward: +.. _staking_function_distribute_reward: distributeReward ---------------- @@ -238,22 +238,22 @@ Specification *Function Signature* -``distributeReward(currencyId, reward)`` +``distributeReward(currency_id, reward)`` *Parameters* -* ``currencyId``: The currency being distributed -* ``vaultId``: the vault for which distribute rewards +* ``currency_id``: The currency being distributed +* ``vault_id``: the vault for which distribute rewards * ``reward``: The amount being distributed *Events* -* :ref:`staking_distributeRewardEvent` +* :ref:`staking_event_distribute_reward` *Postconditions* -Let ``nonce`` be ``Nonce[currencyId, vaultId]``, and -Let ``initialTotalCurrentStake`` be ``TotalCurrentStake[currencyId, nonce, vaultId]``, then: +Let ``nonce`` be ``Nonce[currency_id, vault_id]``, and +Let ``initialTotalCurrentStake`` be ``TotalCurrentStake[currency_id, nonce, vault_id]``, then: * If ``initialTotalCurrentStake`` is zero, or if ``reward`` is zero, then: @@ -262,16 +262,16 @@ Let ``initialTotalCurrentStake`` be ``TotalCurrentStake[currencyId, nonce, vault * Otherwise (if ``initialTotalCurrentStake`` and ``reward`` are not zero), then: - * ``RewardPerToken[currencyId, nonce, vaultId)]`` MUST increase by ``reward / initialTotalCurrentStake`` - * ``TotalRewards[currencyId, nonce, vaultId]`` MUST increase by ``reward`` + * ``RewardPerToken[currency_id, nonce, vault_id)]`` MUST increase by ``reward / initialTotalCurrentStake`` + * ``TotalRewards[currency_id, nonce, vault_id]`` MUST increase by ``reward`` * The function MUST return ``reward``. -.. _staking_computeRewardAtIndex: +.. _staking_function_compute_reward_at_index: -computeRewardAtIndex --------------------- +compute_reward_at_index +----------------------- Calculates the amount of rewards the vault's stakeholder can withdraw. @@ -280,27 +280,27 @@ Specification *Function Signature* -``computeRewardAtIndex(nonce, currencyId, vaultId, amount)`` +``compute_reward_at_index(nonce, currency_id, vault_id, amount)`` *Parameters* * ``nonce``: The nonce to compute the stake at -* ``currencyId``: The currency for which to compute the stake -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency for which to compute the stake +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator *Postconditions* -Let ``stake`` be the result of ``computeStakeAtIndex(nonce, currencyId, vaultId, nominatorId)``, then: -Let ``rewardPerToken`` be ``RewardPerToken[currencyId, nonce, vaultId]``, and -Let ``rewardTally`` be ``rewardTally[nonce, currencyId, vaultId, nominatorId]``, then +Let ``stake`` be the result of ``compute_stake_at_index(nonce, currency_id, vault_id, nominator_id)``, then: +Let ``rewardPerToken`` be ``RewardPerToken[currency_id, nonce, vault_id]``, and +Let ``rewardTally`` be ``rewardTally[nonce, currency_id, vault_id, nominator_id]``, then * The function MUST return ``max(0, stake * rewardPerToken - reward_tally)`` -.. _withdrawRewardAtIndex: +.. _staking_function_withdraw_reward_at_index: -withdrawRewardAtIndex ---------------------- +withdraw_reward_at_index +------------------------ Withdraws the rewards the given vault's stakeholder has accumulated. @@ -309,14 +309,14 @@ Specification *Function Signature* -``withdrawRewardAtIndex(currencyId, vaultId, amount)`` +``withdraw_reward_at_index(currency_id, vault_id, amount)`` *Parameters* * ``nonce``: The nonce to compute the stake at -* ``currencyId``: The currency for which to compute the stake -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency for which to compute the stake +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator *Events* @@ -324,22 +324,22 @@ Specification *Preconditions* -* ``computeRewardAtIndex(nonce, currencyId, vaultId, nominatorId)`` MUST NOT return an error +* :ref:`staking_function_compute_reward_at_index` MUST NOT return an error *Postconditions* -Let ``reward`` be the result of ``computeRewardAtIndex(nonce, currencyId, vaultId, nominatorId)``, then: -Let ``stake`` be ``Stake(nonce, currencyId, vaultId, nominatorId)``, then: -Let ``rewardPerToken`` be ``RewardPerToken[currencyId, nonce, vaultId]``, and +Let ``reward`` be the result of ``compute_reward_at_index(nonce, currency_id, vault_id, nominator_id)``, then: +Let ``stake`` be ``Stake(nonce, currency_id, vault_id, nominator_id)``, then: +Let ``rewardPerToken`` be ``RewardPerToken[currency_id, nonce, vault_id]``, and * ``TotalRewards[currency_id, nonce, vault_id]`` MUST decrease by ``reward`` -* ``RewardTally[currencyId, nonce, vaultId, nominatorId]`` MUST be set to ``stake * rewardPerToken`` +* ``RewardTally[currency_id, nonce, vault_id, nominator_id]`` MUST be set to ``stake * rewardPerToken`` * The function MUST return ``reward`` -.. _forceRefund: +.. _staking_function_force_refund: -forceRefund ------------ +force_refund +------------ This is called when the vault opts out of nomination. All collateral is distributed among the stakeholders, after which the vault withdraws his part immediately. @@ -348,98 +348,98 @@ Specification *Function Signature* -``forceRefund(currencyId, vaultId)`` +``force_refund(currency_id, vault_id)`` *Parameters* -* ``currencyId``: The currency for which to compute the stake -* ``vaultId``: Account of the vault +* ``currency_id``: The currency for which to compute the stake +* ``vault_id``: Account of the vault *Events* -* :ref:`forceRefundEvent` -* :ref:`increaseNonceEvent` +* :ref:`staking_event_force_refund` +* :ref:`staking_event_increase_nonce` *Preconditions* -Let ``nonce`` be ``Nonce[currencyId, vaultId]``, then: +Let ``nonce`` be ``Nonce[currency_id, vault_id]``, then: -* ``distributeReward(currencyId, vaultId, TotalCurrentStake[currencyId, nonce, vaultId])`` MUST NOT return an error -* ``withdrawRewardAtIndex(nonce, currencyId, vaultId, vaultId)`` MUST NOT return an error -* ``depositStake(currencyId, vaultId, vaultId, reward)`` MUST NOT return an error -* ``Nonce[currencyId, vaultId]`` MUST be increased by 1 +* ``distributeReward(currency_id, vault_id, TotalCurrentStake[currency_id, nonce, vault_id])`` MUST NOT return an error +* ``withdrawRewardAtIndex(nonce, currency_id, vault_id, vault_id)`` MUST NOT return an error +* ``depositStake(currency_id, vault_id, vault_id, reward)`` MUST NOT return an error +* ``Nonce[currency_id, vault_id]`` MUST be increased by 1 *Postconditions* -Let ``nonce`` be ``Nonce[currencyId, vaultId]``, then: +Let ``nonce`` be ``Nonce[currency_id, vault_id]``, then: -* ``distributeReward(currencyId, vaultId, TotalCurrentStake[currencyId, nonce, vaultId])`` MUST have been called -* ``withdrawRewardAtIndex(nonce, currencyId, vaultId, vaultId)`` MUST have been called -* ``Nonce[currencyId, vaultId]`` MUST be increased by 1 -* ``depositStake(currencyId, vaultId, vaultId, reward)`` MUST have been called AFTER having increased the nonce +* ``distributeReward(currency_id, vault_id, TotalCurrentStake[currency_id, nonce, vault_id])`` MUST have been called +* ``withdrawRewardAtIndex(nonce, currency_id, vault_id, vault_id)`` MUST have been called +* ``Nonce[currency_id, vault_id]`` MUST be increased by 1 +* ``depositStake(currency_id, vault_id, vault_id, reward)`` MUST have been called AFTER having increased the nonce -.. _staking_DepositStakeEvent: +.. _staking_event_deposit_stake: DepositStake --------------- *Event Signature* -``DepositStake(currencyId, vaultId, nominatorId, amount)`` +``DepositStake(currency_id, vault_id, nominator_id, amount)`` *Parameters* -* ``currencyId``: The currency of the reward pool -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency of the reward pool +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator * ``amount``: The amount by which the stake is to increase *Functions* -* :ref:`staking_depositStake` +* :ref:`staking_function_deposit_stake` -.. _staking_withdrawStakeEvent: +.. _staking_event_withdraw_stake: WithdrawStake --------------- *Event Signature* -``WithdrawStake(currencyId, vaultId, nominatorId, amount)`` +``WithdrawStake(currency_id, vault_id, nominator_id, amount)`` *Parameters* -* ``currencyId``: The currency of the reward pool -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency of the reward pool +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator * ``amount``: The amount by which the stake is to increase *Functions* -* :ref:`staking_WithdrawStake` +* :ref:`staking_function_withdraw_stake` -.. _staking_distributeRewardEvent: +.. _staking_event_distribute_reward: DistributeReward ---------------- *Event Signature* -``DistributeReward(currencyId, vaultId, amount)`` +``DistributeReward(currency_id, vault_id, amount)`` *Parameters* -* ``currencyId``: The currency of the reward pool -* ``vaultId``: Account of the vault +* ``currency_id``: The currency of the reward pool +* ``vault_id``: Account of the vault * ``amount``: The amount by which the stake is to increase *Functions* -* :ref:`staking_distributeReward` +* :ref:`staking_function_distribute_reward` @@ -450,55 +450,55 @@ WithdrawReward *Event Signature* -``WithdrawReward(currencyId, vaultId, nominatorId, amount)`` +``WithdrawReward(currency_id, vault_id, nominator_id, amount)`` *Parameters* -* ``currencyId``: The currency of the reward pool -* ``vaultId``: Account of the vault -* ``nominatorId``: Account of the nominator +* ``currency_id``: The currency of the reward pool +* ``vault_id``: Account of the vault +* ``nominator_id``: Account of the nominator * ``amount``: The amount by which the stake is to increase *Functions* -* :ref:`withdrawRewardAtIndex` +* :ref:`staking_function_withdraw_reward_at_index` -.. _forceRefundEvent: +.. _staking_event_force_refund: ForceRefund ----------- *Event Signature* -``ForceRefund(currencyId, vaultId)`` +``ForceRefund(currency_id, vault_id)`` *Parameters* -* ``currencyId``: The currency of the reward pool -* ``vaultId``: Account of the vault +* ``currency_id``: The currency of the reward pool +* ``vault_id``: Account of the vault *Functions* -* :ref:`ForceRefund` +* :ref:`staking_function_force_refund` -.. _increaseNonceEvent: +.. _staking_event_increase_nonce: IncreaseNonce ------------- *Event Signature* -``IncreaseNonce(currencyId, vaultId, nominatorId, amount)`` +``IncreaseNonce(currency_id, vault_id, nominator_id, amount)`` *Parameters* -* ``currencyId``: The currency of the reward pool -* ``vaultId``: Account of the vault +* ``currency_id``: The currency of the reward pool +* ``vault_id``: Account of the vault * ``amount``: The amount by which the stake is to increase *Functions* -* :ref:`forceRefund` +* :ref:`staking_function_force_refund` diff --git a/docs/spec/vault-registry.rst b/docs/spec/vault-registry.rst index ca23342..dc6bc1a 100644 --- a/docs/spec/vault-registry.rst +++ b/docs/spec/vault-registry.rst @@ -327,7 +327,7 @@ Precondition *Postconditions* -* Function :ref:`staking_depositStake` MUST complete successfully - parameterized by ``vaultId`` and ``collateral``. +* Function :ref:`staking_function_deposit_stake` MUST complete successfully - parameterized by ``vaultId`` and ``collateral``. * The vault MUST lock an amount of ``collateral`` of its collateral, using the currency set in ``vault.currencyId``. .. _withdrawCollateral: @@ -364,7 +364,7 @@ Specification *Postconditions* -* Function :ref:`staking_withdrawStake` MUST complete successfully - parameterized by ``vaultId`` and ``withdrawAmount``. +* Function :ref:`staking_function_withdraw_stake` MUST complete successfully - parameterized by ``vaultId`` and ``withdrawAmount``. * The vault's free balance in the currency configured by ``vault.currencyID`` MUST increase by ``withdrawAmount``. * The vault's locked balance in the currency configured by ``vault.currencyID`` MUST decrease by ``withdrawAmount``. @@ -635,7 +635,7 @@ One of: * If the vault is *not* liquidated: * The vault's ``toBeRedeemedTokens`` must be greater than or equal to ``tokens``. - * If ``premium > 0``, then the vault's ``backingCollateral`` (as calculated via :ref:`computeStakeAtIndex`) must be greater than or equal to ``premium``. + * If ``premium > 0``, then the vault's ``backingCollateral`` (as calculated via :ref:`staking_function_compute_stake_at_index`) must be greater than or equal to ``premium``. * If the vault *is* liquidated, then the liquidation vault's ``toBeRedeemedTokens`` must be greater than or equal to ``tokens`` @@ -650,7 +650,7 @@ One of: * The amount ``toBeReleased`` is calculated as ``(vault.liquidatedCollateral * tokens) / vault.toBeRedeemedTokens``. * The vault's ``liquidatedCollateral`` MUST decrease by ``toBeReleased``. - * Function :ref:`staking_depositStake` MUST complete successfully - parameterized by ``vaultId``, ``vaultId``, and ``toBeReleased``. + * Function :ref:`staking_function_deposit_stake` MUST complete successfully - parameterized by ``vaultId``, ``vaultId``, and ``toBeReleased``. * The vault's ``toBeRedeemedTokens`` MUST decrease by ``tokens``. * The vault's ``issuedTokens`` MUST decrease by ``tokens``. @@ -817,7 +817,7 @@ Specification * The amount ``toBeReleased`` MUST be calculated as ``(oldVault.liquidatedCollateral * tokens) / oldVault.toBeRedeemedTokens``. * The ``oldVault``'s ``liquidatedCollateral`` MUST decrease by ``toBeReleased``. - * Function :ref:`staking_depositStake` MUST complete successfully - parameterized by ``oldVault``, ``oldVault`` and ``toBeReleased``. + * Function :ref:`staking_function_deposit_stake` MUST complete successfully - parameterized by ``oldVault``, ``oldVault`` and ``toBeReleased``. * The ``oldVault``'s ``toBeRedeemed`` MUST decrease by ``tokens``. * The ``oldVault``'s ``issuedTokens`` MUST decrease by ``tokens``. @@ -896,12 +896,12 @@ Specification * ``toBeLiquidated`` MUST be calculated as ``(usedCollateral * (usedTokens - toBeRedeemedTokens)) / usedTokens``. * ``remainingCollateral`` MUST be calculated as ``max(0, usedCollateral - toBeLiquidated)``. * Function :ref:`reward_withdrawStake` MUST complete successfully - parameterized by ``vault`` and ``issuedTokens``. -* Function :ref:`staking_withdrawStake` MUST complete successfully - parameterized by ``vault`` and ``remainingCollateral``. +* Function :ref:`staking_function_withdraw_stake` MUST complete successfully - parameterized by ``vault`` and ``remainingCollateral``. * ``liquidatedCollateral`` MUST be increased by ``remainingCollateral``. * ``toWithdraw`` MUST be calculated as ``toBeLiquidated - backingCollateral`` OR ``toBeLiquidated`` if ``backingCollateral > toBeLiquidated``. * ``toSlash`` MUST be calculated as the remainder of the previous calculation. -* Function :ref:`staking_withdrawStake` MUST complete successfully - parameterized by ``vault`` and ``toWithdraw``. -* Function :ref:`slashStake` MUST complete successfully - parameterized by ``vault`` and ``toSlash``. +* Function :ref:`staking_function_withdraw_stake` MUST complete successfully - parameterized by ``vault`` and ``toWithdraw``. +* Function :ref:`staking_function_slash_stake` MUST complete successfully - parameterized by ``vault`` and ``toSlash``. * The liquidation vault MUST be updated as follows: