.. _vault_nomination: Vault Nomination ================ Overview ~~~~~~~~ Nomination is a feature aimed at increasing `interBTC` issuance capacity by allowing Nominators to back a particular Vault. Nominators lock their free collateral so that trusted Vaults can issue `interBTC` backed by the nominated collateral. Nominators are rewarded a fraction of the fees generated by the Vault, while the remaining fees are given to the Vault. Vaults are assumed to be trusted by their Nominators not to steal Bitcoin backed by nominated collateral. .. note:: The current specification requires some level of trust between the Vault and its Nominators. The specification will be revised before this feature goes live to keep the same security model as XCLAIM where Nominators would not trust Vaults. Step-by-step ------------ #. Vaults may opt in to Nomination, expanding the total possible issuance amount. #. The maximum amount that can be nominated is bounded by the Vault's locked collateral. #. Nominators select one or more Vaults and lock their collateral balance on the BTC Parachain. The used currency for each nomination is determined by the vault's collateral currency. If a nominator is nominating different vaults, a different currency can be used for each vault, i.e., a nominator is not limited to a single currency. #. Nominators can go offline and their nominated collateral will generate rewards passively. #. Vaults and Nominators can withdraw their collateral at any point subject to the ``SecureCollateralThreshold``. #. Upon liquidation, Nominators are returned some collateral after remaining requests have been executed. Protocol ~~~~~~~~ Assumptions ----------- **Security Assumptions** #. The operating Vault is trusted by its Nominators not to steal the `interBTC` issued with their collateral. #. There is no transitive trust. If a user trusts Vault A and Vault A trusts Vault B, the user does not trust Vault B. **Liveness Assumptions** #. Nominators are mostly-offline agents, who are slow to respond to system changes. #. Vaults are always-online agents, who can promptly react to system updates. Vault Nomination Protocol ------------------------- #. Vaults must choose to opt in to the Nomination protocol. #. Nominators select a Vault to which they can delegate collateral. They will earn a fraction of any rewards generated by the Vault. #. Vault replacement is disallowed with nominated collateral. Otherwise, Security Assumptions 1 and 2 would be violated. #. The nominated collateral: #. Is in the vault's collateral currency, #. Cannot be withdrawn by the Vault, #. Is locked on the parachain, #. Is capped at a fraction of the Vault’s deposited collateral (:ref:`maxNominationRatio`) to bound the risk for both Vaults and Nominators. #. Liquidation slashing is handled as follows: #. **Proportional Slashing** In case the collateral managed by the Vault falls below the liquidation threshold, the Vault and its Nominators are slashed proportionally to their collateral. #. **Vault First Slashing** In case the Vault steals Bitcoin deposited at its address, its collateral is used to cover as much of the slashed amount as possible. If the Vault's collateral was not enough to cover the entire amount, the Nominators are slashed proportionally for the remaining amount. #. Vaults may opt out of the Nomination protocol which force refunds Nominators if there is enough collateral over the ``SecureCollateralThreshold``. .. _maxNominationRatio: Max Nomination Ratio .................... This ratio prevents the Vault from withdrawing its entire collateral and only exposing Nominators to economic risk, or stealing without liquidation consequences. This means that a Vault can only withdraw collateral as long as the fraction of nominated collateral does not exceed the threshold cap. Capping Nominator collateral also prevents Vaults being “outnumbered” by Nominators and their relative fee earnings being marginalized. The calculation is defined in :ref:`vault-registry`, in the ``getMaxNominationRatio`` function. .. _securityConsiderations: Security Considerations ----------------------- The Vault Nomination protocol changes the economic incentive for Vaults to misbehave, i.e., violate the security of the XCLAIM protocol by stealing BTC. Economic Security without Vault Nomination .......................................... Informally and not considering reputation or rewards, a rational Vault should not steal BTC if the economic value of the collateral is above the value of the BTC held in custody. The *effective collateralization* rate at which Vaults should steal BTC is below 100%. More formally, we can express this as: .. math:: C > b Where :math:`C` is the value of the locked collateral (e.g., DOT) and :math:`b` is the value of the backing asset (e.g., BTC). Note, that we will add an extension to this model such that we account for the *expected* value from the perspective of the Vault for both assets. However, for this simple model, the above should suffice. As an aside, Vaults are liquidated before reaching 100% collateralization as defined by the :ref:`LiquidationThreshold`. Economic Security with Vault Nomination ....................................... Introducing Vault Nomination changes the effective collateralization rate at which Vaults have an economic incentive to steal BTC. In both, the Vault First and Proportional Slashing, the effective collateralization rate at which Vaults should steal can be calculated by considering that if the value of *only* the Vault's collateral is below 100% of the locked BTC, a Vault has an incentive to steal BTC. We can then calculate the effective collateralization, under the assumption that a Vault is fully nominated, by taking the 100% collateralization provided by the Vault and adding the :ref:`maxNominationRatio`: .. math:: 100\% + (100\% * \text{maxNominationRatio}) .. note:: If we take DOT as an example and use a secure collateral ratio of 150% and a premium redeem threshold of 135%, Vaults have an incentive to steal BTC if their collateralization falls below 125%. Above the effective collateralization rate to steal BTC, the incentives to violate the security of the system (i.e., being under-collateralized *or* steal BTC), are different depending on the slashing strategy. **Proportional Slashing** For the under-collateralization failure, both Nominators and Vaults need to be active to (1) add more collateral to prevent such a failure, (2) reduce the amount of backed tokens, i.e., the number of backed interBTC, or (3) a combination of 1 and 2. In this strategy each the Vault and its Nominators are punished proportionally to their collateral holdings. We visualize this with the example below: .. _fig-proportional: .. figure:: ../figures/spec/nomination_proportional_slashing.png :alt: proportional-slashing The slashed collateral (in %) in Proportional Slashing of a Vault and its Nominators. .. note:: Assume the similar DOT example from above. Effective threshold when Vault has an incentive to steal Bitcoin: 100% + (100% * 25%) = 125% collateralization. In case of a liquidation, the Vault is slashed all collateral and the Nominators are slashed all collateral since we slash up to the secure collateral threshold. .. note:: It is not recommended to use this strategy in case of Vault theft. If the Vault steals Bitcoin at collateralization of 187.5% (i.e., 150% + (150% * 25%)), the Vault's and Nominators' collateral are slashed proportionally such that 150%/187.5% = 80% of the collateral is slashed from both the Vault and its Nominators. Normally, the vault should not be motivated to steal but it might be the case if e.g., the DOT/BTC exchange rate drops, the exchange rate update is not yet reflected on chain, nominators are offline and cannot react, and the new exchange rate would bring the combined collateralization below 125% (such that Vault's future collateral is below 100%)). **Vault First Slashing** Nominators cannot control if Vaults decide to steal BTC. While Nominators trust Vaults (see Security Assumption 1 and 2), the protocol still tries to minimize this case by slashing Vaults first in case of theft. Therefore, in case of theft all of the Vaults available collateral are slashed before its Nominators. At the lower bound of :math:`100\% + (100\% * \text{maxNominationRatio})`, both Proportional Slashing and Vault First Slashing slash the same amount of collateral from a Vault and its Nominators. However, at higher collateralization rates, Vaults are comparatively more slashed. See the figure below for an illustration using the threshold examples as above: .. _fig-vault-first: .. figure:: ../figures/spec/nomination_vault_first_slashing.png :alt: vault-first-slashing The slashed collateral (in %) in Vault First Slashing of a Vault and its Nominators. .. note:: Assume the similar DOT example from above. Effective threshold when Vault has an incentive to steal Bitcoin: 100% + (100% * 25%) = 125% collateralization. In case of theft, the vault is slashed all collateral, the nominators are slashed all collateral since we slash up to the secure collateral threshold. However, if the Vault steals Bitcoin at collateralization of 187.5% (i.e., 150% + (150% * 25%)), all of the vault's collateral are slashed and none of the nominators collateral is slashed. Normally, the vault should not be motivated to steal but it might be the case if e.g., you modify my example from the comment above (exchange rate drops, not yet reflected on chain, nominators are offline and cannot react, new exchange rate would bring combined collaterealization below 125% (such that vault's future collateral is below 100%)). In this case, the vault should steal BTC but in this case, we would only slash the vault for this. Risk Summary ............ #. **Increased Exchange Rate Risk on Collateral Withdrawal**: A Nominator may expose the Vault and the other Nominators to additional economic risk by withdrawing nominated collateral during an exchange rate spike. Similarly, the Vault may expose its Nominators to additional economic risk by withdrawing excess collateral. #. **Vaults Have an Increased Incentive to Commit Theft**: The effective collateralization rate at which Vault's should steal Bitcoin increases from 100% to :math::`100\% + (100\% * \text{maxNominationRatio})`. #. **Different Slashing Strategies Reduce the Impact of Theft for Nominators**: By applying Vault First Slashing, the impact of the slashed collateral for Nominators is reduced if the collateralization is :math:`> 100\% + (100\% * \text{maxNominationRatio})`. Data Model ~~~~~~~~~~ Scalars ------- .. _nominationEnabled: NominationEnabled ................. Flag indicating whether this feature is enabled. - If set to ``True``, Vaults MAY opt-in to be nominated. - If set to ``False``, Vaults MUST NOT be able to opt-in to nomination. Already nominated Vaults MUST keep being nominated as Vaults may have issued `interBTC` with nominated collateral when this feature was enabled. Maps ---- Vaults ...... Set of Vault accounts that have enabled nomination. Structs ------- Functions ~~~~~~~~~ .. _setNominationEnabled: setNominationEnabled -------------------- Set the feature flag for Vault nomination. Specification ............. *Function Signature* ``setNominationEnabled(enabled)`` *Parameters* * ``enabled``: ``True`` if nomination should be enabled, ``False`` if it should be disabled. *Preconditions* * The calling account MUST be root (system level origin). *Postconditions* * The ``NominationEnabled`` scalar MUST be set to the value of the ``enabled`` parameter. .. _optInToNomination: optInToNomination ----------------- Allow the Vault to receive nominated collateral. Specification ............. *Function Signature* ``optInToNomination(vaultId)`` *Parameters* * ``vaultId``: the id of the Vault to enable nomination for. *Events* * :ref:`nominationOptInEvent` *Preconditions* * The BTC Parachain status in the :ref:`security` component MUST be ``RUNNING:0``. * :ref:`nominationEnabled` MUST be true. * A Vault with id ``vaultId`` MUST be registered. * The Vault MUST NOT be opted in. *Postconditions* * The Vault MUST be allowed to receive nominated collateral. .. _optOutOfNomination: optOutOfNomination ------------------ Disallow the Vault from receiving nominated collateral and force refund Nominators. Specification ............. *Function Signature* ``optOutOfNomination(vaultId)`` *Parameters* * ``vaultId``: the id of the Vault to deregister from the nomination feature. *Events* * :ref:`nominationOptOutEvent` *Preconditions* * The BTC Parachain status in the :ref:`security` component MUST be ``RUNNING:0``. * A Vault with id ``vaultId`` MUST be registered. * A Vault with id ``vaultId`` MUST exist in the ``Vaults`` mapping. *Postconditions* * The Vault MUST be removed from the ``Vaults`` mapping. * The Vault MUST remain above the secure collateralization threshold. * ``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. .. _depositNominationCollateral: depositCollateral ----------------- Nominate collateral to a selected Vault. Specification ............. *Function Signature* ``depositCollateral(vaultId, nominatorId, amount)`` *Parameters* * ``vaultId``: the id of the Vault to receive the nomination. * ``nominatorId``: the id of the user nominating collateral. * ``amount``: the amount of collateral to nominate. *Events* * :ref:`depositNominationCollateralEvent` *Preconditions* * The BTC Parachain status in the :ref:`security` component MUST be ``RUNNING:0``. * :ref:`nominationEnabled` MUST be true. * A Vault with id ``vaultId`` MUST be registered. * A Vault with id ``vaultId`` MUST exist in the ``Vaults`` mapping. * The nominator's free balance in the vault's used currency MUST be at least `amount`. * The Vault MUST remain below the max nomination ratio. *Postconditions* * The Vault's backing collateral MUST increase by the amount nominated. * The Nominator's balance in the vault's ``currencyId`` MUST decrease by the amount nominated. .. _withdrawNominationCollateral: withdrawCollateral ------------------ Withdraw collateral from a nominated Vault. Specification ............. *Function Signature* ``withdrawCollateral(vaultId, nominatorId, amount)`` *Parameters* * ``vaultId``: the id of the previously nominated Vault. * ``nominatorId``: the id of the user who nominated collateral. * ``amount``: the amount of collateral to withdraw. *Events* * :ref:`withdrawNominationCollateralEvent` *Preconditions* * The BTC Parachain status in the :ref:`security` component MUST be ``RUNNING:0``. * :ref:`nominationEnabled` MUST be true. * A Vault with id ``vaultId`` MUST be registered. * A Vault with id ``vaultId`` MUST exist in the ``Vaults`` mapping. * The Vault MUST remain above the secure collateralization threshold. * Nominator MUST have a nomination with the given vault (including slashes) of at least ``amount``. *Postconditions* * The Vault's collateral MUST decrease by ``amount``. * The Nominator's balance in the vault's ``currencyId`` MUST increase by ``amount``. Events ~~~~~~ .. _nominationOptInEvent: NominationOptIn --------------- *Event Signature* ``NominationOptIn(vaultId)`` *Parameters* * ``vaultId``: the id of the Vault who opted in. *Functions* * :ref:`optInToNomination` .. _nominationOptOutEvent: NominationOptOut ---------------- *Event Signature* ``NominationOptOut(vaultId)`` *Parameters* * ``vaultId``: the id of the Vault who opted out. *Functions* * :ref:`optOutOfNomination` .. _depositNominationCollateralEvent: DepositCollateral ----------------- *Event Signature* ``DepositCollateral(vaultId, nominatorId, amount)`` *Parameters* * ``vaultId``: the id of the Vault who receives the nomination. * ``nominatorId``: the id of the nominator who is depositing collateral. * ``amount``: the amount of nominated collateral. *Functions* * :ref:`depositNominationCollateral` .. _withdrawNominationCollateralEvent: WithdrawCollateral ------------------ *Event Signature* ``WithdrawCollateral(vaultId, nominatorId, amount)`` *Parameters* * ``vaultId``: the id of the previously nominated Vault. * ``nominatorId``: the id of the nominator who is withdrawing collateral. * ``amount``: the amount of nominated collateral. *Functions* * :ref:`withdrawNominationCollateral`