Referral Solidity is a library for quick building multiple levels referral mechanisms in your dapps.
The current version supports:

• pay native token (ETH, TT...)
• multiple levels referral (3 as Max now)
• pay referral bonus based referee amount
• only active user get referral bonus
• pay instantly when downline joins

There is tutorial and example at here.

npm install @thundercore/referral-solidity

To write your custom contracts, import ours lib and extend them through inheritance. Initialize your referral contract by passing the following parameters: decimals, referralBonus, secondsUntilInactive, onlyRewardActiveReferrers, levelRate, refereeBonusRateMap. See the API part to know more detail. Then, use addReferrer and payReferral to binding uplines and trigger referral payment.

pragma solidity ^0.5.0;
import '@thundercore/referral-solidity/contracts/Referral.sol';

contracts YourGame is Referral {
  // Referral(decimals, referralBonus, secondsUntilInactive, onlyRewardActiveReferrers, levelRate, refereeBonusRateMap)
  constructor() Referral (10000, 500, 1 days, true, [6000, 3000, 1000], [1, 10000]) public {
  }

  // bind uplineAddr as msg.sender's referrer
  function addUpline(address payable uplineAddr) public {
    addReferrer(upline);
  }

  // trigger pay referral in your business logic
  function play() public payable {
    payReferral(msg.value);
  }
}

The referral bonus formula is:

For the specific example, you can see the example.

Base decimals for all rate calculation in referral. For example, if decimals equals to 10000, and referralBonus is 500, that means referral bonus rate is 5%.

The total referral bonus rate, which will divide by decimals. For example, If you will like to set as 5%, it can set as 50 when decimals is 1000.

The seconds that how long a user will be inactive. For example, one days.

The flag to enable whether paying to inactive uplines.

The bonus rate for each level, which will divide by decimals too. The max level depth is 3. For example, set levelRate as [6000, 3000, 1000] when decimals is 10000 for the following case:

The bonus rate mapping to each referree amount, which will divide by decimals too. The max depth is 3. The map should be pass as [ <lower amount>, <rate>, ... ]. For example, you should pass [1, 2500, 5, 5000, 10, 10000] when decimals is 10000 for the following case:

Add an address as msg.sender's referrer. When add referrer failed, it won't revert the transaction but emit RegisteredRefererFailed events and return false.

Calculate and pay referral to all of uplines instantly. The return is total tokens paid to uplines.

Check whether an address has the referrer

Update an user's active time.

Update secondsUntilInactive after deployed.

Update onlyRewardActiveReferrers after deployed.

Emitted when referee add referrer as upline.

Emitted when referee add referrer as upline failed.

Emitted when from trigger pay referral amount to to, which is level level referrer.

Emitted when updated user active time as timestamp.

The mapping of all address information.

struct Account {
  address payable referrer; 
  uint reward; // total reward the user got
  uint referredCount; // total amount that the user referred
  uint lastActiveTimestamp; // last active time
}

Consider that we pass the following parameter to referral contract:

So the rates are

3%

Ther referral relationship is A <- B <- C <- D and each case is the following:

The following table will showe that if user D play with 1 ETH or TT at 2019-01-01 12:00 and 2019-01-02 6:00, how much will user A, B and C get.

We are welcome for your participate and help. Please feel free to contribute and check out the contribution guide!