Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
314 lines (229 sloc) 20.4 KB
BSIP: 57
Title: Managed vesting balances
Authors: Fabian Schuh <>
         Stefan Schießl <>
Status: Draft
Type: Protocol
Created: 2018-10-10
Worker: ""


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
  • balance counts towards voting power


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 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.

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 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). 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 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.


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 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.


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.


  • 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 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
    // After vesting_cliff_seconds have passed, the customer can iniate to withdraw the contained 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<account_id_type>          manager;


  • 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

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
    asset_id_type   asset_id;  // this settlement can only be applied to vesting balances that hold this asset
    vector<delta>   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               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 asset of the vesting balances need to match the asset_id in their settlement, and the sum of amounts 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:

struct vesting_balance_settle_operation : public base_operation
   asset                       fee;
   account_id_type             fee_paying_account;
   vector<settlement>          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. There must be at least one settlement in settlements vector of vesting_balance_settle_operation and at least two deltas in deltas vector of each settlement.
  3. All deltas within one settlement must contain vesting balances with the same asset (asset_id)
  4. The sum of all deltas within one settlement (summing up the contained amounts) 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 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 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

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;
   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 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

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. 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 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)


  • 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!)


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 half the vesting balance create fee
  • deposit and withdrawal fee: similar to a transfer operation fee
  • settlement fee: limit_order fee * amount of contained deltas


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 (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 (increase the balance, or reduce from 40 to minimum 0, also partially)


Preferably on the pull request, or bitsharestalk:

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 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. 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.


This document is placed in the public domain.

You can’t perform that action at this time.