Bsip 0018 (#26)

* Replaced auto-revive empty with auto-recollateralize, auto-revive empty is handled in bsip-0017a
* Detailed description of bid mechanism
* Modified some details for clarity

bsip-0018.md

@@ -1,6 +1,6 @@
     BSIP: 00018
     Title: Revive BitAsset through buying Settlement Pool
-    Authors: Fabian Schuh
+    Authors: Fabian Schuh, Peter Conrad
     Status: Draft
     Type: Protocol
     Created: 2017-06-05
@@ -43,29 +43,30 @@ position is lower than the fees required to get rid of it.
 
 # Rationale
 
-When a market-pegged assets undergoes a global settlement, one of the crucial
+When a market-pegged asset undergoes a global settlement, one of the crucial
 mechanisms that support the peg (namely "margin calls") is no longer available.
 However, other mechanisms, such as the "face-value", trading and settlement
-still exist and, unless the valuation of BTS decreases significantly, the
+still exist and, unless the valuation of the underlying asset decreases
-outstanding debt (the BitAsset long positions) are still collateralized by
+significantly, the outstanding debt (the BitAsset long positions) are still
-approximately 100% through the settlement pool at the fixed settlement price.
+collateralized through the settlement pool at the fixed settlement price. It is
+even possible that the value of the collateral exceeds the nominal value of the
+MPA significantly.
 
-This means, if a global settlement event happened on USD at a price of 1
+For example, if a global settlement event happened on USD at a price of 1
 bitUSD/BTS, then an outstanding debt of 1000 bitUSD would be backed by
-1000 BTS in the settlement pool of the bitUSD asset and no other call
+1000 BTS in the settlement pool of the bitUSD asset. No other call positions
-positions would be open by anyone else. Every bitUSD long position
+would be open by anyone else. Every bitUSD long position could, in this case,
-could, in this case, claim BTS from the settlement pool at a rate of
+claim BTS from the settlement pool at a rate of 1:1.
-1:1.
 
 # Proposal
 
 All that is needed for the asset to be *revived* is:
 
-* empty the settlement pool
 * re-enable price feeds
+* replace the settlement pool with sufficiently collateralized call positions.
 
 Since after a global settlement, the collateral for the outstanding long
-positions are stored in the settlement pool, we here propose to **obtain
+positions are stored in the settlement pool, we here propose a way to **obtain
 the funds in the settlement pool and its outstanding debt from the
 network**. Since the collateral ratio of the settlement pool after a
 global settlement is 100%, obtaining the settlement funds in order to
@@ -75,6 +76,9 @@ global settlement or margin call right away.
 
 # Specifications
 
+Like in BSIP-0017, let SWAN be an asset that has seen global settlement, and
+let BACK be the asset backing SWAN.
+
 ## Bugfix: MPAs that have seen a global settlement cannot be settled after the price feed expires
 
 It has turned out that force-settling an MPA requires a valid price feed
@@ -88,104 +92,159 @@ This bug will be fixed. See
 https://github.com/cryptonomex/graphene/issues/664#issuecomment-254056746
 for a discussion.
 
-## Auto-revive empty bitassets
+(This fix is also part of BSIP-0017. Obviously, it needs to be fixed only once.
+ It is repeated here because it is currently unclear which of these proposals
+ will be implemented.)
 
-A bitasset is "empty" if nobody is holding a positive amount of it
+## Auto-revive after increase of settlement fund value
-anymore. The only reasonable exception to this rule is the pool of
-accumulated fees belonging to the asset itself. This situation can occur
-after all holders of a globally settled asset have settled their
-position via forced settlement.
-
-The emptiness of a bitasset can easily be determined. When the BitAsset is
-empty, the remainder of the settlement fund will be paid out to the
-issuer, the accumulated fees and the current supply are reset to zero,
-and the settlement price is cleared.
-
-## `bid_settlement_funds_operation`
 
 This applies only to SmartCoins, not to Prediction Markets.
 
+A price increase of BACK can lead to the situation where SWAN is worth much more
+than it was originally intended to be. I. e. the value of the settlement fund
+becomes much greater than the nominal value of the existing supply of SWAN.
+
+When the value of the settlement fund reaches the minimum required collateral
+(in terms of price feed and MCR), a call_order_object owned by the issuer of
+SWAN is created (or updated) that takes the settlement_fund as collateral and
+covers the full debt. The settlement_fund and the settlement_price will then
+be cleared, which revives the asset.
+
+The condition can easily be checked at the time the price feed is updated.
+Obviously, this requires a price feed. Currently it is not possible to
+publish a price feed for assets that have seen global settlement. This
+restriction will be removed.
+
+## Recollateralize
+
+This applies only to SmartCoins, not to Prediction Markets.
+
+### Overview
+
 The idea of turning the settlement fund into a short position when its
 value has increased sufficiently can easily be extended. If the value of
-the settlement fund itself is not sufficient to create a sufficiently
+the settlement fund itself is too low to create a sufficiently collateralized
-collateralized short position (in terms of price feed and MCR), an
+short position (in terms of price feed and MCR), investors could volunteer to
-investor could volunteer to add the required amount of collateral to the
+add the required amount of collateral to the fund and take ownership of the
-fund and take ownership of the resulting short position
+resulting short position (collateral+debt).
-(collateral+debt).
 
-This operation is all that is needed empty the settlement pool and re-enable price feeds.
+The proposed operation enables potential investors to "bid" additional
-It has the following payload:
+collateral for taking over part of the debt (or all of it). When enough bids
+have been made to cover the full outstanding debt, and all of them are
+sufficiently collateralized (in terms of price feed and MCR), the
+settlement_fund and the bids are turned into call positions. Finally, the
+settlement_price is removed from the asset, which revives it.
+
+If the available bids cover more than the outstanding debt, bids with a higher
+collateral/debt ratio are preferred over those with a lower ratio. The intent is
+to turn the competition among investors into better collateralized calls, which
+is in the interest of the MPA holders.
+
+### `bid_collateral_operation`
+
+The operation has the following payload:
 
 * `fee`(asset_type): The operation requires a fee to be paid
- * `symbol` (asset_id_typ): Symbol that has a settlement fund to be claimed.
+* `bidder`(account_type): This account pays the additional collateral and
- * `account` (account_type): This account obtains the collateral **as well** as
+  will become the owner of the resulting call position, if the bid is accepted
-   the debt (i.e. call position) and has to either pay additional collateral,
+* `additional_collateral`(asset_type): Collateral paid by the account in order
-   provide shares of the BitAsset to reduce the outstanding debt, or a combination
+  to support the call position
-   of both.
+* `debt_covered`(asset_type): The amount of debt the account is willing to cover
- * `additional_collateral` (asset_type): Collateral paid by the account in
-   order to support the call position
- * `obtain_settlement_funds` (asset_type): The amount of settlement funds the
-   account is willing to obtain
 
 The operation works as follows:
  
 1. It pays a fee
- 2. It reduces the account's balance by `debt`.
+2. If account has already placed a bid on the same MPA, the existing bid is
-    The debt is used to reduce the outstanding shares of the globally settled BitAsset.
+   cancelled (see below).
- 3. It reduces the account's balance by `collateral`.
+3. If `debt_covered` equals 0, no further action is taken.
-    The collateral is used to initially support the accounts' call position.
+4. It reduces the account's balance by `additional_collateral`.
-    However, technically, only little additional collateral is required (if the
+5. It creates a `collateral_bid_object` containing the `bidder` and the partial
-    valuation of the collateral hasn't change since the global
+   inverted swan price calculated as `additional_collateral` / `debt_covered`.
-    settlement) if the owner accepts a margin call.
- 4. The global settlement flag is removed from the asset.          
- 5. The asset is re-enabled such that price feeds can be produced again.
- 6. After sufficient price feeds, the asset can be borrowed again.
 
-The required checks for the operation are:
+The required validity checks for the operation are:
 
- * Has the asset globally settled?
+* `debt` == 0 || `debt` > 0 && `collateral` > 0
- * Are funds in the settlement pool?
- * `debt` > 0 or `collateral` > 0
- * `obtain_settlement_funds` <= `settlement_pool`
- * the account has sufficient balance to cover `additional_collateral`
 
-If the checks are successful, a `call_order_object` belonging to the
+The required evalutation checks for the operation are:
-investor will be created or updated as described above. Then, the
-settlement price and `settlement_fund` will be cleared.
 
-The fee for this operation will be paid by the investor/recoverer. The
+* debt_covered.asset must be a bitasset (not a PM) with a settlement_price
-fee is equal to the fee of the `call_order_update` operation.
+* additional_collateral.asset must be the asset backing SWAN
+* account must have sufficient BACK, i. e. at least additional_collateral
+
+Obviously, the operation must be authorized by `bidder`.
+
+### `collateral_bid_object`
+
+The `collateral_bid_object` stores information about bids offered by accounts
+using the `bid_collateral_operation`. It is indexed
+
+1. by_id
+2. by debt asset and bidder
+3. by debt asset and partial inverted swan price.
+
+When a `collateral_bid_object` is cancelled, the additional_collateral (i. e.
+the partial inverted swan price's base) is returned to the bidder and the
+`collateral_bid_object` is deleted.
+
+The intent of the partial inverted swan price is to facilitate selection of the
+bids that will result in the call_order_objects with the lowest debt/collateral
+ratio after the revival of the bitasset.
+
+### Maintenance
+
+In every maintenance interval, all MPAs that have a settlement_price are checked
+if
+
+* they have a valid price feed, and
+* if enough sufficiently collateralized bids are available to cover the debt.
+
+If both conditions are met, for each `collateral_bid_object` (in order of
+descending partial inverted swan price) a new call_order_object will be
+constructed in this way, starting with remaining_debt=SWAN.current_supply:
+
+* call.borrower = bid.bidder
+* call.debt = bid.debt.amount
+* call.collateral = call.debt * SWAN.settlement_price + bid.additional_collateral.amount
+* remaining_debt -= call.debt
+* SWAN.settlement_fund -= call.debt * SWAN.settlement_price
+
+If remaining_debt reaches 0, any remaining bids will be cancelled.
+It is likely that for the last converted bid the requested debt will be less
+than the remaining_debt. In that case, call.debt will be set to remaining_debt
+and call.collateral will be set to asset.settlement_fund + additional_collateral.
+
+### `execute_bid_operation`
+
+In order to make the revival event visible in the bid owners' account histories,
+a new virtual `execute_bid_operation` will be introduced, that contains these
+parameters:
+
+* the `bidder`
+* the actual covered `debt`
+* the total `collateral` of the resulting call_order
+
+The semantics of that operation includes the removal of the existing bid and
+the creation of the new call_order as described above.
 
 # Discussion
 
-## Sufficient Collateral
-
-Given that at the time of claiming the settlement funds, the blockchain
-cannot know the valuation of the collateral, the user needs to ensure
-that sufficient collateral is provided to support the call position
-**after** the price feeds are refreshed. Otherwise, the asset will
-either experience another global settlement event right away, or the
-call position will be margin called.  In any way, it is up to the user
-of the above operation to take that risk.
-
 ## Partially Obtaining Settlement Funds
 
-In the case a widely used BitAsset is globally settled, the costs of providing
+In the case a widely used BitAsset is globally settled, the cost of providing
-the collateral can be shared among multiple participants by means of only
+sufficient collateral and the associated risk may be prohibitively high. The
-obtaining a fraction of the settlement pool.
+proposed bidding mechanism allows to split the cost (and the risk) among
+multiple participants.
 
 ## BitAssets using BitAssets as collateral are unaffected
 
-One huge advantage of this approach is BitAssets that are collateralized
+One huge advantage of this approach over BSIP-0017 is that BitAssets which are
-by other BitAssets are not directly affected by this proposal. Even
+collateralized by other BitAssets are not directly affected by this proposal.
-though the *economical debt* of such asset may be argued about if the
+Even though the *economical debt* of such asset may be argued about if the
 collateral asset experienced a global settlement, the *technical debt*
 is unaffected. Converting the settlement pool into a regular call
 position through this proposal would not only restore the original
 BitAsset, but also reset the collateral of the derived BitAsset.
 
-## Committee funded BitAsset Recovery
-
 ## Cost vs. Profit
 
 This operation opens an interesting cost vs. profit trade-off for those willing