Solidity API

Emissions

This contract is responsible for the scheduled distribution of emissions based on predefined cycles and decay settings.

Manages the periodic distribution of B3TR tokens to XAllocation, Vote2Earn, and Treasury allocations. This contract leverages openzeppelin’s AccessControl, ReentrancyGuard, and UUPSUpgradeable libraries for access control, reentrancy protection, and upgradability.

MINTER_ROLE

bytes32 MINTER_ROLE

Role for addresses allowed to mint new tokens

UPGRADER_ROLE

bytes32 UPGRADER_ROLE

Role for addresses that can upgrade the contract

CONTRACTS_ADDRESS_MANAGER_ROLE

bytes32 CONTRACTS_ADDRESS_MANAGER_ROLE

The role that can set external contracts addresses

DECAY_SETTINGS_MANAGER_ROLE

bytes32 DECAY_SETTINGS_MANAGER_ROLE

Role for addresses that can update the decay settings

SCALING_FACTOR

uint256 SCALING_FACTOR

EmissionDistributed

event EmissionDistributed(uint256 cycle, uint256 xAllocations, uint256 vote2Earn, uint256 treasury)

Emitted when emissions are distributed for a cycle

XAllocationsAddressUpdated

event XAllocationsAddressUpdated(address newAddress, address oldAddress)

Emitted when XAllocations address is updated

Vote2EarnAddressUpdated

event Vote2EarnAddressUpdated(address newAddress, address oldAddress)

Emitted when Vote2Earn address is updated

XAllocationsGovernorAddressUpdated

event XAllocationsGovernorAddressUpdated(address newAddress, address oldAddress)

Emitted when XAllocationsGovernor address is updated

TreasuryAddressUpdated

event TreasuryAddressUpdated(address newAddress, address oldAddress)

Emitted when Treasury address is updated

EmissionCycleDurationUpdated

event EmissionCycleDurationUpdated(uint256 newDuration, uint256 oldDuration)

Emitted when the emission cycle duration is updated

XAllocationsDecayUpdated

event XAllocationsDecayUpdated(uint256 newDecay, uint256 oldDecay)

Emitted when the xAllocations decay rate is updated

Vote2EarnDecayUpdated

event Vote2EarnDecayUpdated(uint256 newDecay, uint256 oldDecay)

Emitted when the vote2Earn decay rate is updated

Vote2EarnDecayPeriodUpdated

event Vote2EarnDecayPeriodUpdated(uint256 newPeriod, uint256 oldPeriod)

Emitted when the vote2Earn decay period is updated

MaxVote2EarnDecayUpdated

event MaxVote2EarnDecayUpdated(uint256 newDecay, uint256 oldDecay)

Emitted when the max vote2Earn decay rate is updated

XAllocationsDecayPeriodUpdated

event XAllocationsDecayPeriodUpdated(uint256 newPeriod, uint256 oldPeriod)

Emitted when the xAllocations decay period is updated

TreasuryPercentageUpdated

event TreasuryPercentageUpdated(uint256 newPercentage, uint256 oldPercentage)

Emitted when the treasury percentage is updated

InitializationData

Initialization data for the Emissions contract

struct InitializationData {
  address minter;
  address admin;
  address upgrader;
  address contractsAddressManager;
  address decaySettingsManager;
  address b3trAddress;
  address[4] destinations;
  uint256 migrationAmount;
  uint256 initialXAppAllocation;
  uint256 cycleDuration;
  uint256[4] decaySettings;
  uint256 treasuryPercentage;
  uint256 maxVote2EarnDecay;
}

Emission

struct Emission {
  uint256 xAllocations;
  uint256 vote2Earn;
  uint256 treasury;
}

EmissionsStorage

Storage structure for the Emissions contract

Struct to store the state of emissions

struct EmissionsStorage {
  contract IB3TR b3tr;
  contract IXAllocationVotingGovernor xAllocationsGovernor;
  address _xAllocations;
  address _vote2Earn;
  address _treasury;
  address _migration;
  uint256 _migrationAmount;
  uint256 nextCycle;
  uint256 cycleDuration;
  uint256 xAllocationsDecay;
  uint256 vote2EarnDecay;
  uint256 maxVote2EarnDecay;
  uint256 xAllocationsDecayPeriod;
  uint256 vote2EarnDecayPeriod;
  uint256 initialXAppAllocation;
  uint256 treasuryPercentage;
  uint256 lastEmissionBlock;
  mapping(uint256 => struct Emissions.Emission) emissions;
  uint256 totalEmissions;
  bool _isEmissionsNotAligned;
}

constructor

constructor() public

