IShareXKeysStaking
Title: ShareX Keys Staking Interface
Author: ShareX Team
Staking interface for ShareX Keys Series ERC1155 NFTs with reward distribution The ShareX Keys Staking system allows users to stake their ShareX Keys Series NFTs to earn rewards based on staking duration and amount. The system supports three token types:
- ESSENTIA (ID: 0): Essential access keys for basic functionality
- MAGNA (ID: 1): Enhanced access keys with additional privileges
- NOVA (ID: 2): Premium access keys with full ecosystem access Key Features:
- Individual and batch staking/unstaking operations for gas efficiency
- Rewards accumulation based on staked amounts and time
- Emergency functions for admin control and user protection
- Upgradeable proxy pattern for future enhancements
- Gas-optimized operations using RareSkills patterns Security Considerations:
- All administrative functions require DEFAULT_ADMIN_ROLE
- Reentrancy protection on all state-changing functions
- Proper reward calculations to prevent over/under-distribution
- Emergency pause functionality for critical situations
- Reward debt mechanism prevents reward manipulation Usage Example:
// Stake individual tokens
stakingContract.stake(0, 5); // Stake 5 ESSENTIA tokens
stakingContract.stake(1, 2); // Stake 2 MAGNA tokens
// Batch operations for gas efficiency
stakingContract.stakeAll(); // Stake all available tokens
stakingContract.unstakeAll(); // Unstake all staked tokens
// Reward management
stakingContract.claimRewards(); // Claim accumulated rewards
// View staking information
StakingInfo memory info = stakingContract.getStakingInfo(user, 0);
// info.stakedAmount, info.pendingRewards, info.lastStakedTime
Functions
stake
Stake a specific amount of tokens for a specific token type
Gas-optimized staking with comprehensive validation and reward updates
function stake(uint256 tokenId, uint256 amount) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The token type to stake (0=ESSENTIA, 1=MAGNA, 2=NOVA) |
amount | uint256 | Number of tokens to stake Requirements: - tokenId must be valid (0, 1, or 2) - amount must be greater than 0 - User must own sufficient tokens in ShareX Keys Series contract - Contract must not be paused - Updates rewards before changing stake amounts Emits: ShareXStakingStaked event |
unstake
Unstake a specific amount of tokens for a specific token type
Gas-optimized unstaking with reward calculation and token transfer
function unstake(uint256 tokenId, uint256 amount) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The token type to unstake (0=ESSENTIA, 1=MAGNA, 2=NOVA) |
amount | uint256 | Number of tokens to unstake Requirements: - tokenId must be valid (0, 1, or 2) - amount must be greater than 0 - User must have sufficient staked tokens of the specified type - Contract must not be paused - Updates rewards before changing stake amounts Emits: ShareXStakingUnstaked event |
stakeAll
Stake all available tokens across all types for the caller
Batch staking operation for gas efficiency and user convenience Gas-optimized batch staking that:
- Automatically detects which tokens the user owns
- Stakes only tokens with balance > 0
- Uses efficient batch operations for multiple token types
- Achieves 20-30% gas savings compared to individual calls Requirements:
- User must own at least one token across all types
- Contract must not be paused Emits: ShareXStakingBatchStaked event
function stakeAll() external;
unstakeAll
Unstake all staked tokens across all types for the caller
Batch unstaking operation for gas efficiency and user convenience Gas-optimized batch unstaking that:
- Automatically detects which tokens the user has staked
- Unstakes only tokens with staked amount > 0
- Uses efficient batch operations for multiple token types
- Updates rewards for all affected pools Requirements:
- User must have at least one staked token across all types
- Contract must not be paused Emits: ShareXStakingBatchUnstaked event
function unstakeAll() external;
claimRewards
Claim all accumulated rewards for the caller
Calculates and distributes pending rewards across all staked token types Reward calculation includes:
- Time-based rewards for all staked tokens
- Accurate reward debt management
- Gas-optimized calculation across multiple pools Requirements:
- Contract must not be paused
- User must have pending rewards > 0 Emits: ShareXStakingRewardsClaimed event
function claimRewards() external;
getStakingInfo
Get comprehensive staking information for a user and token type
View function providing complete staking status including pending rewards
function getStakingInfo(address account, uint256 tokenId)
external
view
returns (StakingInfo memory info);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address to query staking information for |
tokenId | uint256 | The token type to query (0=ESSENTIA, 1=MAGNA, 2=NOVA) |
Returns
| Name | Type | Description |
|---|---|---|
info | StakingInfo | Complete staking information including current stake and pending rewards The StakingInfo contains: - stakedAmount: Current tokens staked by the user - rewardDebt: Internal value for reward calculation precision - lastStakedTime: Timestamp of user's last staking action - pendingRewards: Rewards currently available for claiming |
getPoolInfo
Get pool configuration and statistics for a specific token type
View function for pool reward parameters and current state
function getPoolInfo(uint256 tokenId) external view returns (PoolInfo memory info);
Parameters
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The token type to query (0=ESSENTIA, 1=MAGNA, 2=NOVA) |
Returns
| Name | Type | Description |
|---|---|---|
info | PoolInfo | Complete pool information including reward rates and total staked The PoolInfo contains: - rewardPerBlock: Rewards distributed per block for this token type - accRewardPerShare: Accumulated rewards per share for precision - lastRewardBlock: Block when rewards were last calculated - totalStaked: Total tokens currently staked in this pool |
getTotalPendingRewards
Get total pending rewards across all token types for a user
Aggregated view of all claimable rewards for gas-efficient querying
function getTotalPendingRewards(address account) external view returns (uint256 totalRewards);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address to calculate total pending rewards for |
Returns
| Name | Type | Description |
|---|---|---|
totalRewards | uint256 | Sum of pending rewards from all staked token types This is a convenience function that: - Calculates pending rewards from all active stakes - Provides single-call access to total claimable amount - Useful for UI/UX displaying total reward balance |
updatePoolRewards
Update reward parameters for a specific token type pool
Admin function to configure reward distribution rates
function updatePoolRewards(uint256 tokenId, uint256 rewardPerBlock) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The token type to configure (0=ESSENTIA, 1=MAGNA, 2=NOVA) |
rewardPerBlock | uint256 | New reward rate per block for this token type Requirements: - Caller must have DEFAULT_ADMIN_ROLE - tokenId must be valid (0, 1, or 2) - Updates pool state before changing parameters Emits: ShareXStakingPoolUpdated event |
emergencyWithdraw
Emergency withdrawal function for users to recover staked tokens
Allows token recovery without reward calculation in emergency situations
function emergencyWithdraw(uint256 tokenId) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The token type to emergency withdraw (0=ESSENTIA, 1=MAGNA, 2=NOVA) Emergency withdrawal: - Bypasses normal reward calculations for faster execution - Available even when contract is paused - Users forfeit pending rewards for immediate token recovery - Intended for emergency situations only Requirements: - User must have staked tokens of the specified type - Can be used even when contract is paused Emits: ShareXStakingEmergencyWithdrawal event |
burnAllTokens
Burn all tokens (staked and owned) for a specific address
Admin function to burn all tokens belonging to a user
function burnAllTokens(address account) external;
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address whose tokens should be burned This function: - Burns all staked tokens from the staking contract - Burns all owned tokens from the user's wallet - Updates pool state and user stakes accordingly - Forfeits any pending rewards for the burned tokens Requirements: - Caller must have DEFAULT_ADMIN_ROLE - Account must have tokens to burn (either staked or owned) Emits: ShareXStakingTokensBurned event |
shareXKeys
Get the ShareX Keys Series contract address used for staking
View function to verify contract integration
function shareXKeys() external view returns (address shareXKeys);
Returns
| Name | Type | Description |
|---|---|---|
shareXKeys | address | Address of the ShareX Keys Series ERC1155 contract |
Structs
StakingInfo
Staking information for a user and specific token type
Contains all relevant staking data for reward calculations and user queries
struct StakingInfo {
uint256 stakedAmount;
uint256 rewardDebt;
uint256 lastStakedTime;
uint256 pendingRewards;
}
Properties
| Name | Type | Description |
|---|---|---|
stakedAmount | uint256 | Current amount of tokens staked by the user |
rewardDebt | uint256 | Accumulated reward debt used for reward calculation precision |
lastStakedTime | uint256 | Timestamp of the user's last staking action |
pendingRewards | uint256 | Currently pending rewards available for claim |
PoolInfo
Pool configuration for reward distribution per token type
Contains reward parameters and accumulator state for each staking pool
struct PoolInfo {
uint128 rewardPerBlock;
uint128 accRewardPerShare;
uint64 lastRewardBlock;
uint128 totalStaked;
}
Properties
| Name | Type | Description |
|---|---|---|
rewardPerBlock | uint128 | Rewards distributed per block for this token type |
accRewardPerShare | uint128 | Accumulated rewards per share (scaled by precision factor) |
lastRewardBlock | uint64 | Block number when rewards were last calculated |
totalStaked | uint128 | Total amount of tokens currently staked in this pool |