ISTOStaking
Author: luoyhang003
Interface for the STO staking contract used in the Genesis Expedition event.
This interface defines:
- Locking STO to earn Hammers, Raw Stones, and Golden Stones
- Time-indexed unlocking mechanism
- View helpers for lock entries, unlockable amounts, and price configurations STO is locked for 70 days before becoming withdrawable.
Functions
lockFor
Locks STO for hammers and raw stones in a single transaction.
_hammersand_rawStonesdetermine how much STO is required- System distributes resources accordingly
function lockFor(uint256 _hammers, uint256 _rawStones, address _referrer) external;
Parameters
| Name | Type | Description |
|---|---|---|
_hammers | uint256 | Number of hammers to purchase via locking. |
_rawStones | uint256 | Number of raw stones to purchase via locking. |
_referrer | address | Optional referral address. |
lockForHammers
Locks STO exclusively for hammers.
function lockForHammers(uint256 _amount, address _referrer) external;
Parameters
| Name | Type | Description |
|---|---|---|
_amount | uint256 | Number of hammers to purchase. |
_referrer | address | Optional referral address. |
lockForRawStones
Locks STO exclusively for raw stones.
function lockForRawStones(uint256 _amount, address _referrer) external;
Parameters
| Name | Type | Description |
|---|---|---|
_amount | uint256 | Number of raw stones to purchase. |
_referrer | address | Optional referral address. |
unlock
Unlocks a specific lock entry after maturity.
Unlock is allowed only when event has ended and the entry has matured.
function unlock(uint256 _lockIndex) external;
Parameters
| Name | Type | Description |
|---|---|---|
_lockIndex | uint256 | Index of the lock entry to unlock. |
unlockAll
Unlocks all matured lock entries at once.
Stops iterating when an entry is not yet matured.
function unlockAll() external;
getUnlockableAmount
Returns the total STO amount that is currently withdrawable by a user.
A lock becomes unlockable after: END_TIME + (timeIndex * 1 day).
function getUnlockableAmount(address _player) external view returns (uint256 unlockableAmount_);
Parameters
| Name | Type | Description |
|---|---|---|
_player | address | Address querying unlockable STO. |
Returns
| Name | Type | Description |
|---|---|---|
unlockableAmount_ | uint256 | Amount of STO eligible for unlocking. |
getTotalLockedAmount
Returns total STO locked by a player (including un-matured entries).
function getTotalLockedAmount(address _player) external view returns (uint256 lockedAmount_);
Parameters
| Name | Type | Description |
|---|---|---|
_player | address | User address. |
Returns
| Name | Type | Description |
|---|---|---|
lockedAmount_ | uint256 | Total STO currently locked. |
getLockEntries
Returns all lock entries for a player.
function getLockEntries(address _player) external view returns (LockEntry[] memory lockEntries_);
Parameters
| Name | Type | Description |
|---|---|---|
_player | address | The user whose lock entries are queried. |
Returns
| Name | Type | Description |
|---|---|---|
lockEntries_ | LockEntry[] | Dynamic array of LockEntry structs. |
getLockEntries
Returns a paginated slice of a user's lock entries.
Reverts if _start + _limit exceeds total entries.
function getLockEntries(address _player, uint256 _start, uint256 _limit)
external
view
returns (LockEntry[] memory lockEntries_);
Parameters
| Name | Type | Description |
|---|---|---|
_player | address | User address. |
_start | uint256 | Starting index. |
_limit | uint256 | Number of entries to return. |
Returns
| Name | Type | Description |
|---|---|---|
lockEntries_ | LockEntry[] | Array slice of LockEntry records. |
getLockEntryLength
Returns total number of lock entries created by a player.
function getLockEntryLength(address _player) external view returns (uint256 length_);
Parameters
| Name | Type | Description |
|---|---|---|
_player | address | User address. |
Returns
| Name | Type | Description |
|---|---|---|
length_ | uint256 | Number of lock entries. |
getLastUnlockIndex
Returns the player's last processed unlock index.
Used internally to track which entries have been unlocked already.
function getLastUnlockIndex(address _player) external view returns (uint256 index_);
Parameters
| Name | Type | Description |
|---|---|---|
_player | address | User address. |
Returns
| Name | Type | Description |
|---|---|---|
index_ | uint256 | Last unlocked index (exclusive). |
getMintedRawStones
Returns the amount of raw stones minted for a specific player on a given day.
The timestamp parameter is normalized to the corresponding UTC-0 day boundary using floor-to-day logic before querying storage. The returned value represents only the raw stones minted on that day, not the cumulative total. This function is intended for off-chain indexing (e.g., Subgraph) and historical reward analysis.
function getMintedRawStones(address _player, uint256 _timestamp) external view returns (uint256 _amount);
Parameters
| Name | Type | Description |
|---|---|---|
_player | address | The address of the player to query. |
_timestamp | uint256 | Any timestamp within the target day (will be floored to UTC-0). |
Returns
| Name | Type | Description |
|---|---|---|
_amount | uint256 | The number of raw stones minted for the player on the specified day. |
Events
TokenLockedForHammer
Emitted when a player locks STO for hammers.
event TokenLockedForHammer(address indexed player, address indexed token, uint256 amount);
Parameters
| Name | Type | Description |
|---|---|---|
player | address | Address performing the lock. |
token | address | The STO token address. |
amount | uint256 | Amount of STO locked. |
TokenLockedForRawStone
Emitted when a player locks STO for raw stones.
event TokenLockedForRawStone(address indexed player, address indexed token, uint256 amount);
Parameters
| Name | Type | Description |
|---|---|---|
player | address | Address performing the lock. |
token | address | The STO token address. |
amount | uint256 | Amount of STO locked. |
TokenUnlocked
Emitted when locked STO becomes unlocked and is withdrawn.
event TokenUnlocked(address indexed player, address indexed token, uint256 amount);
Parameters
| Name | Type | Description |
|---|---|---|
player | address | The user unlocking STO. |
token | address | The STO token address. |
amount | uint256 | Amount unlocked. |
SetHammerPrice
Emitted when the STO -> Hammer conversion price changes.
event SetHammerPrice(uint256 oldPrice, uint256 newPrice);
Parameters
| Name | Type | Description |
|---|---|---|
oldPrice | uint256 | Previous price. |
newPrice | uint256 | New price. |
SetRawStonePrice
Emitted when the STO -> Raw Stone conversion price changes.
event SetRawStonePrice(uint256 oldPrice, uint256 newPrice);
Parameters
| Name | Type | Description |
|---|---|---|
oldPrice | uint256 | Previous price. |
newPrice | uint256 | New price. |
SetGoldenStonePrice
Emitted when the STO -> Golden Stone conversion price changes.
event SetGoldenStonePrice(uint256 oldPrice, uint256 newPrice);
Parameters
| Name | Type | Description |
|---|---|---|
oldPrice | uint256 | Previous price. |
newPrice | uint256 | New price. |
SetMaxDailyRawStoneMintAmount
Emitted when the maximum daily raw stone mint limit is updated.
event SetMaxDailyRawStoneMintAmount(uint256 oldAmount, uint256 newAmount);
Parameters
| Name | Type | Description |
|---|---|---|
oldAmount | uint256 | The previous maximum daily raw stone mint amount. |
newAmount | uint256 | The new maximum daily raw stone mint amount. |
Structs
LockEntry
Represents a time-indexed STO lock entry.
- timeIndex: (timestamp / 1 days) - startTimeIndex, representing day offset
- lockedAmount: amount of STO locked on this day
struct LockEntry {
uint256 timeIndex;
uint256 lockedAmount;
}
Enums
LOCK_TYPE
Defines lock type used during locking operations.
LOCK_FOR_HAMMER: lock STO to receive hammers LOCK_FOR_RAW_STONE: lock STO to receive raw stones
enum LOCK_TYPE {
LOCK_FOR_HAMMER,
LOCK_FOR_RAW_STONE
}