_This contract is used by x2Earn apps to reward users that performed sustainable actions. The XAllocationPool contract or other contracts/users can deposit funds into this contract by specifying the app that can access the funds. Admins of x2EarnApps can withdraw funds from the rewards pool, whihch are sent to the team wallet. Reward distributors of a x2Earn app can distribute rewards to users that performed sustainable actions or withdraw funds to the team wallet. The contract is upgradable through the UUPS proxy pattern and UPGRADER_ROLE can authorize the upgrade.
—– Version 2 —– - Added onchain proof and impact tracking —– Version 3 —– - Added VeBetterPassport integration —– Version 4 —– - Updated the X2EarnApps interface to support node endorsement feature —– Version 5 —– - Updated the X2EarnApps interface to support node cooldown functionality —– Version 6 —– - Added distribute with metadata functionality —– Version 7 —– - Added optional dual-pool balance to manage rewards and treasury separately - Added 2 new storage variables: rewardsPoolBalance and isRewardsPoolEnabled - Modified withdrawal access control to only admin - Rewards distribution can be paused by admin_
bytes32 UPGRADER_ROLEbytes32 CONTRACTS_ADDRESS_MANAGER_ROLEbytes32 IMPACT_KEY_MANAGER_ROLEconstructor() publicstruct X2EarnRewardsPoolStorage {
contract IB3TR b3tr;
contract IX2EarnApps x2EarnApps;
mapping(bytes32 => uint256) availableFunds;
mapping(string => uint256) impactKeyIndex;
string[] allowedImpactKeys;
contract IVeBetterPassport veBetterPassport;
mapping(bytes32 => uint256) rewardsPoolBalance;
mapping(bytes32 => bool) isRewardsPoolEnabled;
mapping(bytes32 => bool) distributionPaused;
}function initialize(address _admin, address _contractsManagerAdmin, address _upgrader, contract IB3TR _b3tr, contract IX2EarnApps _x2EarnApps) externalfunction initializeV2(address _impactKeyManager, string[] _initialImpactKeys) externalfunction initializeV3(address _veBetterPassport) externalmodifier onlyRoleOrAdmin(bytes32 role)Modifier to check if the user has the required role or is the DEFAULT_ADMIN_ROLE
| Name | Type | Description |
|---|---|---|
| role | bytes32 | - the role to check |
modifier onlyX2EarnApps()Modifier to ensure function can only be called by the X2EarnApps contract
function _authorizeUpgrade(address newImplementation) internal virtual_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 {}
```_
### pauseDistribution
```solidity
function pauseDistribution(bytes32 appId) externalPauses reward distribution for a specific app
Only app admins can pause their own app
| Name | Type | Description |
|---|---|---|
| appId | bytes32 | - the app ID to pause |
function unpauseDistribution(bytes32 appId) externalUnpauses reward distribution for a specific app
Only app admins can unpause their own app
| Name | Type | Description |
|---|---|---|
| appId | bytes32 | - the app ID to unpause |
function deposit(uint256 amount, bytes32 appId) external returns (bool)See {IX2EarnRewardsPool-deposit}
function withdraw(uint256 amount, bytes32 appId, string reason) externalSee {IX2EarnRewardsPool-withdraw}
function distributeRewardDeprecated(bytes32 appId, uint256 amount, address receiver, string proof) externalThis function was initially planned for deprecation but has been retained due to its continued relevance and usage. It remains for backward compatibility and is not scheduled for removal at this time.
Distribute rewards to a user with a self provided proof.
function distributeReward(bytes32 appId, uint256 amount, address receiver, string) externalthe proof argument is unused but kept for backwards compatibility
{IX2EarnRewardsPool-distributeReward}
function distributeRewardWithProof(bytes32 appId, uint256 amount, address receiver, string[] proofTypes, string[] proofValues, string[] impactCodes, uint256[] impactValues, string description) externalSee {IX2EarnRewardsPool-distributeRewardWithProof}
function distributeRewardWithProofAndMetadata(bytes32 appId, uint256 amount, address receiver, string[] proofTypes, string[] proofValues, string[] impactCodes, uint256[] impactValues, string description, string metadata) externalSee {IX2EarnRewardsPool-distributeRewardWithProofAndMetadata}
function _distributeReward(bytes32 appId, uint256 amount, address receiver) internalThe impact is an array of integers and codes that represent the impact of the action. Each index of the array represents a different impact. The codes are predefined and the values are the impact values. Example: [“carbon”, “water”, “energy”], [100, 200, 300]
See {IX2EarnRewardsPool-distributeReward}
function increaseRewardsPoolBalance(bytes32 appId, uint256 amount) externalIncreases the balance for rewards distribution and toggles the feature if needed
| Name | Type | Description |
|---|---|---|
| appId | bytes32 | - the app ID |
| amount | uint256 | - the amount that will be used for rewards distribution |
function decreaseRewardsPoolBalance(bytes32 appId, uint256 amount) externalDecreases the balance for rewards distribution and toggles the feature if needed
| Name | Type | Description |
|---|---|---|
| appId | bytes32 | - the app ID |
| amount | uint256 | - the amount that will be used for rewards distribution |
function toggleRewardsPoolBalance(bytes32 appId, bool enable) externalEnable / Disable the rewards pool for rewards distribution
| Name | Type | Description |
|---|---|---|
| appId | bytes32 | - the app ID |
| enable | bool | - true to enable, false to disable Note: When disabled, the main pool goes back to the available funds |
function enableRewardsPoolForNewApp(bytes32 appId) externalThis function can only be called by the X2EarnApps contract during app submission
Function to enable rewards pool on all newly registered apps
| Name | Type | Description |
|---|---|---|
| appId | bytes32 | - the app ID |
function _emitProof(bytes32 appId, uint256 amount, address receiver, string[] proofTypes, string[] proofValues, string[] impactCodes, uint256[] impactValues, string description) internalEmits the RewardDistributed event with the provided proofs and impacts.
function _emitMetadata(bytes32 appId, uint256 amount, address receiver, string metadata) internalEmits the RewardMetadata event with the provided metadata.
function buildProof(string[] proofTypes, string[] proofValues, string[] impactCodes, uint256[] impactValues, string description) public view virtual returns (string)see {IX2EarnRewardsPool-buildProof}
function _buildProofJson(string[] proofTypes, string[] proofValues) internal pure returns (bytes)Builds the proof JSON string from the proof data.
| Name | Type | Description |
|---|---|---|
| proofTypes | string[] | the proof types |
| proofValues | string[] | the proof values |
function _buildImpactJson(string[] impactCodes, uint256[] impactValues) internal view returns (bytes)Builds the impact JSON string from the impact data.
| Name | Type | Description |
|---|---|---|
| impactCodes | string[] | the impact codes |
| impactValues | uint256[] | the impact values |
function _isAllowedImpactKey(string key) internal view returns (bool)Checks if the key is allowed.
function _isValidProofType(string proofType) internal pure returns (bool)Checks if the proof type is valid.
function setX2EarnApps(contract IX2EarnApps _x2EarnApps) externalSets the X2EarnApps contract address.
| Name | Type | Description |
|---|---|---|
| _x2EarnApps | contract IX2EarnApps | the new X2EarnApps contract |
function addImpactKey(string newKey) externalAdds a new allowed impact key.
| Name | Type | Description |
|---|---|---|
| newKey | string | the new key to add |
function _addImpactKey(string key, struct X2EarnRewardsPool.X2EarnRewardsPoolStorage $) internalInternal function to add a new allowed impact key.
| Name | Type | Description |
|---|---|---|
| key | string | the new key to add |
| $ | struct X2EarnRewardsPool.X2EarnRewardsPoolStorage |
function removeImpactKey(string keyToRemove) externalRemoves an allowed impact key.
| Name | Type | Description |
|---|---|---|
| keyToRemove | string | the key to remove |
function setVeBetterPassport(contract IVeBetterPassport _veBetterPassport) externalSets the VeBetterPassport contract address.
| Name | Type | Description |
|---|---|---|
| _veBetterPassport | contract IVeBetterPassport | the new VeBetterPassport contract |
function availableFunds(bytes32 appId) external view returns (uint256)See {IX2EarnRewardsPool-availableFunds}
function totalBalance(bytes32 appId) external view returns (uint256)See {IX2EarnRewardsPool-totalBalance}
function isRewardsPoolEnabled(bytes32 appId) external view returns (bool)See {IX2EarnRewardsPool-isRewardsPoolEnabled}
function isDistributionPaused(bytes32 appId) external view returns (bool)See {IX2EarnRewardsPool-isDistributionPaused}
function rewardsPoolBalance(bytes32 appId) external view returns (uint256)See {IX2EarnRewardsPool-rewardsPoolBalance}
function version() external pure virtual returns (string)See {IX2EarnRewardsPool-version}
function b3tr() external view returns (contract IB3TR)Retrieves the B3TR token contract.
function x2EarnApps() external view returns (contract IX2EarnApps)Retrieves the X2EarnApps contract.
function getAllowedImpactKeys() external view returns (string[])Retrieves the allowed impact keys.
function veBetterPassport() external view returns (contract IVeBetterPassport)Retrieves the VeBetterPassport contract.
receive() external payable virtualTransfers of VET to this contract are not allowed.
fallback() external payableContract does not accept calls/data.
function onERC721Received(address, address, uint256, bytes) public virtual returns (bytes4)supported only when safeTransferFrom is used
Transfers of ERC721 tokens to this contract are not allowed.
function onERC1155Received(address, address, uint256, uint256, bytes) public virtual returns (bytes4)Transfers of ERC1155 tokens to this contract are not allowed.
function onERC1155BatchReceived(address, address, uint256[], uint256[], bytes) public virtual returns (bytes4)Transfers of ERC1155 tokens to this contract are not allowed.