Solidity API

XAllocationPool

This contract is the receiver and distributor of weekly B3TR emissions for x2earn apps. Funds can be claimed by the X2Earn apps at the end of each allocation round

Interacts with the Emissions contract to get the amount of B3TR available for distribution in each round, and the x2EarnApps contract to check app existence and the app’s team wallet address. The contract is using AccessControl to handle roles for upgrading the contract and external contract addresses. —————————————————————————- ———————- Version 2 —————————————- - Added the abilty to toggle quadratic funding on and off. ———————- Version 3 —————————————- - Use new interface IX2EarnApps that supports endorsement. ———————- Version 4 —————————————- - Updated the X2EarnApps interface to support node cooldown functionality

PERCENTAGE_PRECISION_SCALING_FACTOR

uint256 PERCENTAGE_PRECISION_SCALING_FACTOR

UPGRADER_ROLE

bytes32 UPGRADER_ROLE

The role that can upgrade the contract.

CONTRACTS_ADDRESS_MANAGER_ROLE

bytes32 CONTRACTS_ADDRESS_MANAGER_ROLE

The role that can set the addresses of the contracts used by the VoterRewards contract.

XAllocationPoolStorage

struct XAllocationPoolStorage {
  contract IXAllocationVotingGovernor _xAllocationVoting;
  contract IEmissions _emissions;
  contract IB3TR b3tr;
  contract ITreasury treasury;
  contract IX2EarnApps x2EarnApps;
  contract IX2EarnRewardsPool x2EarnRewardsPool;
  mapping(bytes32 => mapping(uint256 => bool)) claimedRewards;
  struct Checkpoints.Trace208 quadraticFundingDisabled;
}

constructor

constructor() public

initialize

function initialize(address _admin, address upgrader, address contractsAddressManager, address _b3trAddress, address _treasury, address _x2EarnApps, address _x2EarnRewardsPool) public

Initializes the contract.

Parameters

Name	Type	Description
_admin	address	The address of the admin.
upgrader	address	The address of the upgrader.
contractsAddressManager	address	The address of the contracts address manager.
_b3trAddress	address	The address of the B3TR token.
_treasury	address	The address of the VeBetterDAO treasury.
_x2EarnApps	address	The address of the x2EarnApps contract.
_x2EarnRewardsPool	address	The address of the x2EarnRewardsPool contract.

XAllocationVotingSet

event XAllocationVotingSet(address oldContractAddress, address newContractAddress)

EmissionsContractSet

event EmissionsContractSet(address oldContractAddress, address newContractAddress)

TreasuryContractSet

event TreasuryContractSet(address oldContractAddress, address newContractAddress)

X2EarnAppsContractSet

event X2EarnAppsContractSet(address oldContractAddress, address newContractAddress)

QuadraticFundingToggled

event QuadraticFundingToggled(bool isDisabled)

Emits true if quadratic funding is disabled, false otherwise.

Parameters

Name	Type	Description
isDisabled	bool	- The flag to enable or disable quadratic funding.

_authorizeUpgrade

function _authorizeUpgrade(address newImplementation) internal

_Function that should revert when msg.sender is not authorized to upgrade the contract. Called by {upgradeToAndCall}.

Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.

function _authorizeUpgrade(address) internal onlyOwner {}
```_

### setXAllocationVotingAddress

```solidity
function setXAllocationVotingAddress(address xAllocationVoting_) external

Set the address of the XAllocationVotingGovernor contract.

setEmissionsAddress

function setEmissionsAddress(address emissions_) external

Set the address of the emissions contract.

setTreasuryAddress

function setTreasuryAddress(address treasury_) external

Set the address of the treasury contract.

setX2EarnAppsAddress

function setX2EarnAppsAddress(address x2EarnApps_) external

Set the address of the x2EarnApps contract.

toggleQuadraticFunding

function toggleQuadraticFunding() external

Toggle quadratic funding for the next round.

This function toggles the state of quadratic funding with new state being used in the next round. The state will flip between enabled and disabled each time the function is called.

claim

function claim(uint256 roundId, bytes32 appId) external

