Percentage based transfer fee [BSIP10] implemented

[bytemaster]

Primary rules for BitShares operations include:

1. All values relevant to the display of the transaction history should be included in the operation.  Namely, the fee must be calculated in advance and explicitly included in the transaction.
2. Existing operations should not be changed if this requires adding additional fields.
3. As long as the FEE * CORE_EXCHANGE_RATE > MIN_NETWORK_FEE_IN_BTS then things should be fine.

The MIN fee is important to prevent spamming of UIAs that have no value.   

[clayop]

Great job!

Everything seems good to me but the fee distribution scheme can be debatable. Why you didn't choose the existing scheme? (20% network 80% referral) Alternatively, the minimum fee always goes to network, and if 20% of a fee exceeds lower limit, 20:80 scheme can be applied, IMO.

[abit]

Yeah.. this actually came out of discussions within the Committee regarding trading fees.

@abit is up for Vote to be on the Committee.

He has shown strong interest in getting things done and as many of you like, has the technical background as a developer.

If you haven't voted for him for committee please consider updating your votes.

He is also a Witness and currently holds the record for lowest missed blocks some how.

Thanks.

By the way I added feature briefs to OP.

[BunkerChainLabs-DataSecurityNode]

Yeah.. this actually came out of discussions within the Committee regarding trading fees.

@abit is up for Vote to be on the Committee.

He has shown strong interest in getting things done and as many of you like, has the technical background as a developer.

If you haven't voted for him for committee please consider updating your votes.

He is also a Witness and currently holds the record for lowest missed blocks some how.

[roadscape]

This is a historical moment - it's a first attempt to implement a new feature in the Graphene code-base without CNX being directly involved.
Well done @abit

Let's hope CNX will be supportive and offer some feedback regarding the quality of abit's code.
Even if they don't find BSIP10 especially useful.

The baby is learning to walk

Yes... This is excellent @abit... well done!

[jakub]

This is a historical moment - it's a first attempt to implement a new feature in the Graphene code-base without CNX being directly involved.
Well done @abit

Let's hope CNX will be supportive and offer some feedback regarding the quality of abit's code.
Even if they don't find BSIP10 especially useful.

The baby is learning to walk

[xeroc]

you will certainly need to change some code in the GUI as well .. it has an estimate_fee method somewhere ..

[abit]

Updated OP to include some examples.

[abit]

Since I just recently started a public Testnet, we can have it tested there if you wish ..

Thanks. But that's depends on you to whether deploy the code the test network.

//edit:
instead of replacing the transfer operation, could we have a flag in each asset that let's the issuer chose which pricing model to use?

It's included in the BSIP.

//Edit:
Due to lack of feedback from CNX, I don't know if it's the best way to implement BSIP10.

A simple modification on transfer_operation has been tried but failed, due to unable to re-index current live chain, it get blocked at a global_fee_change_operation or so. So I end up introduced a new operation transfer_v2_operation.
Maybe it's needed to modify GUI code to adapt the new operation, at least it's needed for CLI wallet (which I have done).

[xeroc]

Since I just recently started a public Testnet, we can have it tested there if you wish ..

//edit:
instead of replacing the transfer operation, could we have a flag in each asset that let's the issuer chose which pricing model to use?

[abit]

[DECLARATION]

The work for this implementation is not free. In order to have it applied on the live BitShares network, it needs to be funded in some way. Suggestions on how to fund it are appreciated. I ask for 10K$, or 3M BTS. Fair negotiations are acceptable.


[MAIN]

Here is the BSIP document: https://github.com/bitshares/bsips/issues/3 https://github.com/bitshares/bsips/blob/master/bsip-0010.md

Feature briefs:
1. Added 3 global parameters which can be adjusted by the committee
  * the percentage
  * a per-transfer upper limit
  * a per-transfer lower limit
2. For each asset, the issuer can choose between flat fee mode and percentage based fee mode
3. Changed fee split schema between network and referral program: if the asset is in percentage based fee mode, the network gets an amount equals to the lower limit, referral program gets the rest.
4. Fee calculation is based on "core_exchange_rate" of the asset:
    fee = min(max(amount * CER * percentage, lower_limit), upper_limit)

Here is source code: https://github.com/abitmore/bitshares-2/tree/test-transfer-fee https://github.com/abitmore/bitshares-2/tree/dev-transfer-fee

Future developments are planned. Schedule depends on funds.


[EXAMPLES]

Here listed some sample commands:

* To set an asset to charge percentage based transfer fees:

Code: [Select]

update_asset MYASSET null {"max_supply": "1000000000000000","market_fee_percent": 0,"max_market_fee": "1000000000000000","issuer_permissions": 79,"flags": 0,"core_exchange_rate": {  "base": {    "amount": 100000,    "asset_id": "1.3.0"  },  "quote": {    "amount": 10000,    "asset_id": "1.3.1"  }},"whitelist_authorities": [],"blacklist_authorities": [],"whitelist_markets": [],"blacklist_markets": [],"description": "","extensions": [[1,{"transfer_fee_mode":"asset_transfer_fee_mode_percentage_simple"}]]  } true

