Skip to content

refactor: use snake case for fee spec #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gregdhill wants to merge 1 commit into
base: master
Choose a base branch
from
Open

refactor: use snake case for fee spec #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 23 additions & 23 deletions docs/spec/fee.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Data Model
Scalars (Fees)
--------------

.. _issueFee:
.. _fee_scalar_issue_fee:

IssueFee
........
Expand All @@ -31,7 +31,7 @@ Issue fee share (configurable parameter, as percentage) that users need to pay u
- Paid in ``interBTC``
- Initial value: 0.5%

.. _issueGriefingCollateral:
.. _fee_scalar_issue_griefing_collateral:

IssueGriefingCollateral
.......................
Expand All @@ -41,7 +41,7 @@ Issue griefing collateral as a percentage of the locked collateral of a Vault a
- Paid in collateral
- Initial value: 0.005%

.. _refundFee:
.. _fee_scalar_refund_fee:

RefundFee
.........
Expand All @@ -51,7 +51,7 @@ Refund fee (configurable parameter, as percentage) that users need to pay to ref
- Paid in ``interBTC``
- Initial value: 0.5%

.. _redeemFee:
.. _fee_scalar_redeem_fee:

RedeemFee
.........
Expand All @@ -61,7 +61,7 @@ Redeem fee share (configurable parameter, as percentage) that users need to pay
- Paid in ``interBTC``
- Initial value: 0.5%

.. _premiumRedeemFee:
.. _fee_scalar_premium_redeem_fee:

PremiumRedeemFee
................
Expand All @@ -71,7 +71,7 @@ Fee for users to premium redeem (as percentage). If users execute a redeem with
- Paid in collateral
- Initial value: 5%

.. _punishmentFee:
.. _fee_scalar_punishment_fee:

PunishmentFee
.............
Expand All @@ -82,7 +82,7 @@ The fee is paid in collateral based on the ``interBTC`` amount at the current ex
- Paid in collateral
- Initial value: 10%

.. _theftFee:
.. _fee_scalar_theft_fee:

TheftFee
........
Expand All @@ -93,7 +93,7 @@ The fee is paid in collateral taken from the liquidated Vault.
- Paid in collateral
- Initial value: 5%

.. _theftFeeMax:
.. _fee_scalar_theft_fee_max:

TheftFeeMax
...........
Expand All @@ -103,7 +103,7 @@ This is expressed in Bitcoin to ensure consistency between assets.

- Initial value: 0.1 BTC

.. _replaceGriefingCollateral:
.. _fee_scalar_replace_griefing_collateral:

ReplaceGriefingCollateral
.........................
Expand All @@ -117,8 +117,8 @@ This collateral will be slashed and allocated to the replacing Vault if the to-b
Functions
~~~~~~~~~

distributeRewards
-----------------
distribute_rewards
------------------

Distributes fees among incentivised network participants.

Expand All @@ -127,7 +127,7 @@ Specification

*Function Signature*

``distributeRewards(amount)``
``distribute_rewards(amount)``

*Preconditions*

Expand All @@ -138,10 +138,10 @@ Specification
* If there are no registered funds, rewards MUST be sent to the treasury account.
* Otherwise, rewards MUST be distributed according to :ref:`reward_distributeReward`.

.. _withdrawRewards:
.. _fee_function_withdraw_rewards:

withdrawRewards
---------------
withdraw_rewards
----------------

A function that allows incentivised network participants to withdraw all earned rewards.

Expand All @@ -150,22 +150,22 @@ Specification

*Function Signature*

``withdrawRewards(accountId, vaultId)``
``withdraw_rewards(account_id, vault_id)``

*Parameters*

* ``accountId``: the account withdrawing ``interBTC`` rewards.
* ``vaultId``: the vault that generated ``interBTC`` rewards.
* ``account_id``: the account withdrawing ``interBTC`` rewards.
* ``vault_id``: the vault that generated ``interBTC`` rewards.

*Events*

* :ref:`withdrawRewardsEvent`
* :ref:`fee_event_withdraw_rewards`

*Preconditions*

* The function call MUST be signed by ``accountId``.
* The function call MUST be signed by ``account_id``.
* The BTC Parachain status in the :ref:`security` component MUST NOT be ``SHUTDOWN:2``.
* The ``accountId`` MUST have available rewards for ``interBTC``.
* The ``account_id`` MUST have available rewards for ``interBTC``.

*Postconditions*

Expand All @@ -175,7 +175,7 @@ Specification
Events
~~~~~~

.. _withdrawRewardsEvent:
.. _fee_event_withdraw_rewards:

WithdrawRewards
---------------
Expand All @@ -191,4 +191,4 @@ WithdrawRewards

*Functions*