initialize

function initialize(struct Emissions.InitializationData data) external

Initializes the contract with specific operational parameters for emissions management

Sets up the initial configurations including token addresses, allocation destinations, cycle parameters, and decay mechanics

Parameters

Name	Type	Description
data	struct Emissions.InitializationData	A struct containing all necessary initialization data: - minter: Address with the minter role who can initiate token distributions - admin: Address with administrative rights - upgrader: Address authorized to upgrade the contract - b3trAddress: Contract address of the B3TR token - destinations: Array of addresses for emissions allocations: [XAllocations, Vote2Earn, Treasury, Migration] - initialXAppAllocation: Initial amount of tokens allocated for XAllocations - cycleDuration: Duration of each emission cycle in blocks - decaySettings: Array with decay rates and periods [XAllocations Decay Rate, Vote2Earn Decay Rate, XAllocations Decay Period, Vote2Earn Decay Period] - treasuryPercentage: Percentage of total emissions allocated to the treasury - maxVote2EarnDecay: Maximum allowable decay rate for Vote2Earn allocations to ensure sustainability - migrationAmount: Amount of tokens seed the migration account with

initializeV2

function initializeV2(bool _isEmissionsNotAligned) external

Reinitializes the contract with new parameters

Parameters

Name	Type	Description
_isEmissionsNotAligned	bool	Flag to indicate if emissions are aligned with the Emissions schedule

_authorizeUpgrade

function _authorizeUpgrade(address newImplementation) internal

Authorized upgrading of the contract implementation

This function can only be called by addresses with the UPGRADER_ROLE

Parameters

Name	Type	Description
newImplementation	address	Address of the new contract implementation

bootstrap

function bootstrap() external

Handles the bootstrapping of the initial emission cycle.

This function can only be called by addresses with the MINTER_ROLE and only when the next cycle is 0.

start

function start() external

Starts the emission process after the initial bootstrap.

This function can only be called by addresses with the MINTER_ROLE and only when the next cycle is 1.

distribute

function distribute() public virtual

Distributes the tokens for the current cycle, calculates allocations based on decay rates.

_calculateNextXAllocation

function _calculateNextXAllocation() internal view virtual returns (uint256)

Calculates the token allocation for XAllocations for the upcoming cycle, taking into account decay rates

Calculates emissions based on the previous cycle’s emissions and applies decay if a new decay period has started If it’s the first cycle, returns the initial allocation

Return Values

Name	Type	Description
[0]	uint256	uint256 The calculated number of tokens for the next cycle

_calculateVote2EarnDecayPeriods

function _calculateVote2EarnDecayPeriods() internal view virtual returns (uint256)

Calculates the number of decay periods that have passed since the start of the emissions

Used to determine how many times the decay rate should be applied to the Vote2Earn emissions The number of decay periods is calculated as follows: number of decay periods = floor(number of periods / decay period)

Return Values

Name	Type	Description
[0]	uint256	uint256 The number of decay periods since the start of emissions

_calculateVote2EarnDecayPercentage

function _calculateVote2EarnDecayPercentage() internal view virtual returns (uint256)

Calculates the decay percentage for Vote2Earn allocations for the next cycle

The decay percentage is determined by the elapsed decay periods and the specified decay rate, capped at a maximum decay rate The decay percentage is calculated as follows: decay percentage = decay rate * number of decay periods The decay percentage is capped at a maximum value to ensure sustainability

Return Values

Name	Type	Description
[0]	uint256	uint256 The calculated decay percentage for the next cycle

_calculateVote2EarnAmount

function _calculateVote2EarnAmount() internal view virtual returns (uint256)

Calculates the token allocation for Vote2Earn for the upcoming cycle

Applies the calculated decay percentage to the XAllocation from the upcoming cycle to determine Vote2Earn allocation

Return Values

Name	Type	Description
[0]	uint256	uint256 The calculated number of tokens for Vote2Earn for the next cycle

_calculateTreasuryAmount

function _calculateTreasuryAmount() internal view virtual returns (uint256)

Calculates the token allocation for the Treasury based on the total allocations to XAllocations and Vote2Earn

Treasury gets a percentage of the combined XAllocations and Vote2Earn amounts, adjusted by the treasury percentage

Return Values

Name	Type	Description
[0]	uint256	unit256 The calculated number of tokens for the Treasury for the next cycle

getXAllocationAmount

function getXAllocationAmount(uint256 cycle) public view virtual returns (uint256)

Retrieves the XAllocation amount for a specified cycle

Returns the allocated amount if the cycle has been distributed, otherwise calculates the expected allocation

Parameters