* To set an asset to charge flat transfer fees:

Code: [Select]

update_asset MYASSET null {"max_supply": "1000000000000000","market_fee_percent": 0,"max_market_fee": "1000000000000000","issuer_permissions": 79,"flags": 0,"core_exchange_rate": {  "base": {    "amount": 100000,    "asset_id": "1.3.0"  },  "quote": {    "amount": 10000,    "asset_id": "1.3.1"  }},"whitelist_authorities": [],"blacklist_authorities": [],"whitelist_markets": [],"blacklist_markets": [],"description": "","extensions": [[1,{"transfer_fee_mode":"asset_transfer_fee_mode_flat"}]]  } true

* To change global percentage fee parameters:

Code: [Select]

...
       ,[
          45,{
            "flat_fee": 2000000,
            "price_per_kbyte": 1000000,
            "percentage_min_fee": 600000,
            "percentage_max_fee": 30000000,
            "percentage": 100,
            "extensions": []
          }
        ]
...
Explanation of above parameters:
* 45 is for a new operation "transfer_v2_operation". The original "transfer_operation" is incompatible
* flat_fee: 2000000 means 20 BTS of transfer fee for assets which selected flat transfer fee mode
* price_per_kbyte: no explanation
* percentage_min_fee: 600000 means 6 BTS of minimum transfer fee for assets which selected percentage fee mode
* percentage_max_fee: 3000000 means 300 BTS
* percentage: 100 means 1%
* extensions: a field for future extensions, leave it empty right now


[API CHANGES]

* added a new database API: get_operation_fee, which will simply return minimum required fee for a given operation, and won't recursively calculate if the operation is a proposal (not like get_required_fees API)

* fee_schedule::set_fee() function is no longer compatible with transfer_operation, a new function set_fee_extended() is introduced. However, the new function is not designed to be used in client applications, it's recommended to use the new get_operation_fee API to get required fee, then set the fee to the operation.


[IMPACTS TO THIRD-PARTY APPLICATIONS]

If a 3rd-party application (for example apps of exchanges, bridges and etc) is monitoring activities of an account, when a transaction which contains transfer_v2_operation(id=45) arrives, it should be treated as same as transfer_operation(id=0).

(3rd-party applications should detect/handle "transfer_v2_operation" too if they detect/handle "transfer_operation".)


[KNOWN ISSUES/LIMITATIONS]
* Unable to apply percentage base fee mode to BTS


[MISC]
Due to lack of feedback from CNX, I don't know if it's the best way to implement BSIP10.
//Update:
2016-01-21 Got in touch with CNX. No much feedback so far.
2016-01-25 Add extensions to fee parameter
2016-01-26 Made some changes on asset_update_operation: new_options can now have no CER or have an empty CER, in this case CER of asset_to_update won't change. Examples:

Code: [Select]

update_asset MYASSET null {"max_supply": "1000000000000000","market_fee_percent": 0,"max_market_fee": "1000000000000000","issuer_permissions": 79,"flags": 0,"whitelist_authorities": [],"blacklist_authorities": [],"whitelist_markets": [],"blacklist_markets": [],"description": "","extensions": [[1,{"transfer_fee_mode":"asset_transfer_fee_mode_percentage_simple"}]]  } true
or
update_asset MYASSET null {"max_supply": "1000000000000000","market_fee_percent": 0,"max_market_fee": "1000000000000000","issuer_permissions": 79,"flags": 0,"core_exchange_rate":{},"whitelist_authorities": [],"blacklist_authorities": [],"whitelist_markets": [],"blacklist_markets": [],"description": "","extensions": [[1,{"transfer_fee_mode":"asset_transfer_fee_mode_percentage_simple"}]]  } true

2016-02-12 Implemented a new operation, so the committee can change some options of the core asset (BTS), including:
  * percentage market fee / market fee cap
  * transfer fee mode
Example:

Code: [Select]

add_operation_to_builder_transaction 0 [46,{"fee":{"amount":50000000,"asset_id":"1.3.0"},"new_options":{"max_supply":"100000","market_fee_percent":10,"max_market_fee":"1000000000000000","issuer_permissions":0,"flags":0,"core_exchange_rate":{},"extensions":[[1,{"transfer_fee_mode":"asset_transfer_fee_mode_percentage_simple"}]]}}]

2016-03-01
* Code is re-branched to be based on develop branch, operation_ids changed.
* Code is deeply refactored, parameter names of fee schedule changed.
* Links in this post updated.
* Added "API changes" section in this post
* Added "impacts to 3rd-party applicaitons" section in this post