16 KiB

BSIP: 0017
Title: Revive BitAssets after global settlement
Authors: Peter Conrad <>
Status: Draft
Type: Protocol
Created: 2016-10-27
Copyright: Public Domain


BitAssets, i. e. market-pegged assets (MPA) like bitUSD and prediction markets (PM) in BitShares can suffer a "global settlement" event. After global settlement, the asset is effectively rendered useless. This BSIP proposes a protocol change to enable resolving a global settlement so that affected assets can be "reset" and put to good use again.


Market-pegged assets, aka SmartCoins, and to some extent Prediction Markets are among the core features of the BitShares blockchain and as such provide one of our USPs.

MPAs can suffer a "black swan" event. A black swan occurs when the least collateralized short position has insufficient collateral to buy back the borrowed SmartCoins at the current feed price. What happens then is that the MPA is tagged with a "settlement price", defined as the collateral ratio of the least collateralized short. All short positions are closed automatically, by collecting sufficient collateral into a settlement pool and paying out the remainder to the short's owners. MPA holders can use the forced settlement operation to receive their share from the settlement pool in exchange for their MPAs. (Actually there's a bug that prevents this currently, but that's the way it is intended to work.)

A technically quite similar mechanism is used to settle PMs. In a PM, shorters and holders are betting on the outcome of a specific event. Once the actual outcome has materialized, the PM is settled by setting a settlement price.

Both MPAs that have suffered a black swan and PMs that have seen settlement are effectively dead. They can still be transferred or traded, but they can no longer be shorted. Eventually, all significant holders wlll have settled their positions, and some dust will remain scattered all over the place, where the value of the dust position is lower than the fees required to get rid of it.

Allowing MPAs and PMs to be revived after a settlement event will greatly increase the usefulness of both types of assets. Increased usefulness will hopefully boost adoption.


After a global settlement, the value of the unit in question is fixed relative to the underlying asset. This means that any exchange of an amount of the asset in question for the underlying asset at the settlement price does not financially damage the previous owner of the exchanged asset.

Reviving bitassets is beneficial for the network as a whole. This justifies decisions in favour of the network, as long as financial damage to anyone is avoided. Any acceptable financial damage must be in the range of rounding errors that are to be expected when dealing with the assets in question.

In that regard, the "override_transfer" permission, which usually regulates forced transfers of a bitasset by the issuer, can be ignored for the purpose of reviving an asset.


revive_asset operation

A new operation will be introduced that performs the revival. The fee for this operation SHOULD be significant, because it is a computationally intensive operation.

The operation has a single parameter, the asset to be revived.

The operation requires a signature from the asset's issuer authority.

The operation can only be invoked under the following conditions:

  • The asset has a settlement_price, either from a black swan or from an asset_global_settle operation. Note that this is possible only for MPAs and PMs.
  • The global settlement event has happened at least 28 days ago. This parameter requires further discussion, see below.

To execute the operation, all open positions of the asset to be revived are looked up and handled as described below.

Open Positions and How to Handle Them

In the following, SWAN is the asset to be revived. BACK is the asset backing SWAN.


Forced settlements have an expiry date. After that date, they are cancelled if the underlying asset has a settlement_price. For SWAN this is the case, so these are resolved automatically after some time. Because "some time" can be quite long though, it is better to resolve this in a quicker way.

Resolution: execute them all at the time of the black swan. This is a softfork.


Limit orders can either buy or sell SWAN. In the case of a sell, the order holds some amount of SWAN. Sell orders MUST be cancelled to revive the asset. Buy orders SHOULD be cancelled, because the price offered may be based on outdated information.

Resolution: Cancel all orders where either the asset to sell or the asset to receive equals SWAN. An index on limit_order_object::price::quote::asset_id will be added to speed up lookups.


Calls on SWAN are resolved when global settlement happens. So at the time of revival none of these exist.

However, calls may exist with SWAN as collateral. Suppose that DUCK is an asset that is backed by SWAN. Calls on DUCK cannot be cancelled.

Resolution 1: Modify DUCK to be backed by BACK instead of SWAN. Modify all DUCK calls accordingly. Remove price feeds from DUCK.

