From 4e4dcbde9e9c7f0a8b42d093a95ccef64c230c16 Mon Sep 17 00:00:00 2001 From: Gregory Hill Date: Wed, 9 Feb 2022 10:54:10 +0000 Subject: [PATCH] refactor: use snake case for fee spec Signed-off-by: Gregory Hill --- docs/spec/fee.rst | 46 +++++++++++++++++++++---------------------- docs/spec/issue.rst | 10 +++++----- docs/spec/redeem.rst | 10 +++++----- docs/spec/refund.rst | 2 +- docs/spec/replace.rst | 4 ++-- 5 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/spec/fee.rst b/docs/spec/fee.rst index c984e55..cb5e294 100644 --- a/docs/spec/fee.rst +++ b/docs/spec/fee.rst @@ -21,7 +21,7 @@ Data Model Scalars (Fees) -------------- -.. _issueFee: +.. _fee_scalar_issue_fee: IssueFee ........ @@ -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 ....................... @@ -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 ......... @@ -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 ......... @@ -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 ................ @@ -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 ............. @@ -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 ........ @@ -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 ........... @@ -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 ......................... @@ -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. @@ -127,7 +127,7 @@ Specification *Function Signature* -``distributeRewards(amount)`` +``distribute_rewards(amount)`` *Preconditions* @@ -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. @@ -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* @@ -175,7 +175,7 @@ Specification Events ~~~~~~ -.. _withdrawRewardsEvent: +.. _fee_event_withdraw_rewards: WithdrawRewards --------------- @@ -191,4 +191,4 @@ WithdrawRewards *Functions* -* :ref:`withdrawRewards` +* :ref:`fee_function_withdraw_rewards` diff --git a/docs/spec/issue.rst b/docs/spec/issue.rst index aa0e578..06c4227 100644 --- a/docs/spec/issue.rst +++ b/docs/spec/issue.rst @@ -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. @@ -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` @@ -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: @@ -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: @@ -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`` diff --git a/docs/spec/redeem.rst b/docs/spec/redeem.rst index 631ae01..8e586d1 100644 --- a/docs/spec/redeem.rst +++ b/docs/spec/redeem.rst @@ -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``. @@ -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. @@ -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`, @@ -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: @@ -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: diff --git a/docs/spec/refund.rst b/docs/spec/refund.rst index 9276198..d4cc13d 100644 --- a/docs/spec/refund.rst +++ b/docs/spec/refund.rst @@ -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``. diff --git a/docs/spec/replace.rst b/docs/spec/replace.rst index 78b20c5..9e22d64 100644 --- a/docs/spec/replace.rst +++ b/docs/spec/replace.rst @@ -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. @@ -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*