Skip to content

BSIP77: Permissions and their forfeiture #277

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

Merged
abitmore merged 2 commits into from
May 29, 2020
Merged

BSIP77: Permissions and their forfeiture #277

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7f741a7
BSIP77: Parameters, effects, permissions to change, and forfeiting pe…
MichelSantos May 28, 2020
c943d80
Update author list
abitmore May 29, 2020
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
107 changes: 86 additions & 21 deletions bsip-0077.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
Title: Require Higher CR When Creating / Adjusting Debt Positions
Authors: Abit More
@shulthz
Michel Santos
Status: Accept
Type: Protocol
Created: 2019-09-30
Expand All @@ -23,47 +24,111 @@ stability of the smartcoin.

# Specification

**Note:** "Implementation Hints" are not to be considered part of the formal specification, but merely as a _possible_ implementation.

## Parameter

Add one parameter "Initial Collateral Ratio" (ICR) to each smartcoin asset, which can be updated by the asset owner.

When adjusting a position, apply [BSIP30](https://github.com/bitshares/bsips/blob/master/bsip-0030.md)
if current CR is lower than ICR but not MCR.
**Implementation Hint:** The optional field that can be set by the asset owner in `bitasset_options` of every asset.

```
struct bitasset_options
{
struct ext {
//...
/// The parameters which the issuer has permission to update
optional<uint16_t> initial_collateral_ratio;
}
};
```

## Effect of a Parameter

Before the protocol upgrade:
When adjusting a position, **the logic of [BSIP30](https://github.com/bitshares/bsips/blob/master/bsip-0030.md) shall be amended** such that the current CR shall be compared to the ICR **instead of** the maintenance collateral ratio (MCR). The effects of this BSIP's amendment on the relevant smart contracts can be summarized in a comparison of the desired behaviors _before versus after_ the protocol upgrade.

**Before the protocol upgrade:**
```
when creating a new debt position
require CR > MCR
When creating a new debt position
Require CR > MCR

when adjusting a debt position
if new CR <= MCR
require CR increased and debt not increased
When adjusting a debt position
If new CR <= MCR
Require CR increased and debt not increased

when current CR <= MCR
trigger margin call
When current CR <= MCR
Trigger margin call
```

After the protocol upgrade:
**After the protocol upgrade:**
```
Require ICR >= MCR

when creating a new debt position
require CR > ICR
When creating a new debt position
Require CR > ICR

when adjusting a debt position
if new CR <= ICR
require CR increased and debt not increased
When adjusting a debt position
If new CR <= ICR
Require CR increased and debt not increased

when current CR <= MCR
trigger margin call
When current CR <= MCR
Trigger margin call
```

Note: logic around *target collateral ratio* (TCR) is not affected.
_Note: The logic around *target collateral ratio* (TCR) is not affected._

At the time that this BSIP activates, the new Initial Collateral Ratio parameter will not be _set_ and _shall therefore default to the current MCR value_. Similarly, whenever the Initial Collateral Ratio is unset by an asset owner, the ICR value _shall default to the current MCR value_.

An asset owner shall 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 the new parameter shall make use of a new permission. Disabling the permission prohibits the changing of the parameter as described in [Changing the Parameter](#changing-parameters).

The existing set of asset issuer permissions shall be expanded to permit an asset owner to forfeit changing the new parameter. 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 the new parameter. Changing the permissions shall be designed such that older software clients may not accidentally forfeit the permission either for existing assets or new assets. _The parameter and the permission to change parameter shall be designed such that they are defaulted to enabled. The permission 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` could be expanded to include `disable_icr_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 Parameter</div>

It shall be possible to set and unset the parameter at any time __if and only if__ its respective [permission](#permissions) is enabled.

**Implementation Hints**

The `create_asset_operation` could be modified to include the setting of the parameters above.

The `update_asset_operation` could 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` could be modified to permit updating of the ICR value, if the asset has the appropriate permissions.


# Discussion

Any client software that intends to allow owners of smart assets to create or to change the 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 the new parameter.

## Risks

**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** parameter is sucessfully set or updated, the asset owner **demonstrates awareness of the new feature** by using client software that is compatible with the new feature. **The asset owner should be aware of the risks of using incompatible older client software and should avoid using it when possible.**

If an asset owner **sets** a parameter and later forfeits the permission to change the parameter, **that parameter will be locked forever**.

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

This BSIP introduces a new tool for smartcoin asset owners to fine tune their assets.
Having an ICR greater than MCR would probably result in less risk-loving traders borrowing that
smartcoin, thus may lead to fewer market activities and worse liquidity. It's up to the asset owners
to decide whether to use this tool.
smartcoin, thus may lead to fewer market activities and worse liquidity. It is up to the asset
owners to decide whether to use this tool.

# References
* https://github.com/bitshares/bsips/issues/129#issuecomment-483937118
Expand Down