Name	Type	Description
cycle	uint256	The cycle number to query

Return Values

Name	Type	Description
[0]	uint256	uint256 The amount of XAllocations for the specified cycle

getVote2EarnAmount

function getVote2EarnAmount(uint256 cycle) public view virtual returns (uint256)

Retrieves the Vote2Earn allocation for a specified cycle

Returns the allocated amount if the cycle has been distributed, otherwise calculates the expected allocation

Parameters

Name	Type	Description
cycle	uint256	The cycle number to query

Return Values

Name	Type	Description
[0]	uint256	uint256 The amount of Vote2Earn for the specified cycle

getTreasuryAmount

function getTreasuryAmount(uint256 cycle) public view virtual returns (uint256)

Retrieves the Treasury allocation for a specified cycle

Returns the allocated amount if the cycle has been distributed, otherwise calculates the expected allocation

Parameters

Name	Type	Description
cycle	uint256	The cycle number to query

Return Values

Name	Type	Description
[0]	uint256	uint256 The amount of Treasury allocation for the specified cycle

isCycleDistributed

function isCycleDistributed(uint256 cycle) public view virtual returns (bool)

Checks if a specific cycle’s allocations have been distributed

Parameters

Name	Type	Description
cycle	uint256	The cycle number to check

Return Values

Name	Type	Description
[0]	bool	True if the cycle has been distributed, false otherwise

isCycleEnded

function isCycleEnded(uint256 cycle) public view virtual returns (bool)

Determines if a specific cycle has ended

Parameters

Name	Type	Description
cycle	uint256	The cycle number to check

Return Values

Name	Type	Description
[0]	bool	True if the cycle has ended, false otherwise

getCurrentCycle

function getCurrentCycle() public view virtual returns (uint256)

Retrieves the current cycle number

The current cycle is the next cycle minus one

Return Values

Name	Type	Description
[0]	uint256	uint256 The current cycle number

getNextCycleBlock

function getNextCycleBlock() public view virtual returns (uint256)

Retrieves the block number when the next cycle will start

Return Values

Name	Type	Description
[0]	uint256	uint256 The starting block number of the next cycle

isNextCycleDistributable

function isNextCycleDistributable() public view virtual returns (bool)

Checks if the next cycle can start based on the block number

Return Values

Name	Type	Description
[0]	bool	True if the next cycle can be started, false otherwise

getRemainingEmissions

function getRemainingEmissions() public view returns (uint256)

Calculates the remaining emissions available for distribution

Return Values

Name	Type	Description
[0]	uint256	uint256 The total number of tokens still available for emission

treasury

function treasury() public view returns (address)

Returns the address of the Treasury

vote2Earn

function vote2Earn() public view returns (address)

Returns the address of the Vote2Earn allocation

xAllocations

function xAllocations() public view returns (address)

Returns the address for XAllocations

b3tr

function b3tr() public view returns (contract IB3TR)

Returns the B3TR contract

xAllocationsGovernor

function xAllocationsGovernor() public view returns (contract IXAllocationVotingGovernor)

Returns the XAllocations Governance contract

cycleDuration

function cycleDuration() public view returns (uint256)

Retrieves the cycle duration in blocks

nextCycle

function nextCycle() public view returns (uint256)

Retrieves the block number of the next emission cycle

Return Values

Name	Type	Description
[0]	uint256	uint256 The block number of the next cycle

xAllocationsDecay

function xAllocationsDecay() public view returns (uint256)

Retrieves the current decay rate for XAllocations

Return Values

Name	Type	Description
[0]	uint256	uint256 The decay rate as a percentage

vote2EarnDecay

function vote2EarnDecay() public view returns (uint256)

Retrieves the current decay rate for Vote2Earn allocations

Return Values

Name	Type	Description
[0]	uint256	uint256 The decay rate as a percentage

maxVote2EarnDecay

function maxVote2EarnDecay() public view returns (uint256)

Retrieves the maximum allowed decay rate for Vote2Earn

Return Values

Name	Type	Description
[0]	uint256	uint256 The maximum decay rate as a percentage

xAllocationsDecayPeriod

function xAllocationsDecayPeriod() public view returns (uint256)

Retrieves the decay period for XAllocations

Return Values

Name	Type	Description
[0]	uint256	uint256 The number of blocks between decay periods

vote2EarnDecayPeriod

function vote2EarnDecayPeriod() public view returns (uint256)

Retrieves the decay period for Vote2Earn allocations

Return Values

Name	Type	Description
[0]	uint256	uint256 The number of cycles between decay applications

initialXAppAllocation

