From d673e668a196eb105f4b489d73b2bba6770f122e Mon Sep 17 00:00:00 2001 From: OpenLedgerApp Date: Wed, 29 Aug 2018 12:35:51 +0300 Subject: [PATCH 1/4] bsip#43 Market fee sharing --- README.md | 1 + bsip-0043.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 bsip-0043.md diff --git a/README.md b/README.md index 2d23357..309680f 100644 --- a/README.md +++ b/README.md @@ -49,3 +49,4 @@ Number | Title | [39](bsip-0039.md) | Automatically approve proposals by the proposer | Fabian Schuh | Protocol | Draft [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 +[43](bsip-0043.md) | Market fee sharing | OpenLedgerApp | Protocol | Draft diff --git a/bsip-0043.md b/bsip-0043.md new file mode 100644 index 0000000..fd26906 --- /dev/null +++ b/bsip-0043.md @@ -0,0 +1,96 @@ + BSIP: 0043 + Title: Market fee sharing + Authors: OpenLedgerApp + Status: Draft + Type: Protocol + Created: 2018-08-23 + Discussion: https://github.com/bitshares/bsips/issues/102 + Worker: + + +# Abstract + +When creating a new asset, the asset issuer is the only beneficiary of the market fees in the current implementation. And the only way to affect the asset community growth is the market fee percentage. For example, one can decrease the market fee and it will result in somewhat larger number of trades with this asset. In this way the asset issuer might get a bigger profit during to increasing the trade volume with this asset. + +However, there might be another opportunity to promote the asset and stimulate the trading - use native Bitshares referral program. At this time unfortunately an assets owner is not able to share market fees with registrars and referrers to stimulate them to market the asset trading, so we suggest to add this possibility. Furthermore, enabling this feature for MPAs (e.g. bitCNY or bitUSD) can provide additional bounty for Bitshares registrars and referrals which can lead to more traders joining to the ecosystem. +The workflow may be as following: + +An asset issuer defines the market_fee_reward_percent - what percentage of the market fee he wants to share with the registrar in asset options. Registrar defines reward_percent for the referrer for each user(using the already existing BitShares mechanism). +Market fee reward is accumulated on the user account. The user decides when they want to claim the market fee reward and move it to their active balance. There is another operation created asset_claim_reward_operation. Each user pays network fee to call this operation. + +# Motivation + +To make promoting BitShares and bringing new users much more attractive to registrars and referrers by sharing UIAs and MPAs market fees with them. + +# Rationale +When 'fill_order_operation' executing at the moment of market fee calculation there will be calculate the reward for the registrar used the parameter market_fee_reward_percent. Then this market_fee_reward_percent of the market fee is split between the registrar and referrer according to the referrer_rewards_percentage, which is set up during the new account registration by registrar (please see the parameters for register_account). + +# Specifications + +## market_fee_reward_percent asset option +Percent of market fee that will be paid to buyer's registrar. Set by UIA issuer. + +## market_sharing_whitelist asset option +An optional list of accounts (configurable by the UIA Issuer) could provide increased control over who is eligible to get market rewards. + +## New database and wallet api methods +**get_account_reward(account, asset_symbol)** - Returns information about the reward amount for specific asset. +**list_account_rewards(account)** - Returns information about the reward amount in various assets +**claim_reward(account, asset_symbol, amount)** - Claim account's reward for the given asset. + +## account_reward_object +A new BitShares object type in implementation space impl_account_reward_object_type = 2.18.X that tracks the rewards of a single account/asset pair +``` +account_reward_object { +owner_account, +asset_type, +reward_amount +} +``` +## account_reward_index +A new index that stores objects of account_reward_object-type in graphene::database and allow random fast access to objects by given criteria +``` +account_reward_index multi-index of account_reward_objects +indexed_by +[id] +[owner_account, asset_type] +[asset_type, reward_amount desc, owner_account] +``` +## asset_claim_reward_operation +A new operation used to transfer reward to the account's balance. +``` +asset_claim_reward_operation { +fee +claiming_account +amount_to_claim +} +``` + +## graphene::chain::database new methods +**get_reward(owner_account, asset_id)** - Retrieve a particular account's reward in a given asset +**adjust_reward(account, delta)** - Adjust a particular account's reward in a given asset by a delta + +## graphene::chain::database modifications +**pay_market_fees(seller, recv_asset_object, receives_amount)** - Split pay to asset issuer fee, registrar fee and referrer fee. If the registrar is not in the market_sharing_whitelist, split_pay will not happen and the entire fee goes to Asset issuer. +**calculate_market_fee(trade_asset, trade_amount)** - Calculate value for previous function. +**fill_limit_order(order, pays, receives, cull_if_small, fill_price, is_maker)** - Append hardfork (HARDFORK_REWARD_TIME) check. Use old or new version of pay_market_fees() function. + +## asset_create_evaluator, asset_update_evaluator modifications +Append hardfork (HARDFORK_REWARD_TIME) check. Validate additional asset options. Apply additional asset options (market_fee_reward_percent, market_sharing_whitelist) + +## Unit tests + +Add: reward_tests.cpp (asset_rewards_test, asset_claim_reward_test) + +Modified: fee_tests.cpp, uia_tests.cpp + +# Description + +# Summary for Shareholders +The new modification - market fee sharing - will allow to bring in new clients for BitShares by making it financially lucrative for registrars and referrers. This modification is interesting mostly so asset issuers and registrars/referrers. + +# Copyright +This document is placed in the public domain. + +# See Also +https://github.com/bitshares/bitshares-core/issues/1268 \ No newline at end of file From d84c73428fba5a4c7e4bb86c49b3640097875a6c Mon Sep 17 00:00:00 2001 From: Denis Sokolov Date: Fri, 5 Oct 2018 19:00:40 +0300 Subject: [PATCH 2/4] Updated according to the discussions with community members --- bsip-0043.md | 43 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/bsip-0043.md b/bsip-0043.md index fd26906..6f32c7a 100644 --- a/bsip-0043.md +++ b/bsip-0043.md @@ -4,19 +4,31 @@ Status: Draft Type: Protocol Created: 2018-08-23 + Updated: 2018-10-05 Discussion: https://github.com/bitshares/bsips/issues/102 Worker: # Abstract -When creating a new asset, the asset issuer is the only beneficiary of the market fees in the current implementation. And the only way to affect the asset community growth is the market fee percentage. For example, one can decrease the market fee and it will result in somewhat larger number of trades with this asset. In this way the asset issuer might get a bigger profit during to increasing the trade volume with this asset. +When creating a new asset, the asset owner is the only beneficiary of the market fees in the current implementation. And one of the ways to increase the community growth is the market fee percentage. For example, one can decrease the market fee and it will result in somewhat larger number of trades with this asset. In this way the asset owner might get a bigger profit during to increasing the trade volume with this asset. However, there might be another opportunity to promote the asset and stimulate the trading - use native Bitshares referral program. At this time unfortunately an assets owner is not able to share market fees with registrars and referrers to stimulate them to market the asset trading, so we suggest to add this possibility. Furthermore, enabling this feature for MPAs (e.g. bitCNY or bitUSD) can provide additional bounty for Bitshares registrars and referrals which can lead to more traders joining to the ecosystem. -The workflow may be as following: -An asset issuer defines the market_fee_reward_percent - what percentage of the market fee he wants to share with the registrar in asset options. Registrar defines reward_percent for the referrer for each user(using the already existing BitShares mechanism). -Market fee reward is accumulated on the user account. The user decides when they want to claim the market fee reward and move it to their active balance. There is another operation created asset_claim_reward_operation. Each user pays network fee to call this operation. +The workflow may be as follows. It is copied from vesting balance mechanism and got simplified. + +An asset owner defines the **market_fee_reward_percent** in asset options - what percentage of the market fee he wants to share with the registrar. +market_fee* market_fee_reward_percent goes the registar's fee pool. +market_fee*(1 - market_fee_reward_percent) goes to the asset owner. + + +Registrar defines **reward_percent** - for the referrer for each user(using the already existing BitShares mechanism). + +Market fee reward is accumulated on the user account. + +Each user decides when they want to claim the market fee reward and move it to their active balance. +There is another operation created asset_claim_reward_operation for this. +And each user pays network fee to call this operation. # Motivation @@ -27,11 +39,21 @@ When 'fill_order_operation' executing at the moment of market fee calculation th # Specifications +##Design decisions. +There has been a discussion going on about which way to implement distribution of the market fees for referrers. +Direct transfer and using vesting balance mechanism are some of the alternatives. +In our approach there has been decided to repicate the current functionality (to use the current vesting balance mechanism). +There is also an option to simplify the current design decisions specified below. +However, it requires that the related bitshares/bitshares-core#1276 is already implemented. If #1276 is implemented before BSIP-43, than BSIP-43 can be changed to accomodate #1276 changes. + + ## market_fee_reward_percent asset option -Percent of market fee that will be paid to buyer's registrar. Set by UIA issuer. +Percent of market fee that will be paid to buyer's registrar. Set by asset owner. +if market_fee_reward_percent = 0 or absent - the old mechanism is used. Market fees are accumulated in the asset and can be claimed. ## market_sharing_whitelist asset option -An optional list of accounts (configurable by the UIA Issuer) could provide increased control over who is eligible to get market rewards. +An optional list of accounts (configurable by the asset owner) could provide increased control over who is eligible to get market rewards. +If whitelist empty or absent - there is no filtering. This means that everyone is in the whitelist by default if it is empty. ## New database and wallet api methods **get_account_reward(account, asset_symbol)** - Returns information about the reward amount for specific asset. @@ -39,7 +61,9 @@ An optional list of accounts (configurable by the UIA Issuer) could provide incr **claim_reward(account, asset_symbol, amount)** - Claim account's reward for the given asset. ## account_reward_object -A new BitShares object type in implementation space impl_account_reward_object_type = 2.18.X that tracks the rewards of a single account/asset pair +A new BitShares object type in implementation space impl_account_reward_object_type = 2.18.X that tracks the rewards of a single account/asset pair. +Usually, vesting_balance_object receives fees from all kinds of transactions. +In this case, a user can't find out how much profit is received from market fee sharing. So a new object account_reward_object is created in order to track profits from market fee sharing only. ``` account_reward_object { owner_account, @@ -58,6 +82,7 @@ indexed_by ``` ## asset_claim_reward_operation A new operation used to transfer reward to the account's balance. +The purpose of this operation is to track profits from market fee sharing. ``` asset_claim_reward_operation { fee @@ -71,7 +96,7 @@ amount_to_claim **adjust_reward(account, delta)** - Adjust a particular account's reward in a given asset by a delta ## graphene::chain::database modifications -**pay_market_fees(seller, recv_asset_object, receives_amount)** - Split pay to asset issuer fee, registrar fee and referrer fee. If the registrar is not in the market_sharing_whitelist, split_pay will not happen and the entire fee goes to Asset issuer. +**pay_market_fees(seller, recv_asset_object, receives_amount)** - Split pay to asset owner fee, registrar fee and referrer fee. If the registrar is not in the market_sharing_whitelist, split_pay will not happen and the entire fee goes to Asset owner. **calculate_market_fee(trade_asset, trade_amount)** - Calculate value for previous function. **fill_limit_order(order, pays, receives, cull_if_small, fill_price, is_maker)** - Append hardfork (HARDFORK_REWARD_TIME) check. Use old or new version of pay_market_fees() function. @@ -87,7 +112,7 @@ Modified: fee_tests.cpp, uia_tests.cpp # Description # Summary for Shareholders -The new modification - market fee sharing - will allow to bring in new clients for BitShares by making it financially lucrative for registrars and referrers. This modification is interesting mostly so asset issuers and registrars/referrers. +The new modification - market fee sharing - will allow to bring in new clients for BitShares by making it financially lucrative for registrars and referrers. This modification is interesting mostly so asset owners and registrars/referrers. # Copyright This document is placed in the public domain. From b9a2774df95c8daaf3c9830cd5b7ff133d5fed8f Mon Sep 17 00:00:00 2001 From: OpenLedgerApp Date: Fri, 19 Oct 2018 18:20:52 +0300 Subject: [PATCH 3/4] rewards issue --- bsip-0043.md | 87 +++++++++------------------------------------------- 1 file changed, 15 insertions(+), 72 deletions(-) diff --git a/bsip-0043.md b/bsip-0043.md index 6f32c7a..8c48369 100644 --- a/bsip-0043.md +++ b/bsip-0043.md @@ -4,7 +4,7 @@ Status: Draft Type: Protocol Created: 2018-08-23 - Updated: 2018-10-05 + Updated: 2018-10-19 Discussion: https://github.com/bitshares/bsips/issues/102 Worker: @@ -15,99 +15,42 @@ When creating a new asset, the asset owner is the only beneficiary of the market However, there might be another opportunity to promote the asset and stimulate the trading - use native Bitshares referral program. At this time unfortunately an assets owner is not able to share market fees with registrars and referrers to stimulate them to market the asset trading, so we suggest to add this possibility. Furthermore, enabling this feature for MPAs (e.g. bitCNY or bitUSD) can provide additional bounty for Bitshares registrars and referrals which can lead to more traders joining to the ecosystem. -The workflow may be as follows. It is copied from vesting balance mechanism and got simplified. +An asset owner defines the **market_fee_reward_percent** in asset options - what percentage of the market fee he wants to share with the registrar. +**market_fee** * **market_fee_reward_percent** goes the registar's fee pool. +**market_fee** * (1 - **market_fee_reward_percent**) goes to the asset owner. -An asset owner defines the **market_fee_reward_percent** in asset options - what percentage of the market fee he wants to share with the registrar. -market_fee* market_fee_reward_percent goes the registar's fee pool. -market_fee*(1 - market_fee_reward_percent) goes to the asset owner. +Registrar defines **reward_percent** - for the referrer for each user (using the already existing BitShares mechanism). -Registrar defines **reward_percent** - for the referrer for each user(using the already existing BitShares mechanism). +Market fee reward is accumulated on the user account. -Market fee reward is accumulated on the user account. - -Each user decides when they want to claim the market fee reward and move it to their active balance. -There is another operation created asset_claim_reward_operation for this. -And each user pays network fee to call this operation. +Each user decides when he wants to claim the market fee reward and move it to their active balance. # Motivation To make promoting BitShares and bringing new users much more attractive to registrars and referrers by sharing UIAs and MPAs market fees with them. # Rationale -When 'fill_order_operation' executing at the moment of market fee calculation there will be calculate the reward for the registrar used the parameter market_fee_reward_percent. Then this market_fee_reward_percent of the market fee is split between the registrar and referrer according to the referrer_rewards_percentage, which is set up during the new account registration by registrar (please see the parameters for register_account). +When *fill_order_operation* executing at the moment of market fee calculation there will be calculate the reward for the registrar used the parameter **market_fee_reward_percent**. Then this **market_fee_reward_percent** of the market fee is split between the registrar and referrer according to the referrer_rewards_percentage, which is set up during the new account registration by registrar (please see the parameters for *register_account*). # Specifications +Market fee rewards accumulated on special vesting balances. -##Design decisions. -There has been a discussion going on about which way to implement distribution of the market fees for referrers. -Direct transfer and using vesting balance mechanism are some of the alternatives. -In our approach there has been decided to repicate the current functionality (to use the current vesting balance mechanism). -There is also an option to simplify the current design decisions specified below. -However, it requires that the related bitshares/bitshares-core#1276 is already implemented. If #1276 is implemented before BSIP-43, than BSIP-43 can be changed to accomodate #1276 changes. - - -## market_fee_reward_percent asset option +## **market_fee_reward_percent** asset option Percent of market fee that will be paid to buyer's registrar. Set by asset owner. -if market_fee_reward_percent = 0 or absent - the old mechanism is used. Market fees are accumulated in the asset and can be claimed. +if **market_fee_reward_percent** = 0 or absent - the old mechanism is used. Market fees are accumulated in the asset and can be claimed. -## market_sharing_whitelist asset option +## **market_sharing_whitelist** asset option An optional list of accounts (configurable by the asset owner) could provide increased control over who is eligible to get market rewards. If whitelist empty or absent - there is no filtering. This means that everyone is in the whitelist by default if it is empty. -## New database and wallet api methods -**get_account_reward(account, asset_symbol)** - Returns information about the reward amount for specific asset. -**list_account_rewards(account)** - Returns information about the reward amount in various assets -**claim_reward(account, asset_symbol, amount)** - Claim account's reward for the given asset. - -## account_reward_object -A new BitShares object type in implementation space impl_account_reward_object_type = 2.18.X that tracks the rewards of a single account/asset pair. -Usually, vesting_balance_object receives fees from all kinds of transactions. -In this case, a user can't find out how much profit is received from market fee sharing. So a new object account_reward_object is created in order to track profits from market fee sharing only. -``` -account_reward_object { -owner_account, -asset_type, -reward_amount -} -``` -## account_reward_index -A new index that stores objects of account_reward_object-type in graphene::database and allow random fast access to objects by given criteria -``` -account_reward_index multi-index of account_reward_objects -indexed_by -[id] -[owner_account, asset_type] -[asset_type, reward_amount desc, owner_account] -``` -## asset_claim_reward_operation -A new operation used to transfer reward to the account's balance. -The purpose of this operation is to track profits from market fee sharing. -``` -asset_claim_reward_operation { -fee -claiming_account -amount_to_claim -} -``` - -## graphene::chain::database new methods -**get_reward(owner_account, asset_id)** - Retrieve a particular account's reward in a given asset -**adjust_reward(account, delta)** - Adjust a particular account's reward in a given asset by a delta - ## graphene::chain::database modifications -**pay_market_fees(seller, recv_asset_object, receives_amount)** - Split pay to asset owner fee, registrar fee and referrer fee. If the registrar is not in the market_sharing_whitelist, split_pay will not happen and the entire fee goes to Asset owner. +**pay_market_fees(seller, recv_asset_object, receives_amount)** - Split pay to asset owner fee, registrar fee and referrer fee. If the registrar is not in the **market_sharing_whitelist**, *split_pay* will not happen and the entire fee goes to Asset owner. **calculate_market_fee(trade_asset, trade_amount)** - Calculate value for previous function. -**fill_limit_order(order, pays, receives, cull_if_small, fill_price, is_maker)** - Append hardfork (HARDFORK_REWARD_TIME) check. Use old or new version of pay_market_fees() function. +**fill_limit_order(order, pays, receives, cull_if_small, fill_price, is_maker)** - Append hardfork (HARDFORK_REWARD_TIME) check. Use old or new version of *pay_market_fees()* function. ## asset_create_evaluator, asset_update_evaluator modifications -Append hardfork (HARDFORK_REWARD_TIME) check. Validate additional asset options. Apply additional asset options (market_fee_reward_percent, market_sharing_whitelist) - -## Unit tests - -Add: reward_tests.cpp (asset_rewards_test, asset_claim_reward_test) - -Modified: fee_tests.cpp, uia_tests.cpp +Append hardfork (HARDFORK_REWARD_TIME) check. Validate additional asset options. Apply additional asset options (**market_fee_reward_percent**, **market_sharing_whitelist**) # Description From 298a9a9ad52bc412739e77a913dc22fdfa15d642 Mon Sep 17 00:00:00 2001 From: OpenLedgerApps Date: Mon, 22 Oct 2018 10:42:36 +0300 Subject: [PATCH 4/4] updated wording --- bsip-0043.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bsip-0043.md b/bsip-0043.md index 8c48369..7c5e328 100644 --- a/bsip-0043.md +++ b/bsip-0043.md @@ -16,11 +16,11 @@ When creating a new asset, the asset owner is the only beneficiary of the market However, there might be another opportunity to promote the asset and stimulate the trading - use native Bitshares referral program. At this time unfortunately an assets owner is not able to share market fees with registrars and referrers to stimulate them to market the asset trading, so we suggest to add this possibility. Furthermore, enabling this feature for MPAs (e.g. bitCNY or bitUSD) can provide additional bounty for Bitshares registrars and referrals which can lead to more traders joining to the ecosystem. An asset owner defines the **market_fee_reward_percent** in asset options - what percentage of the market fee he wants to share with the registrar. -**market_fee** * **market_fee_reward_percent** goes the registar's fee pool. +**market_fee** * **market_fee_reward_percent** goes the registrar. **market_fee** * (1 - **market_fee_reward_percent**) goes to the asset owner. - -Registrar defines **reward_percent** - for the referrer for each user (using the already existing BitShares mechanism). +Registrar splits the reward between itself and its referrers by defining **reward_percent**, which defines referrer's percentage. +It is defined per each other using the already existing BitShares mechanism. Market fee reward is accumulated on the user account.