Service Provider Rewards and Promotions

[michaeldjeffrey]

Service Provider Promotion Rewards

HIP-114, Pre-req PR, Proto PR

Where do Funds come from?

Service Providers update their incentive_escrow_fund_bps on Solana. The promotion_fund workspace is configured to check Solana for updates to Service Provider Accounts, and output new reports to S3 when values change.

bps stands for Basis Points. They represent a percentage to 2 decimal places 00.00%. A bps of 500 is equal to 5%. 10,000 equals 100%.

mobile-verifier watches that file and saves it's values to it's db. This means rewards can be run without needing to talk to Solana. S3 acts as the history of values for Service Providers, and mobile-verifier hangs on to the latest value.

A promotions subcommand has been added to mobile-verifier.

Calculating with percentages

Now that Service Providers can set aside a percentage of their rewards for promotions, it becomes easier to think of calculating rewards in only percentages. There are 5 percentages we track.

1. dc_perc :: Service Provider DC percentage of total rewards pool

This percentage is derived from the amount of DC transfer a Service Provider facilitated during the reward period.

2. allocated_promo_perc :: Percentage the Service Provider has set aside for promotions

This is the percentage representation of incentive_escrow_fund_bps.

3. realized_promo_perc :: Promotions as a percentage of total rewards pool

To get this percentage we take the allocated_promo_perc of dc_perc. If a Service Provider has 60% of the total rewards pool and has set aside 20% of their rewards for promotions 60% x 20% = 12%, that Service Provider's promotion rewards represent 12% of the total rewards pool.

In he case where a Service Provider has no promotions to give out, this percentage will be 0%.

4. realized_dc_perc :: Service Provider rewards as a percentage of total rewards pool

This percentage is dc_perc - realized_promo_perc. It is the subset of the total rewards pool that is going to the Service Provider. Continuing the example from above, 60% - 12% = 48%, that Service Provider's rewards represent 48% of the total rewards pool.

In the case where a Service Provider has no rewards this percentage will be equal to dc_perc.

5. matched_promo_perc :: Matched promotion from Unallocated as a percentage of total rewards pool

This percentage is the amount of the total rewards pool going towards matching a Service Provider's promotions. This value is extrapolated in the next section.

How does matching work?

Thus far, the unallocated service provider rewards can be found by removing all service provider's dc_perc from 100%. Continuing the above example with a single service provider, there is 40% of the rewards pool unallocated and available for matching promotion rewards.

Matched rewards can never exceed the amount a service provider has allocated for promotions. And matched rewards can never go towards anything other than promotions.

If a Service Provider has no promotions for the reward period, they are not considered in any of the matching situations.

Unallocated % is greater than all promotions

If you take take the sum of all Service Provider's realized_promo_perc, and it is less than the remaining unallocated rewards, each service provider receives an equal amount of matched rewards. realized_promo_perc == matched_promo_perc.

With the ongoing example, 12% would be used to match the 12% promotion rewards from the Service Provider, and the remaining unallocated amount would be 28%. Remember all these percentages are relative to the total rewards pool.

Unallocated % is less than all promotions

In this situation, the unallocated rewards are distributed amongst the service providers in portions relative to their dc_perc.

Let's have an example where Total Rewards Allocation: 100,000

	DC Tranfser	Promotion Allocation	% of total rewards	% of DC transfer
Service Provider 1	80,000	50%	80%	88%
Service Provider 2	10,000	50%	10%	12%

The realized promotion percentage for both Service Providers is 45%. (50% of 80%) + (50% of 10%).

To dive up the remaining 10% of rewards, we split on the % of DC Transfer.

Service Provider 1: 88% of 10% = 8.8%
Service Provider 2: 12% of 10% = 1.2%

Now, 100% of the total service provider rewards should be accounted for.

	dc_perc	allocated_promo_perc	realized_promo_perc	realized_dc_perc	matched_promo_perc
Service Provider 1	80%	50%	40%	40%	8.8%
Service Provider 2	10%	50%	5%	5%	1.2%

40% + 40% + 8.8% + 5% + 5% + 1.2% = 100%

Distributing Promotions

Service Providers submit promotion rewards by assigning a number of shares to the recipient (Entity in code). To distribute the rewards, we do a familiar calculation where we find the rewards_per_share by doing total_shares / total_rewards, then each recipient is given their shares * rewards_per_share.

total_rewards in this case is a Service Proviers (realized_promo_perc + matched_promo_perc) * total_rewards_pool.

Rounding

Generally, when dealing with reward calculations that result in fractional values, oralces always down. This is to prevent any chance of over allocation. In dealing with very large numbers and the way computers do math, we may not always end up with nice round numbers.

There are a couple tests where the math in any online calculator will come out to an even 60,000. The DC Transfer in the test represent some 0.00000073% of rewards above 8 trillion. The resulting multiplication when using percentages comes out to 5,999.9999999976 (estimation). This gets rounded down, and the missing reward is moved to the unallocated pool.

Errors like this are reduced when dealing with larger allocations of the total rewards pool.

Something like Bankers rounding wouldn't necessarily alleviate this problem, because we have no reason to think that promotion values will be randomly distributed. Assuming promotion shares could all be the same for a reward period, they would all round in the same direction, and if that direction is up, we could end up allocating more rewards than what exists.

So we remain safe and round down.