* :ref:`withdrawRewards`
* :ref:`fee_function_withdraw_rewards`
10 changes: 5 additions & 5 deletions docs/spec/issue.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ Specification
* The Vault MUST be registered and active.
* The Vault MUST NOT be banned.
* The ``amount`` MUST be greater than or equal to :ref:`issueBtcDustValue`.
* The ``griefingCollateral`` MUST exceed or equal the value of request ``amount`` at the current exchange-rate, multiplied by :ref:`issueGriefingCollateral`.
* The ``griefingCollateral`` MUST exceed or equal the value of request ``amount`` at the current exchange-rate, multiplied by :ref:`fee_scalar_issue_griefing_collateral`.
* The ``griefingCollateral`` MUST be equal or less than the requester's free balance in the :ref:`griefingCurrency`.
* The :ref:`tryIncreaseToBeIssuedTokens` function MUST return a new BTC deposit address for the Vault ensuring that the Vault's free collateral is above the :ref:`SecureCollateralThreshold` for the requested ``amount`` and that a unique BTC address is used for depositing BTC.
* A new unique ``issuedId`` MUST be generated via the :ref:`generateSecureId` function.
Expand All @@ -166,7 +166,7 @@ Specification
* ``issue.period``: MUST be the current :ref:`issuePeriod`.
* ``issue.griefingCollateral``: MUST be the ``griefingCollateral`` amount passed to the function.
* ``issue.amount``: MUST be ``amount`` minus ``issue.fee``.
* ``issue.fee``: MUST equal ``amount`` multiplied by :ref:`issueFee`.
* ``issue.fee``: MUST equal ``amount`` multiplied by :ref:`fee_scalar_issue_fee`.
* ``issue.requester``: MUST be the ``requester``
* ``issue.btcAddress``: MUST be the BTC address returned from the :ref:`tryIncreaseToBeIssuedTokens`
* ``issue.btcPublicKey``: MUST be the BTC public key returned from the :ref:`tryIncreaseToBeIssuedTokens`
Expand Down Expand Up @@ -218,7 +218,7 @@ Specification
* The Vault's ``toBeIssuedTokens`` MUST decrease by the deficit (``issue.amount - amountTransferred``).
* The Vault's free balance in the :ref:`griefingCurrency` MUST increase by the ``griefingCollateral * (1 - amountTransferred / (issue.amount + issue.fee))``.
* The requester's free balance in the :ref:`griefingCurrency` MUST increase by the ``griefingCollateral * amountTransferred / (issue.amount + issue.fee)``.
* The ``issue.fee`` MUST be updated to the amount transferred multiplied by the :ref:`issueFee`.
* The ``issue.fee`` MUST be updated to the amount transferred multiplied by the :ref:`fee_scalar_issue_fee`.
* The ``issue.amount`` MUST be set to the amount transferred minus the updated ``issue.fee``.

* If the amount transferred IS NOT less than the expected amount:
Expand All @@ -229,7 +229,7 @@ Specification
* If the Vault IS NOT liquidated and has sufficient collateral:

* The Vault's ``toBeIssuedTokens`` MUST increase by the surplus (``amountTransferred - issue.amount``).
* The ``issue.fee`` MUST be updated to the amount transferred multiplied by the :ref:`issueFee`.
* The ``issue.fee`` MUST be updated to the amount transferred multiplied by the :ref:`fee_scalar_issue_fee`.
* The ``issue.amount`` MUST be set to the amount transferred minus the updated ``issue.fee``.

* If the Vault IS NOT liquidated and does not have sufficient collateral:
Expand Down Expand Up @@ -398,7 +398,7 @@ Error Codes

* **Message**: "User provided collateral below limit."
* **Function**: :ref:`requestIssue`
* **Cause**: User provided griefingCollateral below :ref:`issueGriefingCollateral`.
* **Cause**: User provided griefingCollateral below :ref:`fee_scalar_issue_griefing_collateral`.

``ERR_UNAUTHORIZED_USER``

Expand Down
10 changes: 5 additions & 5 deletions docs/spec/redeem.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ Specification

*Preconditions*

Let ``burnedTokens`` be ``amountWrapped`` minus the result of the multiplication of :ref:`redeemFee` and ``amountWrapped``. Then:
Let ``burnedTokens`` be ``amountWrapped`` minus the result of the multiplication of :ref:`fee_scalar_redeem_fee` and ``amountWrapped``. Then:

* The function call MUST be signed by *redeemer*.
* The BTC Parachain status in the :ref:`security` component MUST be set to ``RUNNING:0``.
Expand All @@ -166,7 +166,7 @@ Let ``burnedTokens`` be ``amountWrapped`` minus the result of the multiplication

*Postconditions*

Let ``burnedTokens`` be ``amountWrapped`` minus the result of the multiplication of :ref:`redeemFee` and ``amountWrapped``. Then:
Let ``burnedTokens`` be ``amountWrapped`` minus the result of the multiplication of :ref:`fee_scalar_redeem_fee` and ``amountWrapped``. Then:

* The vault's ``toBeRedeemedTokens`` MUST increase by ``burnedTokens``.
* ``amountWrapped`` of the redeemer's tokens MUST be locked by this transaction.
Expand All @@ -175,7 +175,7 @@ Let ``burnedTokens`` be ``amountWrapped`` minus the result of the multiplication

