Distribute Asset Market Fees to Referral Program

[charyury]

User Story
As an asset owner I want an ability to share market fees with registrars and referrals so that other people can easily benefit from promoting my asset and attract more traders to it.

Example use cases

1. As a gateway operator I would like to stimulate webmasters to promote my gateway. I am able to share my gateway UIA's market fee with referrals, so that any webmaster who has Bitshares LTM account is able to refer people and benefit from the people trading the gateway assets.
2. Enabling this feature for MPAs (e.g. bitCNY or bitUSD) can provide additional bounty for registrars and referrals which can lead to more traders joining to the ecosystem.

Additional Context (optional)
This is introduced originally by Dan in BSIP 4. We suggest to extend this to UIAs as well. This setting is optional for an assets, so the owner is free to use it or not, so does Committee regarding MPAs.

CORE TEAM TASK LIST

• Draft BSIP
  • Assigned: @OpenLedgerApp
  • Estimated: 40 hours
  • Remitted: weeks 42-43
• Define Specification
• Community Voting
• Design / Develop Solution
  • Assigned: @OpenLedgerApp
  • Budgeted: 450 hours over ~8 weeks (thru end of 2018)
• Perform QA/Testing
• Update Documentation

[charyury]

We have PoC ready for this functionality. Most likely this should be converted to a BSIP, technical specification is ready as well, see below.

Specifications

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

TODO An optional whitelist (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 and referrer fee (market sharing fee) if referrer is whitelisted.
**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 modifications

Append hardfork (HARDFORK_REWARD_TIME) check. Validate additional asset options. Apply additional asset options (reward_percent, TODO: market_sharing_whitelist)

Unit tests

Add: reward_tests.cpp (asset_rewards_test, asset_claim_reward_test)

Modified: fee_tests.cpp, uia_tests.cpp

[abitmore]

Not bad. Please go ahead with a BSIP (replaces BSIP4).

• Perhaps need two reward_percent fields, one for registrar and one for referrer. Or perhaps use only one here, and honor the original registrar/referrer split percentage.
• perhaps good to have a reward_split virtual operation for referrers/registrars to track.
• asset_update_operation need to be updated, not only asset_create_operation
• if want to have white list (according to TODO), need to add/update operations as well.

Best if you have developers to help implement it.

[ryanRfox]

Great initiative @charyury

Let's discuss an estimate for drafting the BSIP. I've assigned you to this Issue. We will use this to track progress of the BSIP. However, the BSIP itself will be drafted in the /BSIPS repo, not the /bitshare-core repo.

I refined the Core Team Task List within the description. We can adjust as needed going forward.

[denissok]

Hello, here are the answers from OpenLedger's team to abit's concerns:

Not bad. Please go ahead with a BSIP (replaces BSIP4).

Perhaps need two reward_percent fields, one for registrar and one for referrer. Or perhaps use only one here, and honor the original registrar/referrer split percentage.

We propose to use market_fee_reward_percent (defined in the asset options) for the registrar and then use the original Bitshares mechanism and original reward percentage field (defined for each account during registration) to split between the registrar and referrer.

Market fee reward is accumulated on the user account. The users decide 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.

perhaps good to have a reward_split virtual operation for referrers/registrars to track.

We don't recommend to make additional operation reward_split, because it leads to a significant blockchain load increase. So, we offer to add extra attributes to fill_order_operation.

asset_update_operation need to be updated, not only asset_create_operation

We have updated our description.

if want to have white list (according to TODO), need to add/update operations as well.
Best if you have developers to help implement it.

That's a very good point! We have thought about it but did not add it to the description as it was not implemented in the prototype yet.
Whitelist is set up and updated by extending the asset_create_operation, asset_update_operation with the hardfork. Also, filter logic by whitelist is added to the pay_market_fees function. If the registrar is not in the whitelist, split_pay will not happen and the entire fee goes to Asset issuer.
We will update our description BSIP.

[denissok]

The new description will come as a BSIP proposal very soon.

[ThomasFreedman]

What are the legal implications if this proposal? Will BitShares still pass the Howie test if implemented? If this is implemented we need to make damned sure we set expectations (there is no guaranteed rate of return).

[OpenLedgerApp]

the official BSIP-43 is here:
https://github.com/bitshares/bsips/blob/master/bsip-0043.md
Please comment here :
#1268 (comment)
I will respond there.

[charyury]

What are the legal implications if this proposal? Will BitShares still pass the Howie test if implemented? If this is implemented we need to make damned sure we set expectations (there is no guaranteed rate of return).

This is not affecting BTS or any other asset in any way as the fees are being distributed to referral program (registrars and referrals), not to specific asset holders.

[oxarbitrage]

work in progress at #1419

[thul3]

Great direction but in my opinion there are some small lacks for mass adoption.
The first issue which has been proofen in the past is the LTM.Webmasters don't pay to be able to promote an offer.Thats something which will discourage majority of webmasters to promote bitshares.
The next point is to deliver massiv traffic promoters need to be able to calculate.Since it is a refferal program it means the webmaster needs to wait a long time for his full reward.He needs some kind of guarantee that the reward won't decrease after a short time when Asset owners update their shared market fee.Will the market_fee_reward_percent asset option gives the possibility that refferals which has been already sent will get a lower reward if changed ?
I also think there should be a global consenus about the market fee reward percent since why should one Asset owner take advantage of the traffic another registrar/asset owner is getting for paying a share of 50% from trading fee.
I would also like to ask if using that solution will it be possible for registrars to recruite local webmasters to promote your assets and get a cut of the market fee's earned by their recruited webmasters ?

[OpenLedgerApp]

@thul3 Thanks a lot for your valuable comments. Most of them are valid and can be encouraged as a good supplement to BSIP-43.

1. LTM - agree, we should think how to handle it.
2. Market fee reward is accumulated on the user account. Each user decides when he wants to claim the market fee reward and move it to their active balance. The current implementation doesn't guarantee something if the reward is changed by the asset owner. It can be some implementation where the reward is conducting with the specific duration for the referrals.
3. Good point. Maybe it makes sense to add some new user type for accounts which issued new assets.
4. It can be a further implementation to have some complex program with sub-levels.

In any case, the BSIP 43 was a start point of the market fees sharing. Your suggestions can be posted as separate BSIP or supplement to BSIP-43 and then discussed with the community.
Thanks again for these noticeable comments!

[oxarbitrage]

done by #1419