Resolution 2: Force-settle DUCK. This will free up all SWAN used as collateral for DUCK, i. e. the SWAN will be returned into account_balance objects and resolved as described below.

Note that Resolution 2 is only available for MPAs, not for PMs, because PMs don't have a price feed that can be used to determine the fair value of DUCK vs SWAN in settlements.

Also note that Resolution 2 is recursive - if an asset SLUG exists that is backed by SWAN, SLUG will have to be settled as well.

This solution requires further discussion.


A vesting_balance_object can hold a vesting balance of SWAN for a given account. Vesting balances can vest with different strategies (linear or coin-days).

Resolution: for every non-zero vesting balance of SWAN, create (if necessary) a vesting balance for BACK with an equivalent vesting policy and adjust balance and policy parameters accordingly. An index on vesting_balance_object::asset::asset_id will be added to speed up lookups.


Balance objects (not to be confused with account_balance objects) contain genesis balances, possibly with linear vesting. This should be a rare case in BitShares-2.0, but it is a possible case and requires resolution.

Resolution: all balances of SWAN are replaced with equivalent balances of BACK. An index on balance_object::asset_type will be added to speed up lookups.


Blinded balances are part of the stealth feature of Graphene. A blinded balance has only an asset id, but no (visible) amount. The only visible thing is the total of all blinded balances of that asset type, which is a field in the asset's dynamic data.


  1. A part of the settlement_fund will be set aside for settling blinded balances. For this, a new object type "blinded_settlement_object" will be introduced that carries the blinded_settlement_fund and the remaining total blinded amount.
  2. The blinded_balance_object will receive an additional optional field that may contain a reference to a blinded_settlement_fund. blinded_balances with such a reference may only be withdrawn from, together with other blinded_balances carrying the same reference, but they cannot be transferred anymore. Note: special care needs to be taken in the fee handling here. Using the blinded balance together with the SWAN fee pool must be avoided. Instead, the BACK fee pool must be used (if at all).
  3. Upon withdrawal, the amount withdrawn is immediately converted to BACK, from the blinded_settlement_fund. If the amount withdrawn is equal to the total remaining blinded amount, the remaining blinded_settlement_fund is paid out to the withdrawer and the object is deleted.

Note that the pair (SWAN, blinded_settlement_object) creates a kind of virtual asset that should not be mixed with "pure" SWAN balances by existing user interfaces.

An index on blinded_balance_object::asset_id will be added to speed up lookups.


This object type does not exist yet. It is introduced by the mechanism to handle blinded SWAN balances, as described above.

Resolution: blinded_settlement_objects holding SWAN are immediately converted to BACK.


This is what holds the actual balances of an account. Each such object refers to a specific account and asset. Account_balances of SWAN can be converted into BACK at any time via the forced settlement feature.

Resolution: account balances of SWAN are converted into BACK immediately.


This object defines (among other things) if an asset is in global settlement.


  • pay out remaining settlement_fund to issuer (if any)
  • nullify settlement_price / force_settled_volume
  • empty feed list / unset current_feed
  • empty options.whitelist_authorities and set white_list in options.flags

The latter requires discussion.


This object logs the existing amount of SWAN (total and blinded). It also contains the fee pool.

Resolution: set accumulated_fees to 0 and adjust current_supply accordingly. The issuer will be compensated for the lost fees by receiving the remainder of the settlement_fund. After all the previous resolutions have been executed, the current_supply and the confidential_supply must be 0.

Additional changes

Bugfix: MPAs that have seen a black swan cannot be settled after the price feed expires

It has turned out that force-settling an MPA requires a valid price feed even when the MPA has a settlement_price set. This is clearly a bug, since in that case the settlement price is independent from the price feed. Furthermore, publishing price feeds is no longer possible after a black swan, so the time when settlement is possible at all is limited to the expiration period of the price feed of the MPA.

This needs to be fixed. See for a discussion.

New chain parameter: minimum_time_before_asset_revival

This parameter defines the minimum required time between a global settlement event on an asset and the revival of that same asset. The parameter will be modifiable by the committee and defaults to 4 weeks (28 days). See discussion below.

Dependent MPAs

If at the time of global settlement an MPA exists that is backed by the settled asset, that dependent MPA is also settled.

