Solidity API

RelayerRewardsPool

This contract manages rewards for relayers who perform auto-voting actions on behalf of users.

_The contract is: - upgradeable using UUPSUpgradeable - using AccessControl to handle admin and relayer roles - using ReentrancyGuard to prevent reentrancy attacks - following the ERC-7201 standard for storage layout

Roles: - DEFAULT_ADMIN_ROLE: Super admin role for critical operations (contract upgrades, role management) - UPGRADER_ROLE: Can upgrade the contract - POOL_ADMIN_ROLE: For pool administration functions (manage relayers, weights, settings)

—————— Version 2 Changes —————— - Added preferred relayer functionality_

UPGRADER_ROLE

bytes32 UPGRADER_ROLE

The role that can upgrade the contract

POOL_ADMIN_ROLE

bytes32 POOL_ADMIN_ROLE

The role for pool administration functions

RelayerRewardsPoolStorage

struct RelayerRewardsPoolStorage {
  contract IB3TR b3tr;
  contract IEmissions emissions;
  contract IXAllocationVotingGovernor xAllocationVoting;
  mapping(uint256 => uint256) totalRewards;
  mapping(uint256 => mapping(address => uint256)) relayerActions;
  mapping(uint256 => mapping(address => uint256)) relayerWeightedActions;
  mapping(uint256 => uint256) totalActions;
  mapping(uint256 => uint256) totalWeightedActions;
  mapping(uint256 => mapping(address => bool)) claimed;
  mapping(uint256 => uint256) completedActions;
  mapping(uint256 => uint256) completedWeightedActions;
  uint256 voteWeight;
  uint256 claimWeight;
  mapping(address => bool) registeredRelayers;
  address[] relayerAddresses;
  uint256 earlyAccessBlocks;
  uint256 relayerFeePercentage;
  uint256 relayerFeeDenominator;
  uint256 feeCap;
  mapping(address => address) preferredRelayer;
}

_getRelayerRewardsPoolStorage

function _getRelayerRewardsPoolStorage() internal pure returns (struct RelayerRewardsPool.RelayerRewardsPoolStorage $)

Get the RelayerRewardsPoolStorage struct from the specified storage slot

onlyRoleOrAdmin

modifier onlyRoleOrAdmin(bytes32 role)

Modifier to check if the caller has either the default admin or pool admin role

constructor

constructor() public

initialize

function initialize(address admin, address upgrader, address b3trAddress, address emissionsAddress, address xAllocationVotingAddress) public

Initialize the contract

Parameters

Name	Type	Description
admin	address	The admin address
upgrader	address	The upgrader address
b3trAddress	address	The B3TR contract address
emissionsAddress	address	The Emissions contract address
xAllocationVotingAddress	address	The XAllocationVoting contract address

_authorizeUpgrade

function _authorizeUpgrade(address newImplementation) internal

Authorizes upgrade to a new implementation

Parameters

Name	Type	Description
newImplementation	address	The address of the new implementation

initializeV2

function initializeV2() external

Initialize version 2 of the contract

Reserved for the preferred relayer upgrade

_validatePreferredRelayer

function _validatePreferredRelayer(address voter, address caller) internal view

Validate the preferred relayer constraint during early access

Parameters

Name	Type	Description
voter	address	The voter whose action is being performed
caller	address	The relayer attempting to perform the action

getRelayerFeeDenominator

function getRelayerFeeDenominator() external view returns (uint256)

Get the current relayer fee denominator

Return Values

Name	Type	Description
[0]	uint256	The current relayer fee denominator

getRelayerFeePercentage

function getRelayerFeePercentage() external view returns (uint256)

Get the current relayer fee percentage

Return Values

Name	Type	Description
[0]	uint256	The current relayer fee percentage

getFeeCap

function getFeeCap() external view returns (uint256)

Get the current fee cap

Return Values

Name	Type	Description
[0]	uint256	The current fee cap

getVoteWeight

function getVoteWeight() external view returns (uint256)

Get the current vote weight

Return Values

Name	Type	Description
[0]	uint256	The current vote weight

getClaimWeight

function getClaimWeight() external view returns (uint256)

Get the current claim weight

Return Values

Name	Type	Description
[0]	uint256	The current claim weight

getTotalRewards

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

Returns the total rewards available for distribution among relayers in a round

Parameters

Name	Type	Description
roundId	uint256	The round ID to check

Return Values

Name	Type	Description
[0]	uint256	The total reward amount for the round

