Merge pull request #218 from bitshares/jmj_bsip_75

BSIP 75 - Asset Owner defines MCR and MSSR values

bsip-0075.md

@@ -0,0 +1,107 @@
+```
+BSIP: 0075
+Title: Asset Owner Defines MCR and MSSR Values
+Authors:
+  Bangzi1001
+  John Jones <jmjatlanta@gmail.com>
+  Michel Santos
+Status: Accepted
+Type: Protocol
+Created: 2019-09-19
+Discussion: https://github.com/bitshares/bsips/issues/96
+Worker: TBD
+```
+
+# Abstract
+This BSIP provides the ability for the asset creator to decide if adjustments to the Maintenance Collateral Ratio (MCR) or the Maximum Short Squeeze Ratio (MSSR) should be done by the asset owner or by price feed providers.
+
+# Motivation
+Asset owners are often in the best position to control the values of MCR and MSSR of their asset. Therefore, they should be able to have direct control to adjust those values, should they choose to allow themselves. They should also be able to forfeit this direct control.
+
+# Rationale
+Prior to this change, adjustments to MCR and MSSR were handled by feed producers. This often requires the asset owner to contact the feed producer and ask for the change. For some assets, such a step is time consuming for both parties and ill-fitted as part of the feed producer's responsibilities.
+
+This new change shall permit the asset owner to determine who should have the responsibility to maintain those values.  It shall also permit the asset owner to forfeit the right to update the parameter.  Therefore the asset owner may continue changing the responsibility unless and until the permission is forfeited.
+
+
+# Specification
+
+**Note:** "Implementation Hints" are not to be considered part of the formal specification, but merely as a _possible_ implementation.
+
+## Parameter
+
+Each of these new issuer-defined parameters shall be independently configurable of the other.
+
+**Implementation Hint:** New optional fields in `bitasset_options` may be defined for every asset to contain these new parameters
+
+```
+struct bitasset_options
+{
+    struct ext {
+      //...
+      /// The parameters which the issuer has permission to update
+      optional<uint16_t> mcr; // Maintenance Collateral Ratio
+      optional<uint16_t> mssr; // Maximum Short Squeeze Ratio
+    }
+};
+```
+
+## Effect of a Parameter
+
+All relevant blockchain contracts _shall use_ a parameter _if it is set_ and _shall ignore_ the derived parameters from the asset's published feeds.
+
+All relevant blockchain contracts _shall ignore_ a parameter _if it is not set_ and _shall use_ the derived parameters from the asset's published feeds.
+
+At the time that this BSIP activates, these issuer-defined parameters shall not be _set_ and will therefore not affect the current behavior of the asset _unless and until_ each asset owner sets a parameter.
+
+An asset owner shall also be able to set and unset a parameter at will unless the permission to change that parameter has been forfeited as described in [Permission to Change the Parameter](#permissions).
+
+
+## <div id="permissions">Permission to Change the Parameters</div>
+
+The permission to change any of these parameters shall make use of new permissions.  _Each of the parameters shall have its own distinct permission._  Disabling the permission prohibits the changing of the parameter as described in [Changing the Parameters](#changing-parameters).
+
+The existing set of asset issuer permissions shall be expanded to permit an asset owner to forfeit changing the parameters.  It shall not be permitted to regain a permission after it is forfeited unless the supply of the asset is zero.
+
+Existing software clients might not be updated to make use of these new parameters.  Changing the permissions shall be designed such that older software clients may not accidentally forfeit these permissions either for existing assets or new assets.  _The parameters and the permissions to change parameters shall be designed such that they are defaulted to enabled.  The permissions shall be designed such that **explicit disabling/forfeiting** is required which should not be possible with older software clients._
+
+**Implementation Hints**
+
+The `asset_object.asset_options.issuer_permissions` may be expanded to include `disable_mcr_update`, `disable_mssr_update`.
+
+Appropriate changes to the ASSET_ISSUER_PERMISSION_MASK and UIA_ASSET_ISSUER_PERMISSION_MASK are advised to be both backward and forward compatible.
+
+
+## <div id="changing-parameters">Changing the Parameters</div>
+
+It shall be possible to set and unset a parameter at any time __if and only if__ its respective [permission](#permissions) is enabled.
+
+**Implementation Hints**
+
+The `create_asset_operation` can be modified to include the setting of the parameters above.
+
+The `update_asset_operation` can be modified to disable/forfeit the permissions to change, and to enable/regain the permissions _if_ the supply is zero.
+
+The `asset_update_bitasset_operation` can be modified to permit updating of the MCR and MSSR values, if the asset has the appropriate permissions.  Much of the logic currently in `asset_publish_feeds_evaluator::do_apply()` (i.e. call order checks and calculations) can be called here if MCR and MSSR are adjusted.
+
+Note: older client software may unexpectedly unset a parameter (although not a flag nor a permission) that is already set due to incompatibility. When a new parameters was sucessfully set or updated, the asset owner was aware of the new feature and has been using client software that is compatible to the new feature, the asset owner should already be aware of the risks of using incompatible older client software and should avoid using it when possible.
+
+# Discussion
+
+Any client software that intends to allow owners of smart assets to create or to change these new parameters will need to be updated.  Older client software may continue to be used but will not be able to view, change, or set these new parameters.
+
+
+## Risks
+
+If an asset owner **sets** a parameter and later forfeits the permission to change the parameter, **that parameter will be locked forever**.  In contrast, if an asset owner leaves a parameter **unset** and later forfeits the permission to change the parameter, that parameter can still be changed by current and future feed publishers.
+
+If an asset owner has set a parameter with compatible (new) client software, but uses incompatible (old) client software afterwards, the parameter may be unset unexpectedly by the incompatible client software.
+
+# Summary for Shareholders
+For some assets, having feed producers control MCR and MSSR values is cumbersome and ill-fitting. This BSIP allows asset owners to decide at asset creation time if the responsibility of those values should be from feed producers' consensus or set directly by the asset owner themselves.
+
+# Copyright
+This document is placed in the public domain.
+
+# See Also
+[BSIP 59](https://github.com/bitshares/bsips/blob/master/bsip-0059.md) documents procedures for adjusting MCR and MSSR of smartcoins by polling.