Additionally, it will be forbidden to create assets backed by bitAssets that have a settlement_price.

The reason for this is that after global settlement the settled asset is no longer pegged to its "real" counterpart. For example, suppose that an asset bitGOLD_USD exists that is supposed to represent the value of an amount of gold and is backed by an amount of bitUSD (which is supposed to be pegged to the US-Dollar). After bitUSD has suffered a black swan, bitUSD is no longer pegged to USD. Instead, bitUSD represents a fixed amount of BTS, defined by the settlement_price.

Supposedly, the price feed for bitGOLD_USD will continue to follow the gold price in terms of US-Dollars, which will quickly deviate from the actual worth of bitGOLD_USD, which is really defined by the BTS price at that time. This will lead to confusion and anger among market participants. It is therefore reasonable to put bitGOLD_USD into the same state of limbo as the backing USD.

This change requires further discussion.



A quick cycle of global settlement and revival is likely to cause confusion among an asset's users (holders and shorters). There is even limited potential to abuse this feature. Therefore it is reasonable to enforce a minimum time before revival, allowing users to get informed about the asset's situation and the resolution process that affects them.

Dependent Assets

As described above, assets may exist that use SWAN as collateral. Short positions in such assets must be resolved somehow. The proposed resolution 1 is quite harsh, in that it modifies the asset that uses SWAN as collateral.

It is reasonable insofar as SWAN effectively represents the value of a fixed amount of BACK, which means that an asset backed by SWAN is actually backed by BACK. The proposed resolution only makes that explicit.

There is a related comment in the source code (f1b19b1562/libraries/chain/include/graphene/chain/protocol/asset_ops.hpp (L160) ):

If this asset is used as backing for other bitassets, those bitassets will be force settled at their current price.

This is not reflected in the actual implementation AFAICS.

Better suggestions are welcome.

Flags and permissions

As described above, the revival operation will set the whitelist flag and permission of the revived asset. The purpose of this is to prevent the asset from immediately becoming active again, before the issuer has a chance to modify other asset parameters. For example, after reviving a prediction market, the owner might want to update the asset description before starting the next round of predictions.

Affected Parties


An exchange holding SWAN will have its SWAN exchanged for BACK just like anyone else. The exchange will probably have SWAN balances in its internal ledgers, which belong to the users of the exchange. The exchange MUST be notified of the settlement and it MUST modify its internal ledger, replacing SWAN balances with BACK balances.

Exchanges SHOULD perform this operation independently from the revival, i. e. before the revival is triggered. They can do this by force-settling their SWAN holdings.

(Other) Users

Users holding SWAN will have their holdings replaced with an equivalent amount of BACK, at the settlement_price. This does not damage the holder financially, see above.

Asset Owners (aka Issuers)

The issuer of an asset to be revived should know what he is doing. Invoking the revive_asset operation is a wilful act. If he isn't happy with the effect of the operation he simply should not invoke it.

Issuers of assets backed by a revived assets are affected too, but they have no choice. See discussion about Dependent Assets above.


This proposal discusses a set of changes to bring back a "stuck" asset into a usable state.

Not all shareholders need to understand the technical details of the proposal, however, they should be aware of the implications of these changes. It is particularly important to understand how the revival of an asset affects the different parties, i. e. holders, shorters, traders and issuers.

After an asset SWAN backed an asset BACK has seen global settlement, in order to revive it all existing SWAN must be destroyed and their owners must receive a share of the available collateral (BACK). In particular,

  1. At the time of the black swan, all outstanding settlement requests will be filled, and all MPAs backed by SWAN will receive a global settlement as well.
  2. At the time of revival, all open market orders concerning SWAN will be cancelled (buys and sells).
  3. Other MPAs backed by SWAN will be settled as well.
  4. Other PMs backed by SWAN will be modified so that they are backed by BACK.
  5. Vesting balances, genesis balances and account balances of SWAN will be turned into respective balances of BACK.
  6. Blinded balances of SWAN will receive special treatment so that they can be withdrawn as BACK.
  7. The SWAN fee pool will be zeroed out, and the issuer will receive the remaining BACK collateral.
  8. Finally, SWAN will be put into a state where the issuer can modify parameters and eventually open it up for general use again.