isRewardClaimable

function isRewardClaimable(uint256 roundId) external view returns (bool)

Checks if rewards are claimable for a specific round

Parameters

Name	Type	Description
roundId	uint256	The round ID to check

Return Values

Name	Type	Description
[0]	bool	True if rewards are claimable, false otherwise

totalRelayerActions

function totalRelayerActions(address relayer, uint256 roundId) external view returns (uint256)

Returns the number of actions performed by a relayer in a specific round

Parameters

Name	Type	Description
relayer	address	The relayer address
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	uint256	The number of actions performed by the relayer

totalActions

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

Returns the total number of actions required for a round

Parameters

Name	Type	Description
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	uint256	The total number of actions required for the round

claimableRewards

function claimableRewards(address relayer, uint256 roundId) external view returns (uint256)

Returns the claimable reward amount for a relayer in a specific round

Parameters

Name	Type	Description
relayer	address	The relayer address
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	uint256	The claimable reward amount

isRegisteredRelayer

function isRegisteredRelayer(address relayer) external view returns (bool)

Check if an address is a registered relayer

Parameters

Name	Type	Description
relayer	address	The address to check

Return Values

Name	Type	Description
[0]	bool	True if the address is a registered relayer

getRegisteredRelayers

function getRegisteredRelayers() external view returns (address[])

Get all registered relayers

Return Values

Name	Type	Description
[0]	address[]	Array of registered relayer addresses

getPreferredRelayer

function getPreferredRelayer(address user) external view returns (address)

Get the preferred relayer for a user

Parameters

Name	Type	Description
user	address	The user address

Return Values

Name	Type	Description
[0]	address	The preferred relayer, or zero address if not set

getEarlyAccessBlocks

function getEarlyAccessBlocks() external view returns (uint256)

Get the number of early access blocks

Return Values

Name	Type	Description
[0]	uint256	The number of blocks for early access period

isVoteEarlyAccessActive

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

Check if early access period is active for a given round

Parameters

Name	Type	Description
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	bool	True if early access period is still active

isClaimEarlyAccessActive

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

Check if claim early access period is active for a given round

Parameters

Name	Type	Description
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	bool	True if claim early access period is still active

totalRelayerWeightedActions

function totalRelayerWeightedActions(address relayer, uint256 roundId) external view returns (uint256)

Returns the total weighted actions performed by a relayer in a specific round

Parameters

Name	Type	Description
relayer	address	The relayer address
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	uint256	The total weighted actions performed by the relayer

totalWeightedActions

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

Returns the total weighted actions required for a round

Parameters

Name	Type	Description
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	uint256	The total weighted actions required for the round

completedWeightedActions

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

Returns the total completed weighted actions for a round

Parameters

Name	Type	Description
roundId	uint256	The round ID

Return Values

Name	Type	Description
[0]	uint256	The total completed weighted actions for the round

getMissedAutoVotingUsersCount

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

Calculates the number of auto-voting users who were completely missed (no vote cast)

Only counts users where BOTH vote AND claim actions were missed Partial completions (vote done but claim missing) are NOT counted as missed users

Parameters

Name	Type	Description
roundId	uint256	The round ID to check

Return Values

Name	Type	Description
[0]	uint256	The number of auto-voting users who were completely missed

validateVoteDuringEarlyAccess

function validateVoteDuringEarlyAccess(uint256 roundId, address voter, address caller) external view

Validates if an action can proceed for an auto-voting user

Reverts if action is not allowed during early access period

Parameters

Name	Type	Description
roundId	uint256	The round ID
voter	address	The voter whose action is being performed
caller	address	The address attempting to perform the action

validateClaimDuringEarlyAccess

function validateClaimDuringEarlyAccess(uint256 roundId, address voter, address caller) external view

Validates if a claim can proceed for an auto-voting user

Reverts if action is not allowed during early access period

Parameters

Name	Type	Description
roundId	uint256	The round ID
voter	address	The voter whose action is being performed
caller	address	The address attempting to perform the action

getB3trAddress

function getB3trAddress() external view returns (address)

Get the B3TR contract address

Return Values

Name	Type	Description
[0]	address	The B3TR contract address

getEmissionsAddress

function getEmissionsAddress() external view returns (address)

Get the Emissions contract address

Return Values

Name	Type	Description
[0]	address	The Emissions contract address

getXAllocationVotingAddress

function getXAllocationVotingAddress() external view returns (address)

Get the XAllocationVoting contract address