* ``redeem.vault`` MUST be the requested ``vault``
* ``redeem.opentime`` MUST be the current :ref:`activeBlockCount`
* ``redeem.fee`` MUST be :ref:`redeemFee` multiplied by ``amountWrapped`` if ``redeemer != vault``, otherwise this should be zero.
* ``redeem.fee`` MUST be :ref:`fee_scalar_redeem_fee` multiplied by ``amountWrapped`` if ``redeemer != vault``, otherwise this should be zero.
* ``redeem.transferFeeBtc`` MUST be the inclusion fee, which is the multiplication of :ref:`RedeemTransactionSize` and the fee rate estimate reported by the oracle,
* ``redeem.amountBtc`` MUST be ``amountWrapped - redeem.fee - redeem.transferFeeBtc``,
* ``redeem.period`` MUST be the current value of the :ref:`RedeemPeriod`,
Expand All @@ -184,7 +184,7 @@ Let ``burnedTokens`` be ``amountWrapped`` minus the result of the multiplication
* ``redeem.btcHeight`` MUST be the current height of the btc relay,
* ``redeem.status`` MUST be ``Pending``,
* If the vault's collateralization rate is above the :ref:`PremiumCollateralThreshold`, then ``redeem.premium`` MUST be ``0``,
* If the vault's collateralization rate is below the :ref:`PremiumCollateralThreshold`, then ``redeem.premium`` MUST be :ref:`premiumRedeemFee` multiplied by the worth of ``redeem.amountBtc``,
* If the vault's collateralization rate is below the :ref:`PremiumCollateralThreshold`, then ``redeem.premium`` MUST be :ref:`fee_scalar_premium_redeem_fee` multiplied by the worth of ``redeem.amountBtc``,

.. _liquidationRedeem:

Expand Down Expand Up @@ -321,7 +321,7 @@ Then:
* If the vault is *not* liquidated, the following collateral changes are made:

* If ``reimburse`` is true, the user SHOULD be reimbursed the worth of ``amountIncludingParachainFee`` in collateral. The transfer MUST be saturating, i.e. if the amount is not available, it should transfer whatever amount *is* available.
* A punishment fee MUST be tranferred from the vault's backing collateral to the redeemer: :ref:`punishmentFee`. The transfer MUST be saturating, i.e. if the amount is not available, it should transfer whatever amount *is* available.
* A punishment fee MUST be tranferred from the vault's backing collateral to the redeemer: :ref:`fee_scalar_punishment_fee`. The transfer MUST be saturating, i.e. if the amount is not available, it should transfer whatever amount *is* available.

* If ``reimburse`` is true:

Expand Down
2 changes: 1 addition & 1 deletion docs/spec/refund.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ Specification

* ``refund.vault``: MUST be the ``vault``.
* ``refund.amountWrapped``: MUST be the ``amount - fee``
* ``refund.fee``: MUST equal ``amount`` multiplied by :ref:`refundFee`.
* ``refund.fee``: MUST equal ``amount`` multiplied by :ref:`fee_scalar_refund_fee`.
* ``refund.amountBtc``: MUST be the ``amount``.
* ``refund.issuer``: MUST be the ``issuer``.
* ``refund.btcAddress``: MUST be the ``btcAddress``.
Expand Down
4 changes: 2 additions & 2 deletions docs/spec/replace.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Step-by-Step

2. *oldVault* submits a replace request, indicating how much BTC is to be migrated by calling the :ref:`requestReplace` function.

* *oldVault* is required to lock some amount of DOT collateral (:ref:`replaceGriefingCollateral`) as griefing protection, to prevent *oldVault* from holding *newVault*'s DOT collateral locked in the BTC Parachain without ever finalizing the redeem protocol (transfer of BTC).
* *oldVault* is required to lock some amount of DOT collateral (:ref:`fee_scalar_replace_griefing_collateral`) as griefing protection, to prevent *oldVault* from holding *newVault*'s DOT collateral locked in the BTC Parachain without ever finalizing the redeem protocol (transfer of BTC).

3. Optional: *oldVault* can withdraw the request by calling the :ref:`withdrawReplace` function with a specified amount. For example, if *oldVault* requested a replacement for 10 tokens, and 2 tokens have been accepted by some *newVault*, then it can withdraw up to 8 tokens from being replaced.

Expand Down Expand Up @@ -146,7 +146,7 @@ Specification
* The *oldVault* MUST NOT be banned.
* The *oldVault* MUST NOT be nominated (if :ref:`vault_nomination` is enabled).
* If the ``btcAmount`` is greater than the Vault's ``replacableTokens = issuedTokens - toBeRedeemTokens - toBeReplaceTokens``, set the ``btcAmount`` to the ``replaceableTokens`` amount.
* The *oldVault* MUST provide sufficient ``griefingCollateral`` such that the ratio of all of its ``toBeReplacedTokens`` and ``replaceCollateral`` is above :ref:`replaceGriefingCollateral`.
* The *oldVault* MUST provide sufficient ``griefingCollateral`` such that the ratio of all of its ``toBeReplacedTokens`` and ``replaceCollateral`` is above :ref:`fee_scalar_replace_griefing_collateral`.
* The *oldVault* MUST request sufficient ``btcAmount`` to be replaced such that its total is above ``ReplaceBtcDustValue``.

*Postconditions*
Expand Down