From f715234dac29a63b8caf69613886e505ef8d03a9 Mon Sep 17 00:00:00 2001 From: Stefan Schiessl Date: Mon, 5 Nov 2018 16:18:12 +0100 Subject: [PATCH 01/14] add bsip 56 Signed-off-by: Stefan Schiessl --- bsip-0056.md | 265 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 bsip-0056.md diff --git a/bsip-0056.md b/bsip-0056.md new file mode 100644 index 0000000..1df93f3 --- /dev/null +++ b/bsip-0056.md @@ -0,0 +1,265 @@ + BSIP: T.B.D. + Title: Managed vesting balances + Authors: Fabian Schuh + Stefan Schießl + Status: Draft + Type: Protocol + Created: 2018-10-10 + Discussion: + Worker: (optional) + +# Abstract + +This document outlines a feature that expands the existing vesting balances. A new vesting balance policy is introduced, namely **managed vesting balances**. This new policy contructed with following key elements: +- after triggering a withdrawal to the balance, the balance owner only receives its funds after waiting a certain time period (delayed) +- allows cliff vesting (if set, a withdrawal can only happen after the specified datetime) +- contains an optional *manager*, which is allowed to access the funds and move them to other vesting balances that have the same manager and same asset +- allows the owner of the vesting balance to deposit more funds into it *after* creation + +# Motivation + +This enhancement to vesting balances allows for additional use-cases which are described below. + +## Off-chain activities + +Managed vesting balances allow to build a settlement layer on top of the BitShares blockchain which can be used by third party +services to offer additional features to BitShares users. The settlement layer tries to bridge the gap between trustless +and public smart contract-based trading and the need for privacy and ultra-low latency services. The proposal removes +the need for the 3rd party to become custodian but grants them limited power over the funds. This way, additional +services are enabled, for instance, off-chain high-frequency trading with sophisticated order types can be implemented +by centralized services with funds being transparently held on-chain. The optional cliff vesting allows promotional campaigns that enforce customer loyalty during cliff vesting period. + +Today, the field of exchanges in the crypto-currency space can be separated into centralized, and decentralized +exchanges. Centralized exchanges hold customer funds in custody and allow trading within their own (closed) platform +providing order books, order matching and fund management (deposits and withdrawals). In contrast, decentralized +exchanges put the order book and order matching into the blockchain which offers increased transparency. Additionally, +no 3rd party needs to hold customer funds in custody and traders have a more direct access to the markets being able to +place orders into the order book directly. + +Both approaches provide advantages and disadvantages. While centralized exchanges allow for high-frequency trading (HFT) +and sophisticated trading strategies (partially hidden from the order book), they come with the disadvantage of low +transparency on the order matching algorithm, potential for front-running as well as theft and hacks that may damage +many customers at the same time. + +In contrast, decentralized exchanges do not require a trusted third party to hold customer funds in custody and offer +high transparency through the audit trail of the blockchain and autonomy of order matching as part of the "smart +contracts" that execute the trading. Most blockchain technologies, however, have the disadvantage of high latency (bitcoin transaction are +processed only once every 10 minutes on average, BitShares transactions are processed every 3 seconds) and thus do not +allow for HFT. Additionally, sophisticated trading strategies cannot be applied as they require some degree of +confidentiality (e.g. the price limit of stop-loss orders). + +The concept proposed in this document tries to benefit from both worlds while offering additional features to traders. +This is done by filling the gap between centralized and decentralized exchanges. + +It is proposed to use the blockchain as settlement layer for off-chain trading platforms while removing the default risk +of the centralized trading platform. While decentralized exchanges follow the concept "the trade is the settlement", we +here propose to let trades happen outside the blockchain while settlements are performed regularly on-chain. + +## Savings Account + +Managed vesting balances furthermore allow to setup *savings accounts* (or rather *savings balances*) which are balances +that can only be accessed after a certain amount of time has elapsed (manager can be set optional). + +# Use-case off-chain activities + +We propose to extend the BitShares Blockchain in that each account is provided an additional freedom and possibilities +in configurating their vesting balances with locked up funds. + +## Exchange perspective + +### Customer sign up +When a new customer signs up with the centralized, external exchange (CEX), a BitShares account must be uniquely linked. This can be done e.g. with a signed message. + +### Customer on-boarding +The centralized, external exchange (CEX) must monitor all vesting balances that are created on the BitShares Blockchain. +If a managed vesting balance is recognized that has this CEX as settlement authority and otherwise matching +parameters (delay time period, cliff period), the asset and amount are credited to the customers account on the CEX. + +The customer has the option to either +1. sign up beforehand, link its BitShares account and let the CEX create the (possibly pre-charged) vesting balances +2. create the vesting balance itself, signup and linking can also happen afterwards + +Once a vesting balance is created, the customer can charge it with a new operation introduced in specifications. + +### Customer off-boarding +The customer iniates a withdrawal and must wait a predefined time period (delay). After this has passed, the funds +are automatically transfered to the customer's account. The CEX must monitor all vesting balances, in particular +which balances have a pending withdrawal. If a customers initiates a withdrawal of funds that are still in its vesting +balance on the BitShares Blockchain, but has already traded on the CEX, the CEX must settle those vesting balances before +the withdrawal executes, to prevent loss on the CEX side. +After a complete withdrawal the vesting balance object will exist for a while before being deleted. Effectively the customer stays a customer of the CEX (at least on chain), only with an empty balance. + +### Trading +After on-boarding the CEX knows that it can perform **settlements** of the corresponding balances and thus +can allow the customer to trade with those funds in the CEX internal markets, let's call that *trading balance* for the CEX. + +To compare this with regular centralized exchanges, withdrawals and deposits are performed against the trading balance. +An exchange platform can obtain limited control over these funds for regular settlements while the customer/trader keeps +ownership of the funds and also has limited control over them. + +Given that two parties have limited access to the funds, coordination of settlement requests and withdrawal requests +needs to provide security over the funds. The additional coordination efforts comes with transparency and security to +both, the customer as well as the 3rd-party centralized service. + +From an exchange perspective, a settlement could be seen as synchronizing the user-specific on-chain trading-balances +with the balances tracked internally. Then, trades happening at the centralized service can be bundled and balances +settled between trading balances of customers on the chain. + +A settlement would then move funds between trading balances of customers. Obviously, each user needs to be able to +create trading balances that are specific to certain exchange services and settlements can only be applied between +trading balances for that particular exchange. + +This way, the exchange would never hold the funds in custody, but would still be able to allow customers to trade. + +## Trader perspective + +A trader can freely deposit money into its exchange-specific trading-balance which can be settled/deposited in the +exchange either momentarily or after the next settlement performed by the exchange to allow trading with the additional +funds. + +However, withdrawing from the trading balance needs to be limited to ensure pending settlements can properly be executed +at their time. This means that withdrawal may require some time to pass (delay). A withdrawal is to be initiated on-chain and the customer funds are being released automatically by the blockchain after the predefined delay. +This allows the CEX to settle according to their internal database, while still enhancing the security to the +user in case of crudities. + +Furthermore consider the case that the CEX is frozen by authorities. Customers can still withdraw their funds, provided that the CEX does not grant access to the settle operation to the authorities right away. + +# Specifications + +The specifications are separated into the definition and behavioral description of a new kind of vesting balance policy, +a new operation for settling balances across multiple vesting balances as well as a delay when withdrawing and an operation to deposit funds into an existing vesting balance. + +## Managed Vesting Balance policy + +Vesting Balances are *separate* balances that can be created freely by any account on the blockchain. They come with a +predefined set of policies. Each vesting balance can only use one particular policy and only contains one +balance/asset pair. + +We here propose to add a new vesting policy: + + struct managed_policy_initializer + { + fc::time_point_sec begin_timestamp; + + // after begin_timestamp + vesting_cliff_seconds, the customer is allowed to initiate withdrawal of funds + // Must be >= 0 + uint32_t vesting_cliff_seconds = 0; + + // The delay in seconds it takes before a withdrawal transfers the funds to the owner account + // Must be >= 0 + uint32_t delay_seconds = 0; + + // An optional manager account that is allowed to perform settlements across vesting balances + optional manager; + } + +Note: + - A managed vesting balance can be created with `amount = 0`, a deposit operation will be introduced as well + - In order to avoid cluttering the in-ram state with unused vesting balances, the managed vesting balance will annul themselves after being unused for a specified time (see Annulment of vesting balances). Annullment means that the vesting balance object is removed and its funds are automatically transferred to the owner. + +## Settlement Operation + +In this step, we allow the above `manager` to re-balance assets in corresponding vesting balances. The rebalancing +takes the following form: + + struct settlement + { + vesting_balance_id_type vesting_balance; + share_type/asset delta; + } + +When settling, a vector of `settlement` is used to redefine the amounts of the corresponding vesting balances. +Obviously, the assets of the vesting balances need to match, and the sum of amounts *before* settlement needs to +equal the sum of amounts *after* settlement. Generally, the settlement operation can move all available funds in the vesting balance, independent of how much the user can currently claim due to the vesting balance policy. + +The settlement operation takes the following form: + + struct vesting_balance_settle_operation : public base_operation + { + asset fee; + account_id_type fee_paying_account; + vector settlements; + + extension< ext > extensions; + }; + +This operations overwrites the balances in the vesting balances according to the content of `settlements`. +Obviously, a few conditions need to be met: + +1. The `manager` of each vesting balances must coincide with `fee_paying_account` of the `vesting_balance_settle_operation` +2. All vesting balances need to hold the same asset (`asset_id`) +3. The sum of deltas in `settlements` must be zero (this makes the settlement operation independent of current state and allows withdrawal/deposit of funds inbetween) + +## Delayed withdrawal and cancellation operation + +To ensure safety of the funds to all parties involved, only the *owner* of the vesting balance can withdraw funds +available in the vesting balance. The `vesting_balance_withdraw_operation` receives following adjustments when applied to a managed vesting balance: +- when a proposal is done for a managed vesting balance, and `delay_seconds > 0` is true, the funds are not immediately +transferred to the owner, but will be automatically when `delay_seconds` seconds have passed + - The specified `amount` can be greater than the current possible maximum of the vesting balance. In such a case, the maximum is withdrawn instead of the specified `amount` +- The `amount` can be set to `0`, which will cancel any pending withdrawal (triggered through a former withdrawal operation and `delay_seconds > 0`) + +## Deposit Operation + +Users of the new vesting balance policy will need to be able to also deposit funds into a vesting balance. +To allow for this a new deposit operation is implemented + + struct vesting_balance_deposit_operation : public base_operation + { + asset fee; + account_id_type fee_paying_account; + vesting_balance_id_type vesting_balance; + share_type/asset deposit_amount; + + extension< ext > extensions; + }; + +Anyone can deposit into any vesting balance, as long as it is the same asset. + +## Annulment of vesting balances + +This new type of vesting balance must be able to know when it was `last used` (created, deposited, withdrawn, settled). This +timestamp is updated every time the vesting balance is used. A new committee parameter is introduced: `cleanup_unused_vesting_balances_after_seconds` (seconds). If the vesting balance was unused for longer than `cleanup_unused_vesting_balances`, it is annuled during maintenance interval. This applies only to managed vesting balances. + +Additional checks during maintenance: + - Query all unused managed vesting balances + - If it has a balance greater than 0, liquidate by forcing a withdrawal (just as if the user would manually initiate a withdrawal), no fee payment necessary. This action may or may not update the `last used` time (developers choice to what is feasible). Deletion of this object will not happen within this maintenance interval + - If the balance is 0, delete the vesting balance object, no return of any fees + +# Economy + +It is expected that many managed vesting balances are to be created to realize the connected CEX. +This requires that the creation and usage fees should be small, as a trade-off managed vesting balances annul themselves if unused to not take up RAM. + +Initial fees (proposal): + - creation fee: similar to twice a transfer operation fee + - deposit and withdrawal fee: similar to a transfer operation fee + - settlement fee: limit_order fee * amount of settled balances + +# Examples + +**Example: What amount should be allowed to be settled?** + +Assume that a user creates a vesting balance A with amount 100 on it (asset does not matter). Now he initiates +`vesting_balance_withdrawal_operation` with `amount = 60`, `delay_seconds = 100`. At this point following holds: + - the vesting balance *manager* can settle, increasing is possible, reduction from from 100 to 0 as well + - the user could refresh or cancel by sending a new `vesting_balance_withdrawal_operation` with adjusted `amount` (`=0` for cancel) + +Now 100 seconds elapses. At this point following holds: + - in the next block, the `amount = 60` is automatically transferred to vesting balance owner + - the vesting balance *manager* can settle, increasing is possible, only reduction from 40 to 0 + +# Discussion + +[to be added] + +# Summary for Voters + +The proposed approach enhances transparency and security over funds while allowing exchange businesses to offer more +sophisticated and improved trading that would otherwise not be possible in a decentralized exchange. +Effectively, the settlement authority has full control over the funds until the customer has initiated a +withdrawal and the delay period is over. Insofar, this proposal adds limited security but significant transparency. + +# Copyright + +This document is placed in the public domain. From 6353078bb2d2e53fb22f37bb22c6a7af9f2ad8bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Mon, 5 Nov 2018 16:23:26 +0100 Subject: [PATCH 02/14] add voting power --- bsip-0056.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/bsip-0056.md b/bsip-0056.md index 1df93f3..87c7d16 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -129,6 +129,9 @@ Furthermore consider the case that the CEX is frozen by authorities. Customers c The specifications are separated into the definition and behavioral description of a new kind of vesting balance policy, a new operation for settling balances across multiple vesting balances as well as a delay when withdrawing and an operation to deposit funds into an existing vesting balance. +Note: + - This new managed vesting balances explicitly counts towards voting power + ## Managed Vesting Balance policy Vesting Balances are *separate* balances that can be created freely by any account on the blockchain. They come with a From d48529e56a54379a5ee9abdb1329c55da594acc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Wed, 7 Nov 2018 13:01:26 +0100 Subject: [PATCH 03/14] add recent review --- bsip-0056.md | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/bsip-0056.md b/bsip-0056.md index 87c7d16..b0ffe17 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -75,14 +75,15 @@ The centralized, external exchange (CEX) must monitor all vesting balances that If a managed vesting balance is recognized that has this CEX as settlement authority and otherwise matching parameters (delay time period, cliff period), the asset and amount are credited to the customers account on the CEX. -The customer has the option to either -1. sign up beforehand, link its BitShares account and let the CEX create the (possibly pre-charged) vesting balances -2. create the vesting balance itself, signup and linking can also happen afterwards +The customer could have the option to either +1. have the CEX create everything (BitShares account and vesting balances), CEX must provide the customer with the private keys in a safe manner +2. create the BitShares account by itself, link it to the CEX account and let the CEX create the vesting balances +3. create the BitShares account and vesting balance itself, signup at CEX and linking of accounts can also happen afterwards Once a vesting balance is created, the customer can charge it with a new operation introduced in specifications. ### Customer off-boarding -The customer iniates a withdrawal and must wait a predefined time period (delay). After this has passed, the funds +The customer initiates a withdrawal and must wait a predefined time period (delay). After this has passed, the funds are automatically transfered to the customer's account. The CEX must monitor all vesting balances, in particular which balances have a pending withdrawal. If a customers initiates a withdrawal of funds that are still in its vesting balance on the BitShares Blockchain, but has already traded on the CEX, the CEX must settle those vesting balances before @@ -144,7 +145,7 @@ We here propose to add a new vesting policy: { fc::time_point_sec begin_timestamp; - // after begin_timestamp + vesting_cliff_seconds, the customer is allowed to initiate withdrawal of funds + // After begin_timestamp + vesting_cliff_seconds, the customer can withdraw the contained funds // Must be >= 0 uint32_t vesting_cliff_seconds = 0; @@ -157,8 +158,9 @@ We here propose to add a new vesting policy: } Note: + - Initiating a withdrawal means sending the withdraw operation to the blockchain - A managed vesting balance can be created with `amount = 0`, a deposit operation will be introduced as well - - In order to avoid cluttering the in-ram state with unused vesting balances, the managed vesting balance will annul themselves after being unused for a specified time (see Annulment of vesting balances). Annullment means that the vesting balance object is removed and its funds are automatically transferred to the owner. + - In order to avoid cluttering the in-ram state with unused vesting balances, the managed vesting balance will annul themselves after being unused for a specified time (see Annulment of vesting balances). Annullment means that the vesting balance object is removed and its funds are automatically transferred to the owner ## Settlement Operation @@ -190,8 +192,9 @@ This operations overwrites the balances in the vesting balances according to the Obviously, a few conditions need to be met: 1. The `manager` of each vesting balances must coincide with `fee_paying_account` of the `vesting_balance_settle_operation` -2. All vesting balances need to hold the same asset (`asset_id`) -3. The sum of deltas in `settlements` must be zero (this makes the settlement operation independent of current state and allows withdrawal/deposit of funds inbetween) +2. There must be at least one `settlement` in `settlements` vector of `vesting_balance_settle_operation` +3. A `settlement` can only contain non-zero `delta`s, must contain at least two `delta`s and all `delta`s in one `settlement` must target vesting balances with the same asset (`asset_id`) +4. The sum of deltas in a `settlement` must be zero (this makes the settlement operation independent of current state and allows withdrawal/deposit of funds inbetween) ## Delayed withdrawal and cancellation operation @@ -229,15 +232,22 @@ Additional checks during maintenance: - If it has a balance greater than 0, liquidate by forcing a withdrawal (just as if the user would manually initiate a withdrawal), no fee payment necessary. This action may or may not update the `last used` time (developers choice to what is feasible). Deletion of this object will not happen within this maintenance interval - If the balance is 0, delete the vesting balance object, no return of any fees +## Honoring White and Blacklisting + +Managed vesting balances must account for white- and blacklisted assets and accounts, and behave in that manner as if the asset would be held direclty by the account. + +- Vesting Balances can created if the owner could also directly hold the contained asset (black- and whitelist check) +- Vesting Balances can only be created or charged (deposit) by someone else if the owner of the vesting balance has not blacklisted the fee paying account + # Economy It is expected that many managed vesting balances are to be created to realize the connected CEX. This requires that the creation and usage fees should be small, as a trade-off managed vesting balances annul themselves if unused to not take up RAM. Initial fees (proposal): - - creation fee: similar to twice a transfer operation fee + - creation fee: similar to half the vesting balance create fee - deposit and withdrawal fee: similar to a transfer operation fee - - settlement fee: limit_order fee * amount of settled balances + - settlement fee: limit_order fee * amount of contained `deltas` # Examples @@ -261,7 +271,7 @@ Now 100 seconds elapses. At this point following holds: The proposed approach enhances transparency and security over funds while allowing exchange businesses to offer more sophisticated and improved trading that would otherwise not be possible in a decentralized exchange. Effectively, the settlement authority has full control over the funds until the customer has initiated a -withdrawal and the delay period is over. Insofar, this proposal adds limited security but significant transparency. +withdrawal and the delay period is over. Insofar, this proposal adds limited security but significant transparency, and the benefit that the user retains his voting rights for vested BTS balances. # Copyright From d67bbbd182a42c4b48f67e815576188142049c5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Wed, 7 Nov 2018 13:36:21 +0100 Subject: [PATCH 04/14] add discussion --- bsip-0056.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/bsip-0056.md b/bsip-0056.md index b0ffe17..fe325f2 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -263,8 +263,13 @@ Now 100 seconds elapses. At this point following holds: - the vesting balance *manager* can settle, increasing is possible, only reduction from 40 to 0 # Discussion +Preferably on the pull request, or bitsharestalk: +- https://github.com/bitshares/bsips/pull/119 +- https://bitsharestalk.org/index.php?topic=27361.0 -[to be added] +Also available on Steem and WhaleShares +- https://steemit.com/bitshares/@sschiessl/bsip-draft-managed-vesting-balances-plus-savings-account-discussion-20181105t152833150z-post +- https://whaleshares.io/bitshares/@sschiessl/bsip-draft-managed-vesting-balances-plus-savings-account-discussion-20181105t152833150z-post # Summary for Voters From 7ac7c5546e286eb240de1b16412c6184dce3b37d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Wed, 7 Nov 2018 15:27:26 +0100 Subject: [PATCH 05/14] added new reviews --- bsip-0056.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/bsip-0056.md b/bsip-0056.md index fe325f2..e44d685 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -143,9 +143,7 @@ We here propose to add a new vesting policy: struct managed_policy_initializer { - fc::time_point_sec begin_timestamp; - - // After begin_timestamp + vesting_cliff_seconds, the customer can withdraw the contained funds + // After vesting_cliff_seconds have passed, the customer can iniate to withdraw the contained funds // Must be >= 0 uint32_t vesting_cliff_seconds = 0; @@ -158,7 +156,8 @@ We here propose to add a new vesting policy: } Note: - - Initiating a withdrawal means sending the withdraw operation to the blockchain + + - Initiating a withdrawal means sending the withdraw operation to the blockchain (i.e. this operation can only be sent after `vesting_cliff_seconds` has passed, just like in existing logic) - A managed vesting balance can be created with `amount = 0`, a deposit operation will be introduced as well - In order to avoid cluttering the in-ram state with unused vesting balances, the managed vesting balance will annul themselves after being unused for a specified time (see Annulment of vesting balances). Annullment means that the vesting balance object is removed and its funds are automatically transferred to the owner @@ -234,10 +233,19 @@ Additional checks during maintenance: ## Honoring White and Blacklisting -Managed vesting balances must account for white- and blacklisted assets and accounts, and behave in that manner as if the asset would be held direclty by the account. +Managed vesting balances must account for white- and blacklisted assets and accounts, and behave in that manner as if the asset would be held directly by the account. + +Vesting Balances can only be created or charged (deposit) if +- the owner, the fee paying account and the manager (of present) could also directly hold the contained asset (black- and whitelist check) +- the owner of the vesting balance has not blacklisted or whitelisted the fee paying account and manager + +Vesting Balances can only be settled if +- the owner, the fee paying account and the manager (of present) could also directly hold the contained asset (black- and whitelist check) +- account blacklisting or whitelisting is not checked to disallow abuse. It is considered sufficient to check on creation + +Vesting Balances can be withdrawn from if +- the owner could also directly hold the contained asset (black- and whitelist check) -- Vesting Balances can created if the owner could also directly hold the contained asset (black- and whitelist check) -- Vesting Balances can only be created or charged (deposit) by someone else if the owner of the vesting balance has not blacklisted the fee paying account # Economy From a1a348cb1c0f1b6ace4c43cad0ba2ed8d7f55e29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Thu, 8 Nov 2018 17:31:26 +0100 Subject: [PATCH 06/14] fix settlement delta description --- bsip-0056.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/bsip-0056.md b/bsip-0056.md index e44d685..0c8b383 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -168,13 +168,19 @@ takes the following form: struct settlement { - vesting_balance_id_type vesting_balance; - share_type/asset delta; + vector deltas; // at least two, and the amounts within must sum up to zero + } + + struct delta + { + vesting_balance_id_type vesting_balance; // vesting balance is uniquely assigned to an account + share_type/asset amount; // delta amount can be positive or negative, but not zero } When settling, a vector of `settlement` is used to redefine the amounts of the corresponding vesting balances. Obviously, the assets of the vesting balances need to match, and the sum of amounts *before* settlement needs to -equal the sum of amounts *after* settlement. Generally, the settlement operation can move all available funds in the vesting balance, independent of how much the user can currently claim due to the vesting balance policy. +equal the sum of amounts *after* settlement for each asset. The settlement operation specifically allows to settle +multuple assets at once to allow for atomicity. Generally, the settlement operation can move all available funds in a vesting balance, independent of how much the user can currently claim due to the vesting balance policy. The settlement operation takes the following form: @@ -192,8 +198,9 @@ Obviously, a few conditions need to be met: 1. The `manager` of each vesting balances must coincide with `fee_paying_account` of the `vesting_balance_settle_operation` 2. There must be at least one `settlement` in `settlements` vector of `vesting_balance_settle_operation` -3. A `settlement` can only contain non-zero `delta`s, must contain at least two `delta`s and all `delta`s in one `settlement` must target vesting balances with the same asset (`asset_id`) -4. The sum of deltas in a `settlement` must be zero (this makes the settlement operation independent of current state and allows withdrawal/deposit of funds inbetween) + and at least two `delta`s in `deltas` vector of each `settlement`. Additionally, the `amount`s of all `delta`s within one `settlement` must sum to zero +3. All `delta`s within one `settlement` must contain vesting balances with the same asset (`asset_id`) +4. The sum of all `delta`s within one `settlement` (summing up the contained `amount`s) must be zero (this makes the settlement operation independent of current state and allows withdrawal/deposit of funds inbetween) ## Delayed withdrawal and cancellation operation From 5dd4dfc2c42481628d35086966cb517594161e39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Mon, 12 Nov 2018 10:16:33 +0100 Subject: [PATCH 07/14] move asset_id into settlement --- bsip-0056.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/bsip-0056.md b/bsip-0056.md index 0c8b383..0347bb5 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -168,18 +168,19 @@ takes the following form: struct settlement { + asset_id_type asset_id; // this settlement can only be applied to vesting balances that hold this asset vector deltas; // at least two, and the amounts within must sum up to zero } struct delta { vesting_balance_id_type vesting_balance; // vesting balance is uniquely assigned to an account - share_type/asset amount; // delta amount can be positive or negative, but not zero + share_type amount; // delta amount can be positive or negative, but not zero } When settling, a vector of `settlement` is used to redefine the amounts of the corresponding vesting balances. -Obviously, the assets of the vesting balances need to match, and the sum of amounts *before* settlement needs to -equal the sum of amounts *after* settlement for each asset. The settlement operation specifically allows to settle +Obviously, the asset of the vesting balances need to match the `asset_id` in their `settlement`, +and the sum of `amount`s of each `settlement` must be zero. The settlement operation specifically allows to settle multuple assets at once to allow for atomicity. Generally, the settlement operation can move all available funds in a vesting balance, independent of how much the user can currently claim due to the vesting balance policy. The settlement operation takes the following form: @@ -201,6 +202,7 @@ Obviously, a few conditions need to be met: and at least two `delta`s in `deltas` vector of each `settlement`. Additionally, the `amount`s of all `delta`s within one `settlement` must sum to zero 3. All `delta`s within one `settlement` must contain vesting balances with the same asset (`asset_id`) 4. The sum of all `delta`s within one `settlement` (summing up the contained `amount`s) must be zero (this makes the settlement operation independent of current state and allows withdrawal/deposit of funds inbetween) +5. When executing, the funds in the vesting balances are shifted according to the deltas ## Delayed withdrawal and cancellation operation @@ -221,13 +223,16 @@ To allow for this a new deposit operation is implemented asset fee; account_id_type fee_paying_account; vesting_balance_id_type vesting_balance; - share_type/asset deposit_amount; + asset deposit_amount; extension< ext > extensions; }; Anyone can deposit into any vesting balance, as long as it is the same asset. + - the `fee_paying_account` must hold `deposit_amount`, and this will be deducted from the corresponding balance + - the `owner` of the `vesting_balance` will receive `deposit_amount` + ## Annulment of vesting balances This new type of vesting balance must be able to know when it was `last used` (created, deposited, withdrawn, settled). This @@ -243,11 +248,11 @@ Additional checks during maintenance: Managed vesting balances must account for white- and blacklisted assets and accounts, and behave in that manner as if the asset would be held directly by the account. Vesting Balances can only be created or charged (deposit) if -- the owner, the fee paying account and the manager (of present) could also directly hold the contained asset (black- and whitelist check) -- the owner of the vesting balance has not blacklisted or whitelisted the fee paying account and manager +- the owner and the fee paying account could also directly hold the contained asset (black- and whitelist check) +- the owner of the vesting balance has not blacklisted (or whitelisted) the fee paying account and/or the manager Vesting Balances can only be settled if -- the owner, the fee paying account and the manager (of present) could also directly hold the contained asset (black- and whitelist check) +- the owner and the fee paying account also directly hold the contained asset (black- and whitelist check) - account blacklisting or whitelisting is not checked to disallow abuse. It is considered sufficient to check on creation Vesting Balances can be withdrawn from if From 0bf770a3b8bbd239d2f7fb7d799b96ebc71c9108 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Mon, 12 Nov 2018 15:05:26 +0100 Subject: [PATCH 08/14] honor black- and whitelist for existing vesting balance --- bsip-0056.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bsip-0056.md b/bsip-0056.md index 0347bb5..5cb8506 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -258,6 +258,8 @@ Vesting Balances can only be settled if Vesting Balances can be withdrawn from if - the owner could also directly hold the contained asset (black- and whitelist check) +Note: +- This BSIP is meant to honor the black- and whitelist for any vesting balance, independent of its policy (i.e. also the already existing vesting balances!) # Economy From 74c41bcac6e19087aec893148360bc9da5a1318f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Wed, 14 Nov 2018 22:57:40 +0100 Subject: [PATCH 09/14] adjust summary --- bsip-0056.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/bsip-0056.md b/bsip-0056.md index 5cb8506..45e5f26 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -273,7 +273,7 @@ Initial fees (proposal): # Examples -**Example: What amount should be allowed to be settled?** +## Example: What amount should be allowed to be settled?** Assume that a user creates a vesting balance A with amount 100 on it (asset does not matter). Now he initiates `vesting_balance_withdrawal_operation` with `amount = 60`, `delay_seconds = 100`. At this point following holds: @@ -295,10 +295,18 @@ Also available on Steem and WhaleShares # Summary for Voters +This BSIP introduces a new vesting balance policy, which introduces a delay on withdrawal and a manager that has limited access +to the contained funds. + +It can for example be used as a deposit into a CEX. Locking away funds on the BitShares Blockchain represents a deposit into the CEX, which allows the user to trade on the CEX, while the CEX does not need to be the custodian of the funds. The CEX settles the trades of the user onto the Blockchain every X amount of time and recognizes when the user wants to withdraw. With the built-in delay the CEX has enough time to settle the user balance on the blockchain according to internal trades. + +Other use cases are possible too, like a promotion programm within the BitShares Blockchain (lock away asset X and gain Y% every Z time period), and of course a savings account (lock away asset X, can only be accessed after waiting X days). + The proposed approach enhances transparency and security over funds while allowing exchange businesses to offer more sophisticated and improved trading that would otherwise not be possible in a decentralized exchange. Effectively, the settlement authority has full control over the funds until the customer has initiated a -withdrawal and the delay period is over. Insofar, this proposal adds limited security but significant transparency, and the benefit that the user retains his voting rights for vested BTS balances. +withdrawal and the delay period is over. Insofar, this proposal adds limited security but significant transparency, and the +benefit that the user retains his voting rights for vested BTS balances. # Copyright From c588d74d3e1d8428d24c588b08ff311f5f0e0874 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Wed, 14 Nov 2018 23:00:54 +0100 Subject: [PATCH 10/14] Update bsip-0056.md --- bsip-0056.md | 1 + 1 file changed, 1 insertion(+) diff --git a/bsip-0056.md b/bsip-0056.md index 45e5f26..2c67069 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -15,6 +15,7 @@ This document outlines a feature that expands the existing vesting balances. A n - allows cliff vesting (if set, a withdrawal can only happen after the specified datetime) - contains an optional *manager*, which is allowed to access the funds and move them to other vesting balances that have the same manager and same asset - allows the owner of the vesting balance to deposit more funds into it *after* creation +- balance counts towards voting power # Motivation From f8b906c6302c32811f1389cecf22d9136e832f8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Wed, 5 Dec 2018 21:57:56 +0100 Subject: [PATCH 11/14] update according to Michel's comments --- bsip-0056.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/bsip-0056.md b/bsip-0056.md index 2c67069..5ab2460 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -72,7 +72,7 @@ in configurating their vesting balances with locked up funds. When a new customer signs up with the centralized, external exchange (CEX), a BitShares account must be uniquely linked. This can be done e.g. with a signed message. ### Customer on-boarding -The centralized, external exchange (CEX) must monitor all vesting balances that are created on the BitShares Blockchain. +The centralized, external exchange (CEX) must monitor all vesting balances that have themselves as the manager that are created on the BitShares Blockchain. If a managed vesting balance is recognized that has this CEX as settlement authority and otherwise matching parameters (delay time period, cliff period), the asset and amount are credited to the customers account on the CEX. @@ -81,10 +81,10 @@ The customer could have the option to either 2. create the BitShares account by itself, link it to the CEX account and let the CEX create the vesting balances 3. create the BitShares account and vesting balance itself, signup at CEX and linking of accounts can also happen afterwards -Once a vesting balance is created, the customer can charge it with a new operation introduced in specifications. +Once a vesting balance is created, the customer can charge it with a new operation introduced in the specifications. We use the wording deposit, and mean the process by the customer to move funds from the normal balance of its BitShares account into the target vesting balance of the same BitShares account. ### Customer off-boarding -The customer initiates a withdrawal and must wait a predefined time period (delay). After this has passed, the funds +The customer initiates a withdrawal and must wait a predefined time period (delay). Here, withdrawal menas the process of moving funds from a vesting balance of the customers BitShares account into the normal balance of the same BitShares account. After this has passed, the funds are automatically transfered to the customer's account. The CEX must monitor all vesting balances, in particular which balances have a pending withdrawal. If a customers initiates a withdrawal of funds that are still in its vesting balance on the BitShares Blockchain, but has already traded on the CEX, the CEX must settle those vesting balances before @@ -122,7 +122,7 @@ funds. However, withdrawing from the trading balance needs to be limited to ensure pending settlements can properly be executed at their time. This means that withdrawal may require some time to pass (delay). A withdrawal is to be initiated on-chain and the customer funds are being released automatically by the blockchain after the predefined delay. This allows the CEX to settle according to their internal database, while still enhancing the security to the -user in case of crudities. +user in case of inconsistencies. Furthermore consider the case that the CEX is frozen by authorities. Customers can still withdraw their funds, provided that the CEX does not grant access to the settle operation to the authorities right away. @@ -137,7 +137,7 @@ Note: ## Managed Vesting Balance policy Vesting Balances are *separate* balances that can be created freely by any account on the blockchain. They come with a -predefined set of policies. Each vesting balance can only use one particular policy and only contains one +predefined set of policies. Each vesting balance can only use one particular policy and **only contains one** balance/asset pair. We here propose to add a new vesting policy: @@ -200,18 +200,18 @@ Obviously, a few conditions need to be met: 1. The `manager` of each vesting balances must coincide with `fee_paying_account` of the `vesting_balance_settle_operation` 2. There must be at least one `settlement` in `settlements` vector of `vesting_balance_settle_operation` - and at least two `delta`s in `deltas` vector of each `settlement`. Additionally, the `amount`s of all `delta`s within one `settlement` must sum to zero + and at least two `delta`s in `deltas` vector of each `settlement`. 3. All `delta`s within one `settlement` must contain vesting balances with the same asset (`asset_id`) 4. The sum of all `delta`s within one `settlement` (summing up the contained `amount`s) must be zero (this makes the settlement operation independent of current state and allows withdrawal/deposit of funds inbetween) -5. When executing, the funds in the vesting balances are shifted according to the deltas +5. When executing, the funds in the vesting balances are shifted according to the deltas while negative balance is not allowed ## Delayed withdrawal and cancellation operation To ensure safety of the funds to all parties involved, only the *owner* of the vesting balance can withdraw funds available in the vesting balance. The `vesting_balance_withdraw_operation` receives following adjustments when applied to a managed vesting balance: -- when a proposal is done for a managed vesting balance, and `delay_seconds > 0` is true, the funds are not immediately -transferred to the owner, but will be automatically when `delay_seconds` seconds have passed - - The specified `amount` can be greater than the current possible maximum of the vesting balance. In such a case, the maximum is withdrawn instead of the specified `amount` +- when a withdrawal is done for a managed vesting balance, and `delay_seconds > 0` is true, the funds are not immediately +transferred to the owner, but will be automatically when `delay_seconds` seconds have passed (next possible block) +- The specified `amount` can be greater than the current possible maximum of the vesting balance. In such a case, the maximum is withdrawn instead of the specified `amount` - The `amount` can be set to `0`, which will cancel any pending withdrawal (triggered through a former withdrawal operation and `delay_seconds > 0`) ## Deposit Operation @@ -246,14 +246,14 @@ Additional checks during maintenance: ## Honoring White and Blacklisting -Managed vesting balances must account for white- and blacklisted assets and accounts, and behave in that manner as if the asset would be held directly by the account. +Managed vesting balances must account for white- and blacklisted assets and accounts, and behave in that manner as if the asset would be held directly by the account. Owner in the following text refers to the BitShares account that contains the managed vesting balance. Vesting Balances can only be created or charged (deposit) if - the owner and the fee paying account could also directly hold the contained asset (black- and whitelist check) - the owner of the vesting balance has not blacklisted (or whitelisted) the fee paying account and/or the manager Vesting Balances can only be settled if -- the owner and the fee paying account also directly hold the contained asset (black- and whitelist check) +- the owner and the fee paying account could also directly hold the contained asset (black- and whitelist check) - account blacklisting or whitelisting is not checked to disallow abuse. It is considered sufficient to check on creation Vesting Balances can be withdrawn from if @@ -278,12 +278,12 @@ Initial fees (proposal): Assume that a user creates a vesting balance A with amount 100 on it (asset does not matter). Now he initiates `vesting_balance_withdrawal_operation` with `amount = 60`, `delay_seconds = 100`. At this point following holds: - - the vesting balance *manager* can settle, increasing is possible, reduction from from 100 to 0 as well + - the vesting balance *manager* can settle (increase the balance, or reduce it from 100 to minimum 0, also partially) - the user could refresh or cancel by sending a new `vesting_balance_withdrawal_operation` with adjusted `amount` (`=0` for cancel) Now 100 seconds elapses. At this point following holds: - in the next block, the `amount = 60` is automatically transferred to vesting balance owner - - the vesting balance *manager* can settle, increasing is possible, only reduction from 40 to 0 + - the vesting balance *manager* can settle (increase the balance, or reduce from 40 to minimum 0, also partially) # Discussion Preferably on the pull request, or bitsharestalk: @@ -301,7 +301,7 @@ to the contained funds. It can for example be used as a deposit into a CEX. Locking away funds on the BitShares Blockchain represents a deposit into the CEX, which allows the user to trade on the CEX, while the CEX does not need to be the custodian of the funds. The CEX settles the trades of the user onto the Blockchain every X amount of time and recognizes when the user wants to withdraw. With the built-in delay the CEX has enough time to settle the user balance on the blockchain according to internal trades. -Other use cases are possible too, like a promotion programm within the BitShares Blockchain (lock away asset X and gain Y% every Z time period), and of course a savings account (lock away asset X, can only be accessed after waiting X days). +Other use cases are possible too, like a promotion program within the BitShares Blockchain (lock away asset X and gain Y% every Z time period), and of course a savings account (lock away asset X, can only be accessed after waiting X days). The proposed approach enhances transparency and security over funds while allowing exchange businesses to offer more sophisticated and improved trading that would otherwise not be possible in a decentralized exchange. From 1e9ad3279a3f376215d18f22838481027d3bdf16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Fri, 4 Jan 2019 08:25:27 +0100 Subject: [PATCH 12/14] update numbers --- bsip-0056.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bsip-0056.md b/bsip-0056.md index 5ab2460..ccd4cb6 100644 --- a/bsip-0056.md +++ b/bsip-0056.md @@ -1,12 +1,12 @@ - BSIP: T.B.D. + BSIP: 57 Title: Managed vesting balances Authors: Fabian Schuh Stefan Schießl Status: Draft Type: Protocol Created: 2018-10-10 - Discussion: - Worker: (optional) + Discussion: https://github.com/bitshares/bsips/issues/136 + Worker: "" # Abstract From 3407fea6e41905f1deb4aa552626b079f044326f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Fri, 4 Jan 2019 08:32:02 +0100 Subject: [PATCH 13/14] add to readme --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ae07c73..7f32637 100644 --- a/README.md +++ b/README.md @@ -50,4 +50,5 @@ Number | Title | [40](bsip-0040.md) | Custom active permission | Stefan Schießl | Protocol | Draft [42](bsip-0042.md) | Adjust price feed to influence trading price of SmartCoins | Abit More | Protocol | Draft [44](bsip-0044.md) | Hashed Time-Locked Contract | Ryan R. Fox | Protocol | Draft -[45](bsip-0045.md) | Introduce 'allow use as bitasset backing collateral' flag/permission to assets | Customminer | Protocol | Draft \ No newline at end of file +[45](bsip-0045.md) | Introduce 'allow use as bitasset backing collateral' flag/permission to assets | Customminer | Protocol | Draft +[57](bsip-0057.md) | Managed Vesting Balances | Blockchain Projects BV | Protocol | Draft From dea23b69953e8ba85f97585f9a89e1d740d1010e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Schie=C3=9Fl?= Date: Fri, 4 Jan 2019 08:34:05 +0100 Subject: [PATCH 14/14] Rename bsip-0056.md to bsip-0057.md --- bsip-0056.md => bsip-0057.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename bsip-0056.md => bsip-0057.md (100%) diff --git a/bsip-0056.md b/bsip-0057.md similarity index 100% rename from bsip-0056.md rename to bsip-0057.md