Claim the rewards for an app in a given round. The rewards are calculated based on the share of votes the app received. A percentage of the total reward is sent to the wallet of the team, while the remaining remains in the contract to be distributed to the users of the app. Unallocated rewards for each app will be sent to the VeBetterDAO treasury. Anyone can call this function. Round must be valid and app must exist.

Parameters

Name	Type	Description
roundId	uint256	The round ID from XAllocationVoting contract for which to claim the rewards.
appId	bytes32	The ID of the app from X2EarnApps contract for which to claim the rewards.

_emissionAmount

function _emissionAmount(uint256 roundId) internal view returns (uint256)

Returns the amount of $B3TR available for allocation in a given cycle. Each cycle is linked to a x-allocation round and they share the same id.

Parameters

Name	Type	Description
roundId	uint256	The round ID for which to calculate the amount available for allocation.

_rewardAmount

function _rewardAmount(uint256 roundId, uint256 share) internal view returns (uint256)

Returns the amount of $B3TR to be distrubuted to either the app or the treasury. The amount is calculated based on the share of votes the app received. The amount is scaled by 1e18 for precision.

Parameters

Name	Type	Description
roundId	uint256	The round ID for which to calculate the amount available for allocation.
share	uint256	The percentage of the total votes the app received.

_calculateTeamAllocation

function _calculateTeamAllocation(bytes32 appId, uint256 totalRoundEarnings) internal view returns (uint256, uint256)

Calculate the amount of B3TR that should be sent to the team and the amount that should be reserved to reward users.

Parameters

Name	Type	Description
appId	bytes32	the app id
totalRoundEarnings	uint256	full amount of B3TR available for allocation to the app

Return Values

Name	Type	Description
[0]	uint256	teamAllocationAmount amount of B3TR that will be sent to the team
[1]	uint256	x2EarnRewardsPoolAmount amount of B3TR reserved to reward users

claimableAmount

function claimableAmount(uint256 roundId, bytes32 appId) public view returns (uint256 totalAmount, uint256 unallocatedAmount, uint256 teamAllocationAmount, uint256 x2EarnRewardsPoolAmount)

Get how much an app can claim for a given round.

Parameters

Name	Type	Description
roundId	uint256	The round ID for which to calculate the amount available for allocation.
appId	bytes32	The ID of the app for which to calculate the amount available for allocation.

Return Values

Name	Type	Description
totalAmount	uint256	The total amount of $B3TR available for allocation to the app.
unallocatedAmount	uint256	The amount of $B3TR that was not allocated, and will be sent to the treasury.
teamAllocationAmount	uint256	The amount of $B3TR that will be sent to the team.
x2EarnRewardsPoolAmount	uint256	The amount of $B3TR reserved to reward users.

roundEarnings

function roundEarnings(uint256 roundId, bytes32 appId) public view returns (uint256 totalAmount, uint256 unallocatedAmount, uint256 teamAllocationAmount, uint256 x2EarnRewardsPoolAmount)

_The amount of allocation to distribute to the apps is calculated in two parts: - There is a minimum amount calculated through the baseAllocationPercentage of total available funds for the round divided by the number of eligible apps - There is a variable amount (calculated upon the variableAllocationPercentage of total available funds) that depends on the amounts of votes that an app receives. There is a cap to how much each x-app will be able to receive each round. Unallocated amount is calculated when the app share is greater than the max share an app get have.

If a round fails then we calculate the % of received votes (shares) against the previous succeeded round. If a round is succeeded then we calculate the % of received votes (shares) against it. If a round is active then results should be treated as real time estimation and not final results, since voting is still in progress._

Parameters

Name	Type	Description
roundId	uint256	The round ID for which to calculate the amount available for allocation.
appId	bytes32	The ID of the app for which to calculate the amount available for allocation.

Return Values

Name	Type	Description
totalAmount	uint256	The total amount of $B3TR available for allocation to the app.
unallocatedAmount	uint256	The amount of $B3TR that was not allocated, and will be sent to the treasury.
teamAllocationAmount	uint256	The amount of $B3TR that will be sent to the team.
x2EarnRewardsPoolAmount	uint256	The amount of $B3TR reserved to reward users.