function initialXAppAllocation() public view returns (uint256)

Retrieves the initial allocation for XAllocations at the start of the first cycle

Return Values

Name	Type	Description
[0]	uint256	uint256 The amount of tokens initially allocated

treasuryPercentage

function treasuryPercentage() public view returns (uint256)

Retrieves the percentage of total emissions allocated to the Treasury

Return Values

Name	Type	Description
[0]	uint256	uint256 The treasury percentage

lastEmissionBlock

function lastEmissionBlock() public view returns (uint256)

Retrieves the block number when the last emission occurred

Return Values

Name	Type	Description
[0]	uint256	uint256 The block number of the last emission

totalEmissions

function totalEmissions() public view returns (uint256)

Retrieves the total amount of emissions that have been distributed across all cycles

Return Values

Name	Type	Description
[0]	uint256	uint256 The total emissions distributed

emissions

function emissions(uint256 cycle) public view returns (struct Emissions.Emission)

Retrieves the emission details for a specific cycle

Parameters

Name	Type	Description
cycle	uint256	The cycle number to query

Return Values

Name	Type	Description
[0]	struct Emissions.Emission	Emission A struct containing the allocations for XAllocations, Vote2Earn, and Treasury

isEmissionsNotAligned

function isEmissionsNotAligned() public view returns (bool)

version

function version() public pure virtual returns (string)

Retrieves the current version of the contract

This function is used to identify the version of the contract and should be overridden in each new version

Return Values

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

setXallocationsAddress

function setXallocationsAddress(address xAllocationAddress) public virtual

Sets the address for XAllocations

Requires admin privileges and a non-zero address

Parameters

Name	Type	Description
xAllocationAddress	address	The new address to set for XAllocations

setVote2EarnAddress

function setVote2EarnAddress(address vote2EarnAddress) public virtual

Sets the address for Vote2Earn allocations

Requires admin privileges and a non-zero address

Parameters

Name	Type	Description
vote2EarnAddress	address	The new address to set for Vote2Earn

setTreasuryAddress

function setTreasuryAddress(address treasuryAddress) public virtual

Sets the address for the Treasury

Requires admin privileges and a non-zero address

Parameters

Name	Type	Description
treasuryAddress	address	The new address to set for the Treasury

setCycleDuration

function setCycleDuration(uint256 _cycleDuration) public virtual

Sets the duration of each emission cycle

Requires admin privileges and a duration greater than 0

Parameters

Name	Type	Description
_cycleDuration	uint256	The duration of the cycle in blocks

setXAllocationsDecay

function setXAllocationsDecay(uint256 _decay) public virtual

Sets the decay rate for XAllocations

Requires admin privileges

Parameters

Name	Type	Description
_decay	uint256	Decay rate as a percentage

setVote2EarnDecay

function setVote2EarnDecay(uint256 _decay) public virtual

Sets the decay rate for Vote2Earn allocations

Requires admin privileges

Parameters

Name	Type	Description
_decay	uint256	Decay rate as a percentage

setXAllocationsDecayPeriod

function setXAllocationsDecayPeriod(uint256 _period) public virtual

Sets the number of cycles after which the XAllocations decay rate is applied

Requires admin privileges and a period greater than 0

Parameters

Name	Type	Description
_period	uint256	Number of cycles

setVote2EarnDecayPeriod

function setVote2EarnDecayPeriod(uint256 _period) public virtual

Sets the number of cycles after which the Vote2Earn decay rate is applied

Requires admin privileges and a period greater than 0

Parameters

Name	Type	Description
_period	uint256	Number of cycles

setTreasuryPercentage

function setTreasuryPercentage(uint256 _percentage) public virtual

Sets the treasury percentage allocation

The treasury percentage is a value between 0 and 10000, scaled by 100 to allow fractional percentages (87.5% for example) Requires admin privileges

Parameters

Name	Type	Description
_percentage	uint256	Treasury percentage (scaled by 100)

setMaxVote2EarnDecay

function setMaxVote2EarnDecay(uint256 _maxVote2EarnDecay) public virtual

Sets the maximum decay rate for Vote2Earn allocations

Requires admin privileges and a decay rate between 0 and 100

Parameters

Name	Type	Description
_maxVote2EarnDecay	uint256	Maximum decay rate as a percentage

setXAllocationsGovernorAddress

function setXAllocationsGovernorAddress(address _xAllocationsGovernor) public

Sets the address for the XAllocations Governor

Requires that the voting period of the governor is less than the cycle duration Requires admin privileges and a non-zero address

Parameters

Name	Type	Description
_xAllocationsGovernor	address	The new XAllocations Governor address