Return Values

Name	Type	Description
[0]	address	The XAllocationVoting contract address

setB3TRAddress

function setB3TRAddress(address b3trAddress) external

Set the B3TR contract address

Parameters

Name	Type	Description
b3trAddress	address	The B3TR contract address

setEmissionsAddress

function setEmissionsAddress(address emissionsAddress) external

Set the Emissions contract address

Parameters

Name	Type	Description
emissionsAddress	address	The Emissions contract address

setXAllocationVotingAddress

function setXAllocationVotingAddress(address xAllocationVotingAddress) external

Set the XAllocationVoting contract address

Parameters

Name	Type	Description
xAllocationVotingAddress	address	The XAllocationVoting contract address

setRelayerFeeDenominator

function setRelayerFeeDenominator(uint256 newDenominator) external

Set the relayer fee denominator

Parameters

Name	Type	Description
newDenominator	uint256	The new relayer fee denominator

setRelayerFeePercentage

function setRelayerFeePercentage(uint256 newFeePercentage) external

Set the relayer fee percentage

Unit: whole percent where 1 == 1%

Parameters

Name	Type	Description
newFeePercentage	uint256	- The new relayer fee percentage

setFeeCap

function setFeeCap(uint256 newFeeCap) external

Set the fee cap for the relayer.

Parameters

Name	Type	Description
newFeeCap	uint256	The new fee cap

setVoteWeight

function setVoteWeight(uint256 newWeight) external

Set the vote weight

Parameters

Name	Type	Description
newWeight	uint256	The new vote weight

setClaimWeight

function setClaimWeight(uint256 newWeight) external

Set the claim weight

Parameters

Name	Type	Description
newWeight	uint256	The new claim weight

claimRewards

function claimRewards(uint256 roundId, address relayer) external

Allows a relayer to claim their rewards for a specific round

Parameters

Name	Type	Description
roundId	uint256	The round ID
relayer	address	The relayer address

registerRelayerAction

function registerRelayerAction(address relayer, address voter, uint256 roundId, enum RelayerAction action) external

Registers an action performed by a relayer in a specific round

Parameters

Name	Type	Description
relayer	address	The relayer address
voter	address	The voter address
roundId	uint256	The round ID
action	enum RelayerAction	The type of action performed (VOTE or CLAIM)

setTotalActionsForRound

function setTotalActionsForRound(uint256 roundId, uint256 totalAutoVotingUsers) external

Sets the total number of actions required for a round

This should be called when the round starts based on the number of users with auto-voting enabled

Parameters

Name	Type	Description
roundId	uint256	The round ID
totalAutoVotingUsers	uint256	The total number of auto-voting users

reduceExpectedActionsForRound

function reduceExpectedActionsForRound(uint256 roundId, uint256 userCount) external

Reduces the total expected actions for a round when an auto-voting user cannot vote

Parameters

Name	Type	Description
roundId	uint256	The round ID
userCount	uint256	The number of users to remove from expected actions (typically 1)

registerRelayer

function registerRelayer(address relayer) external

Parameters

Name	Type	Description
relayer	address	The address of the relayer to register

unregisterRelayer

function unregisterRelayer(address relayer) external

Unregister a relayer from early access. A relayer can unregister themselves; pool admin can unregister any relayer.

Parameters

Name	Type	Description
relayer	address	The address of the relayer to unregister

setPreferredRelayer

function setPreferredRelayer(address relayer) external

Set or clear the caller’s preferred relayer for early access actions

Parameters

Name	Type	Description
relayer	address	The preferred relayer, or zero address to clear it

setEarlyAccessBlocks

function setEarlyAccessBlocks(uint256 blocks) external

Set the number of blocks for early access period

Parameters

Name	Type	Description
blocks	uint256	The number of blocks for early access

deposit

function deposit(uint256 amount, uint256 roundId) external

Deposits B3TR tokens into the pool for a specific round

Parameters

Name	Type	Description
amount	uint256	The amount of B3TR tokens to deposit
roundId	uint256	The round ID to deposit for

calculateRelayerFee

function calculateRelayerFee(uint256 totalReward) external view returns (uint256)

Calculate relayer fee from total reward

Parameters

Name	Type	Description
totalReward	uint256	Total reward amount in wei

Return Values

Name	Type	Description
[0]	uint256	Relayer fee in wei

version

function version() external pure returns (string)

Returns the contract version

Return Values

Name	Type	Description
[0]	string	The version string