IECOSYSTEM
Interface for the Ecosystem contract that handles airdrops, rewards, burning, partnerships, and secure upgrades
Defines all external functions and events for the Ecosystem contract
Notes:
security-contact: security@nebula-labs.xyz
copyright: Copyright (c) 2025 Nebula Holding Inc. All rights reserved.
Functions
initialize
Initializes the ecosystem contract
Sets up the initial state of the contract, including roles and token supplies
function initialize(address token, address timelockAddr, address multisig) external;Parameters
token
address
Address of the governance token
timelockAddr
address
Address of the timelock controller
multisig
address
Address of the multisig wallet
pause
Pauses all contract operations
Can only be called by accounts with the PAUSER_ROLE
function pause() external;unpause
Resumes all contract operations
Can only be called by accounts with the PAUSER_ROLE
function unpause() external;scheduleUpgrade
Schedules an upgrade to a new implementation
Can only be called by accounts with the UPGRADER_ROLE
function scheduleUpgrade(address newImplementation) external;Parameters
newImplementation
address
Address of the new implementation
cancelUpgrade
Cancels a previously scheduled upgrade
Can only be called by accounts with the UPGRADER_ROLE
function cancelUpgrade() external;upgradeTimelockRemaining
Returns the remaining time before a scheduled upgrade can be executed
Returns 0 if no upgrade is scheduled or timelock has passed
function upgradeTimelockRemaining() external view returns (uint256);Returns
<none>
uint256
The time remaining in seconds
emergencyWithdrawToken
Emergency function to withdraw tokens to the timelock
Can only be called by accounts with the MANAGER_ROLE
function emergencyWithdrawToken(address token) external;Parameters
token
address
The token to withdraw
airdrop
Distributes tokens to multiple recipients
Can only be called by accounts with the MANAGER_ROLE
function airdrop(address[] calldata recipients, uint256 amount) external;Parameters
recipients
address[]
Array of addresses to receive the airdrop
amount
uint256
Amount of tokens each recipient will receive
reward
Rewards a single address with tokens
Can only be called by accounts with the MANAGER_ROLE
function reward(address to, uint256 amount) external;Parameters
to
address
Recipient address
amount
uint256
Amount of tokens to reward
burn
Burns tokens from the reward supply
Can only be called by accounts with the MANAGER_ROLE
function burn(uint256 amount) external;Parameters
amount
uint256
Amount of tokens to burn
addPartner
Creates a vesting contract for a new partner
Can only be called by accounts with the MANAGER_ROLE
function addPartner(address partner, uint256 amount, uint256 cliff, uint256 duration) external;Parameters
partner
address
Address of the partner
amount
uint256
Amount of tokens to vest
cliff
uint256
Cliff period in seconds
duration
uint256
Vesting duration in seconds
cancelPartnership
Cancels a partner's vesting contract
Can only be called by the timelock
function cancelPartnership(address partner) external;Parameters
partner
address
Address of the partner
updateMaxReward
Updates the maximum one-time reward amount
Can only be called by accounts with the MANAGER_ROLE
function updateMaxReward(uint256 newMaxReward) external;Parameters
newMaxReward
uint256
New maximum reward value
updateMaxBurn
Updates the maximum one-time burn amount
Can only be called by accounts with the MANAGER_ROLE
function updateMaxBurn(uint256 newMaxBurn) external;Parameters
newMaxBurn
uint256
New maximum burn value
availableRewardSupply
Returns the available reward supply
Calculates remaining reward tokens
function availableRewardSupply() external view returns (uint256);Returns
<none>
uint256
Available tokens in the reward supply
availableAirdropSupply
Returns the available airdrop supply
Calculates remaining airdrop tokens
function availableAirdropSupply() external view returns (uint256);Returns
<none>
uint256
Available tokens in the airdrop supply
availablePartnershipSupply
Returns the available partnership supply
Calculates remaining partnership tokens
function availablePartnershipSupply() external view returns (uint256);Returns
<none>
uint256
Available tokens in the partnership supply
rewardSupply
Gets the total reward supply
function rewardSupply() external view returns (uint256);Returns
<none>
uint256
The total reward supply
maxReward
Gets the maximum reward amount
function maxReward() external view returns (uint256);Returns
<none>
uint256
The maximum reward amount
issuedReward
Gets the total amount of tokens issued as rewards
function issuedReward() external view returns (uint256);Returns
<none>
uint256
The total issued reward amount
burnedAmount
Gets the total amount of tokens burned
function burnedAmount() external view returns (uint256);Returns
<none>
uint256
The total burned amount
maxBurn
Gets the maximum burn amount
function maxBurn() external view returns (uint256);Returns
<none>
uint256
The maximum burn amount
airdropSupply
Gets the total airdrop supply
function airdropSupply() external view returns (uint256);Returns
<none>
uint256
The total airdrop supply
issuedAirDrop
Gets the total amount of tokens issued via airdrops
function issuedAirDrop() external view returns (uint256);Returns
<none>
uint256
The total issued airdrop amount
partnershipSupply
Gets the total partnership supply
function partnershipSupply() external view returns (uint256);Returns
<none>
uint256
The total partnership supply
issuedPartnership
Gets the total amount of tokens issued to partners
function issuedPartnership() external view returns (uint256);Returns
<none>
uint256
The total issued partnership amount
version
Gets the contract version
function version() external view returns (uint32);Returns
<none>
uint32
The current version number
timelock
Gets the timelock address
function timelock() external view returns (address);Returns
<none>
address
The timelock address
vestingContracts
Gets the vesting contract address for a partner
function vestingContracts(address partner) external view returns (address);Parameters
partner
address
The address of the partner
Returns
<none>
address
The vesting contract address
Events
Initialized
Emitted when the contract is initialized
event Initialized(address indexed initializer);Parameters
initializer
address
The address that initialized the contract
AirDrop
Emitted when an airdrop is executed
event AirDrop(address[] indexed winners, uint256 amount);Parameters
winners
address[]
Array of addresses that received the airdrop
amount
uint256
Amount of tokens each address received
Reward
Emitted when a reward is distributed
event Reward(address indexed sender, address indexed recipient, uint256 amount);Parameters
sender
address
The address that initiated the reward
recipient
address
The address that received the reward
amount
uint256
The amount of tokens awarded
Burn
Emitted when tokens are burned
event Burn(address indexed burner, uint256 amount);Parameters
burner
address
The address that initiated the burn
amount
uint256
The amount of tokens burned
AddPartner
Emitted when a new partner is added
event AddPartner(address indexed partner, address indexed vestingContract, uint256 amount);Parameters
partner
address
The address of the partner
vestingContract
address
The address of the partner's vesting contract
amount
uint256
The amount of tokens allocated to the partner
CancelPartnership
Emitted when a partnership is cancelled
event CancelPartnership(address indexed partner, uint256 remainingAmount);Parameters
partner
address
The address of the partner whose contract was cancelled
remainingAmount
uint256
The amount of tokens returned to the timelock
MaxRewardUpdated
Emitted when the maximum reward amount is updated
event MaxRewardUpdated(address indexed updater, uint256 oldValue, uint256 newValue);Parameters
updater
address
The address that updated the maximum reward
oldValue
uint256
The previous maximum reward value
newValue
uint256
The new maximum reward value
MaxBurnUpdated
Emitted when the maximum burn amount is updated
event MaxBurnUpdated(address indexed updater, uint256 oldValue, uint256 newValue);Parameters
updater
address
The address that updated the maximum burn
oldValue
uint256
The previous maximum burn value
newValue
uint256
The new maximum burn value
Upgrade
Emitted when the contract is upgraded
event Upgrade(address indexed upgrader, address indexed newImplementation, uint32 version);Parameters
upgrader
address
The address that performed the upgrade
newImplementation
address
The address of the new implementation
version
uint32
The new version number
UpgradeScheduled
Emitted when an upgrade is scheduled
event UpgradeScheduled(
address indexed sender, address indexed implementation, uint64 scheduledTime, uint64 effectiveTime
);Parameters
sender
address
The address that scheduled the upgrade
implementation
address
The new implementation address
scheduledTime
uint64
The time when the upgrade was scheduled
effectiveTime
uint64
The time when the upgrade can be executed
UpgradeCancelled
Emitted when a scheduled upgrade is cancelled
event UpgradeCancelled(address indexed canceller, address indexed implementation);Parameters
canceller
address
The address that cancelled the upgrade
implementation
address
The implementation address that was cancelled
EmergencyWithdrawal
Emitted when an emergency withdrawal is executed
event EmergencyWithdrawal(address indexed token, uint256 amount);Parameters
token
address
Address of the token withdrawn
amount
uint256
Amount withdrawn
Errors
ValidationFailed
Error thrown for general validation failures
error ValidationFailed(string reason);Parameters
reason
string
Description of the validation failure
UpgradeTimelockActive
Error thrown if you try to upgrade while the timelock is active
error UpgradeTimelockActive(uint256 remainingTime);Parameters
remainingTime
uint256
Time remaining in the timelock period
UpgradeNotScheduled
Thrown when trying to execute an upgrade that wasn't scheduled
error UpgradeNotScheduled();ImplementationMismatch
Thrown when trying to execute an upgrade with wrong implementation
error ImplementationMismatch(address expected, address provided);Parameters
expected
address
The implementation address that was scheduled
provided
address
The implementation address that was attempted
ZeroAddressDetected
Error thrown when a zero address is provided where a non-zero address is required
error ZeroAddressDetected();InvalidAmount
Error thrown when an invalid amount is provided
error InvalidAmount(uint256 amount);Parameters
amount
uint256
The invalid amount that was provided
AirdropSupplyLimit
Error thrown when an airdrop exceeds the available supply
error AirdropSupplyLimit(uint256 requested, uint256 available);Parameters
requested
uint256
The amount of tokens requested for the airdrop
available
uint256
The amount of tokens actually available
GasLimit
Error thrown when too many recipients are provided for an airdrop
error GasLimit(uint256 recipients);Parameters
recipients
uint256
The number of recipients that would exceed gas limits
RewardLimit
Error thrown when a reward exceeds the maximum allowed amount
error RewardLimit(uint256 amount, uint256 maxAllowed);Parameters
amount
uint256
The requested reward amount
maxAllowed
uint256
The maximum allowed reward amount
RewardSupplyLimit
Error thrown when a reward exceeds the available supply
error RewardSupplyLimit(uint256 requested, uint256 available);Parameters
requested
uint256
The requested reward amount
available
uint256
The amount of tokens actually available
BurnSupplyLimit
Error thrown when a burn exceeds the available supply
error BurnSupplyLimit(uint256 requested, uint256 available);Parameters
requested
uint256
The requested burn amount
available
uint256
The amount of tokens actually available
MaxBurnLimit
Error thrown when a burn exceeds the maximum allowed amount
error MaxBurnLimit(uint256 amount, uint256 maxAllowed);Parameters
amount
uint256
The requested burn amount
maxAllowed
uint256
The maximum allowed burn amount
InvalidAddress
Error thrown when an invalid address is provided
error InvalidAddress();PartnerExists
Error thrown when attempting to create a vesting contract for an existing partner
error PartnerExists(address partner);Parameters
partner
address
The address of the partner that already exists
AmountExceedsSupply
Error thrown when an amount exceeds the available supply
error AmountExceedsSupply(uint256 requested, uint256 available);Parameters
requested
uint256
The requested amount
available
uint256
The amount actually available
ExcessiveMaxValue
Error thrown when a maximum value update exceeds allowed limits
error ExcessiveMaxValue(uint256 amount, uint256 maxAllowed);Parameters
amount
uint256
The requested new maximum value
maxAllowed
uint256
The maximum allowed value
InvalidVestingSchedule
Thrown when attempting to set an invalid vesting duration
error InvalidVestingSchedule();ZeroBalance
Error thrown when attempting operations with zero balance
error ZeroBalance();Structs
UpgradeRequest
Structure to track pending upgrades with timelock
struct UpgradeRequest {
address implementation;
uint64 scheduledTime;
bool exists;
}Properties
implementation
address
The address of the new implementation contract
scheduledTime
uint64
The timestamp when the upgrade was scheduled
exists
bool
Boolean flag indicating if an upgrade is currently scheduled
Last updated