ISTOStaking

Git Source

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.

_hammers and _rawStones determine 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).

Events

TokenLocked

Emitted when a player locks STO for specific game resources.

event TokenLocked(address indexed player, address indexed token, uint256 amount, LOCK_TYPE lockFor);

Parameters

Name	Type	Description
`player`	`address`	Address performing the lock.
`token`	`address`	The STO token address.
`amount`	`uint256`	Amount of STO locked.
`lockFor`	`LOCK_TYPE`	Resource type the STO is locked to obtain.

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.

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
}

Keyboard shortcuts