STOStaking

Git Source

Inherits: ISTOStaking, Ownable2Step

Author: luoyhang003

Enables users to lock STO tokens during the Genesis Expedition event to earn Hammers, Raw Stones, and Golden Stones.

• Lock entries are grouped by UTC-0 day (timeIndex).
• STO unlocks gradually after the event ends (END_TIME).
• Golden Stones are distributed using cumulative modulo accounting.
• Integrates with GenesisExpedition for distributing in-game resources.
• Integrates with ReferralRegistry for bonus hammer rewards.

State Variables

DURATION

Duration of the staking event.

uint256 public constant DURATION = 70 days

STO_ADDR

Address of the STO ERC20 token to be staked.

address public immutable STO_ADDR

EXPEDITION_ADDR

GenesisExpedition contract for distributing Hammers, Raw Stones, Golden Stones.

address public immutable EXPEDITION_ADDR

REFERRAL_REGISTRY_ADDR

Referral registry for establishing referrer/referee relationships.

address public immutable REFERRAL_REGISTRY_ADDR

START_TIME

Event start timestamp (UTC-0 aligned).

uint256 public immutable START_TIME

END_TIME

Event end timestamp (START_TIME + DURATION).

uint256 public immutable END_TIME

START_TIME_INDEX

UTC-0 day index corresponding to START_TIME.

uint256 public immutable START_TIME_INDEX

END_TIME_INDEX

UTC-0 day index corresponding to END_TIME.

uint256 public immutable END_TIME_INDEX

stoPerHammer

STO amount required to mint one Hammer.

uint256 public stoPerHammer = 30 * 1e18

stoPerRawStone

STO amount required to mint one Raw Stone.

uint256 public stoPerRawStone = 50 * 1e18

stoPerGoldenStone

STO amount required to mint one Golden Stone.

uint256 public stoPerGoldenStone = 2000 * 1e18

lockEntries

User lock entries, grouped by day index.

mapping(address => LockEntry[]) private lockEntries

totalLocked

Total STO locked per user.

mapping(address => uint256) private totalLocked

lastUnlockIndex

Next unlockable lock index per user.

mapping(address => uint256) private lastUnlockIndex

Functions

onlyEventActive

Ensures a function is only callable while event is active.

Active period: START_TIME <= block.timestamp <= END_TIME.

modifier onlyEventActive() ;

onlyEventEnded

Ensures a function is only callable after event has ended.

modifier onlyEventEnded() ;

constructor

Initializes the STO staking contract.

Start time must be UTC-0 aligned and in the future.

constructor(address _stoAddr, address _expeditionAddr, address _referralRegistryAddr, uint256 _startTime)
    Ownable(msg.sender);

Parameters

lockFor

Locks STO for both Hammers and Raw Stones in a single transaction.

Wrapper around _lockForResources.

function lockFor(uint256 _hammers, uint256 _rawStones, address _referrer) external onlyEventActive;

Parameters

lockForHammers

Locks STO exclusively for hammers.

function lockForHammers(uint256 _amount, address _referrer) external onlyEventActive;

Parameters

lockForRawStones

Locks STO exclusively for raw stones.

function lockForRawStones(uint256 _amount, address _referrer) external onlyEventActive;

Parameters

unlock

Unlocks matured lock entries up to _lockIndex.

• Each lock entry unlocks at: END_TIME_INDEX + entry.timeIndex.
• Reverts if any entry in range has not matured.

function unlock(uint256 _lockIndex) external onlyEventEnded;

Parameters

unlockAll

Unlocks all matured lock entries.

Stops at the first non-mature lock entry.

function unlockAll() external onlyEventEnded;

getTotalLockedAmount

Returns total STO locked by _player.

function getTotalLockedAmount(address _player) external view returns (uint256 lockedAmount_);

Parameters

Returns

getLockEntries

Returns all lock entries for a user.

function getLockEntries(address _player) external view returns (LockEntry[] memory lockEntries_);

Parameters

Returns

getLockEntries

Paginated lock entry query.

function getLockEntries(address _player, uint256 _start, uint256 _limit)
    external
    view
    returns (LockEntry[] memory lockEntries_);

Parameters

Returns

getLockEntryLength

Returns total number of lock entries for a user.

function getLockEntryLength(address _player) external view returns (uint256 length_);

Parameters

Returns

getLastUnlockIndex

Returns the next unlockable lock index.

function getLastUnlockIndex(address _player) external view returns (uint256 index_);

Parameters

Returns

getUnlockableAmount

Computes how much STO is unlockable at current time.

function getUnlockableAmount(address _player) external view returns (uint256 unlockableAmount_);

Parameters

Returns

setHammerPrice

Updates STO price per Hammer.

function setHammerPrice(uint256 _stoPerHammer) external onlyOwner;

Parameters

setRawStonePrice

Updates STO price per Raw Stone.

function setRawStonePrice(uint256 _stoPerRawStone) external onlyOwner;

Parameters

setGoldenStonePrice

Updates STO price per Golden Stone.

function setGoldenStonePrice(uint256 _stoPerGoldenStone) external onlyOwner;

Parameters

_onlyEventActive

Ensures event is active.

function _onlyEventActive() internal view;

_onlyEventEnded

Ensures event has ended.

function _onlyEventEnded() internal view;

_bindReferral

Binds referee–referrer relationship.

function _bindReferral(address _referee, address _referrer) internal returns (bool);

Parameters

Returns

_lockForResources

Core lock logic for Hammers and Raw Stones.

Also distributes Golden Stones and applies referral rewards.

function _lockForResources(address _player, address _referrer, uint256 _hammers, uint256 _rawStones) internal;

Parameters

_addNewLockEntry

Adds STO lock entry for the current UTC-0 day.

Aggregates multiple locks in the same day.

function _addNewLockEntry(address _player, uint256 _amount) internal;

Parameters