currentRoundEarnings

function currentRoundEarnings(bytes32 appId) public view returns (uint256)

Fetches the id of the current round and calculates the earnings. Usually when calling this function round is active, and the results should be treated as real time estimation and not final results. If round ends and a new round did not start yet, then the results can be considered final.

Parameters

Name	Type	Description
appId	bytes32	The ID of the app for which to calculate the amount available for allocation.

baseAllocationAmount

function baseAllocationAmount(uint256 roundId) public view returns (uint256)

Calculate the minimum amount of $B3TR that will be distributed to each qualified X Application in a given round. baseAllocationPercentage% of allocations will be on average distributed to each qualified X Application as the base part of the allocation (so all the x-apps in the ecosystem will receive a minimum amount of $B3TR).

Parameters

Name	Type	Description
roundId	uint256	The round ID for which to calculate the amount available for allocation.

getAppShares

function getAppShares(uint256 roundId, bytes32 appId) public view returns (uint256, uint256)

Returns the funding percentage of votes for a given app in a given round. When calculating the percentage of votes received we check if the app exceeds the max cap of shares, eg: if an app has 80 votes out of 100, and the max cap is 50, then the app will have a share of 50% of the available funds. The remaining 30% will be sent to the treasury.

Parameters

Name	Type	Description
roundId	uint256	The round ID for which to calculate the amount of votes received in percentage.
appId	bytes32	The ID of the app.

Return Values

Name	Type	Description
[0]	uint256	appShare The percentage of votes received by the app.
[1]	uint256	unallocatedShare The amount of votes that were not allocated, and will be sent to the treasury.

claimed

function claimed(uint256 roundId, bytes32 appId) external view returns (bool)

Check if app has already claimed the rewards for a given round.

Parameters

Name	Type	Description
roundId	uint256	The round ID for which to check if the app has claimed the rewards.
appId	bytes32	The ID of the app.

scaledAppSharesCap

function scaledAppSharesCap(uint256 roundId) public view returns (uint256)

Returns the maximum app shares cap scaled by 1e2 for precision since our shares calculation is scaled by 1e4.

Parameters

Name	Type	Description
roundId	uint256	The round ID

getMaxAppAllocation

function getMaxAppAllocation(uint256 roundId) external view returns (uint256)

Returns the maximum amount an app can claim for a given round.

Parameters

Name	Type	Description
roundId	uint256	The round ID

isQuadraticFundingDisabledForRound

function isQuadraticFundingDisabledForRound(uint256 roundId) public view returns (bool)

Check if quadratic funding is disabled at a specific round.

To check if quadratic funding was disabled for a round, use the block number the cycle started.

Parameters

Name	Type	Description
roundId	uint256	- The round ID for which to check if quadratic funding is disabled.

Return Values

Name	Type	Description
[0]	bool	true if quadratic funding is disabled, false otherwise.

isQuadraticFundingDisabledForCurrentRound

function isQuadraticFundingDisabledForCurrentRound() public view returns (bool)

Check if quadratic funding is disabled for the current round.

Return Values

Name	Type	Description
[0]	bool	true if quadratic funding is disabled, false otherwise.

xAllocationVoting

function xAllocationVoting() public view returns (contract IXAllocationVotingGovernor)

Returns the XAllocationVotingGovernor contract.

emissions

function emissions() public view returns (contract IEmissions)

Returns the emissions contract.

treasury

function treasury() external view returns (contract ITreasury)

Returns the emissions contract.

b3tr

function b3tr() external view returns (contract IB3TR)

Returns the b3tr contract.

x2EarnApps

function x2EarnApps() external view returns (contract IX2EarnApps)

Returns the x2EarnApp contract.

version

function version() external pure virtual returns (string)

Returns the version of the contract

Return Values

Name	Type	Description
[0]	string	string The version of the contract

clock

function clock() public view virtual returns (uint48)

Clock used for flagging checkpoints.

CLOCK_MODE

function CLOCK_MODE() public view virtual returns (string)

Returns the mode of the clock.