IGenesisExpedition

Git Source

Author: luoyhang003

Interface for the Genesis Expedition core game contract.

This interface defines:

Core structs for player inventory and GoldenStone mechanics.
Events emitted during forging, GoldenStone operations, lotteries, and admin updates.
Functions for forging, distributing resources, querying state, and validating signatures.

Functions

forge

Forges raw stones into gems using a valid EIP-712 signature.

Validates:

player identity
nonce uniqueness
array length
signature validity
deadline Consumes hammers & raw stones, distributes gems, generates lottery codes.

function forge(
    address _player,
    uint256 _nonce,
    uint256 _amount,
    uint256[] memory _gems,
    uint256 _deadline,
    bytes calldata _signature
) external;

Parameters

Name	Type	Description
`_player`	`address`	Address performing the forge.
`_nonce`	`uint256`	Unique nonce preventing replay.
`_amount`	`uint256`	Raw stones to forge.
`_gems`	`uint256[]`	Gem rewards for each stone.
`_deadline`	`uint256`	Signature expiration timestamp.
`_signature`	`bytes`	EIP-712 signature from master signer.

distributeRawStones

Distributes raw stones to a player.

Only callable by whitelisted staking contracts.

function distributeRawStones(address _player, uint256 _amount) external;

Parameters

Name	Type	Description
`_player`	`address`	Player receiving raw stones.
`_amount`	`uint256`	Amount to distribute.

distributeHammers

Distributes hammers to a player.

Only callable by staking contracts.

function distributeHammers(address _player, uint256 _amount) external;

Parameters

Name	Type	Description
`_player`	`address`	Player receiving hammers.
`_amount`	`uint256`	Amount to distribute.

distributeGoldenStones

Distributes GoldenStones to a player.

Only callable by staking contracts.

function distributeGoldenStones(address _player, uint256 _amount) external;

Parameters

Name	Type	Description
`_player`	`address`	Player receiving GoldenStones.
`_amount`	`uint256`	Amount to distribute.

activateDailyHammerRewards

Activates daily hammer reward accumulation for a player.

Only callable by staking contracts.

function activateDailyHammerRewards(address _player) external;

Parameters

Name	Type	Description
`_player`	`address`	Player whose daily rewards are activated.

getPlayerInventory

Returns the player's stored (non-system) inventory.

function getPlayerInventory(address _player) external view returns (PlayerInventory memory inventory_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.

Returns

Name	Type	Description
`inventory_`	`PlayerInventory`	PlayerInventory struct.

getSystemResources

Returns daily system resources available to the player.

Includes only fresh (non-stored) daily rewards.

function getSystemResources(address _player) external view returns (PlayerInventory memory inventory_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.

Returns

Name	Type	Description
`inventory_`	`PlayerInventory`	System resources for today.

getTotalResources

Returns total resources a player has (stored + daily system).

function getTotalResources(address _player) external view returns (PlayerInventory memory inventory_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.

Returns

Name	Type	Description
`inventory_`	`PlayerInventory`	Aggregated inventory.

getActivatedGoldenStoneAmount

Returns number of activated GoldenStones owned by player.

function getActivatedGoldenStoneAmount(address _player) external view returns (uint256 amount_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.

Returns

Name	Type	Description
`amount_`	`uint256`	Activation count.

getActivatedGoldenStones

Returns all activated GoldenStones for a player.

function getActivatedGoldenStones(address _player) external view returns (GoldenStone[] memory goldenStones_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.

Returns

Name	Type	Description
`goldenStones_`	`GoldenStone[]`	Array of GoldenStone structs.

getActivatedGoldenStones

Returns paginated GoldenStones for a player.

function getActivatedGoldenStones(address _player, uint256 _start, uint256 _limit)
    external
    view
    returns (GoldenStone[] memory goldenStones_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.
`_start`	`uint256`	Start index.
`_limit`	`uint256`	Number of entries.

Returns

Name	Type	Description
`goldenStones_`	`GoldenStone[]`	Array of GoldenStone structs.

getActivatedGoldenStone

Returns a single GoldenStone at index.

function getActivatedGoldenStone(address _player, uint256 _index)
    external
    view
    returns (GoldenStone memory goldenStone_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.
`_index`	`uint256`	GoldenStone index.

Returns

Name	Type	Description
`goldenStone_`	`GoldenStone`	GoldenStone struct.

getHammersPerReferral

Returns number of hammers rewarded per referral.

function getHammersPerReferral() external view returns (uint256);

Returns

Name	Type	Description
`<none>`	`uint256`	hammers Number of hammers per referral.

checkNonce

Checks whether forge nonce is still unused.

function checkNonce(address _player, uint256 _nonce) external view returns (bool valid_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.
`_nonce`	`uint256`	Nonce to query.

Returns

Name	Type	Description
`valid_`	`bool`	True if nonce is unconsumed.

getForgedGems

Returns today's forged gems for player & total forged gems globally.

function getForgedGems(address _player) external view returns (uint256 forged_, uint256 total_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.

Returns

Name	Type	Description
`forged_`	`uint256`	Player's forged gems today.
`total_`	`uint256`	Total forged gems today.

getForgedGems

Returns forged gems for a given UTC day.

function getForgedGems(address _player, uint256 _day) external view returns (uint256 forged_, uint256 total_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.
`_day`	`uint256`	Any timestamp within the desired day.

Returns

Name	Type	Description
`forged_`	`uint256`	Player's forged gems that day.
`total_`	`uint256`	Total forged gems globally that day.

verifyForgeSignature

Verifies whether a signature is a valid forge EIP-712 signature.

function verifyForgeSignature(
    address _player,
    uint256 _nonce,
    uint256 _amount,
    uint256[] memory _gems,
    uint256 _deadline,
    bytes calldata _signature
) external view returns (bool valid_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.
`_nonce`	`uint256`	Nonce in signature.
`_amount`	`uint256`	Raw stones amount.
`_gems`	`uint256[]`	Gem array.
`_deadline`	`uint256`	Signature expiration.
`_signature`	`bytes`	Provided signature.

Returns

Name	Type	Description
`valid_`	`bool`	True if signature is valid and from master signer.

getForgeDigest

Returns EIP-712 digest for Forge message (for off-chain debugging).

function getForgeDigest(
    address _player,
    uint256 _nonce,
    uint256 _amount,
    uint256[] memory _gems,
    uint256 _deadline
) external view returns (bytes32 digest_);

Parameters

Name	Type	Description
`_player`	`address`	Player address.
`_nonce`	`uint256`	Nonce.
`_amount`	`uint256`	Raw stone amount.
`_gems`	`uint256[]`	Gems array.
`_deadline`	`uint256`	Deadline.

Returns

Name	Type	Description
`digest_`	`bytes32`	EIP-712 digest.

Events

GemsForged

Emitted when a player successfully forges gems.

event GemsForged(address indexed player, uint256 gems);

Parameters

Name	Type	Description
`player`	`address`	Address of the forging player.
`gems`	`uint256`	Amount of gems forged.

GoldenStoneActivated

Emitted when a GoldenStone is activated by a player.

event GoldenStoneActivated(address indexed owner, uint256 index, uint256 deadline);

Parameters

Name	Type	Description
`owner`	`address`	GoldenStone owner.
`index`	`uint256`	Index of the GoldenStone.
`deadline`	`uint256`	Activation expiry timestamp.

GoldenStoneTapped

Emitted when a player taps (joins) someone's GoldenStone.

event GoldenStoneTapped(address indexed owner, address indexed player, uint256 index);

Parameters

Name	Type	Description
`owner`	`address`	Owner of the GoldenStone.
`player`	`address`	Player who tapped.
`index`	`uint256`	GoldenStone index.

GoldenStoneForged

Emitted when a GoldenStone is successfully forged.

event GoldenStoneForged(address indexed owner, uint256 index, uint256 participants);

Parameters

Name	Type	Description
`owner`	`address`	Owner of the GoldenStone.
`index`	`uint256`	Index of the GoldenStone.
`participants`	`uint256`	Final participant count.

LotteryGenerated

Emitted once per forged raw stone for each player.

event LotteryGenerated(address indexed player, bytes4 code);

Parameters

Name	Type	Description
`player`	`address`	Address receiving the lottery ticket.
`code`	`bytes4`	4-byte lottery code generated via keccak256.

RawStonesDistributed

Emitted when raw stones are distributed to a player.

event RawStonesDistributed(address indexed player, uint256 amount);

Parameters

Name	Type	Description
`player`	`address`	Player receiving raw stones.
`amount`	`uint256`	Amount distributed.

HammersDistributed

Emitted when hammers are distributed to a player.

event HammersDistributed(address indexed player, uint256 amount);

Parameters

Name	Type	Description
`player`	`address`	Player receiving hammers.
`amount`	`uint256`	Amount distributed.

GoldenStonesDistributed

Emitted when GoldenStones are distributed.

event GoldenStonesDistributed(address indexed player, uint256 amount);

Parameters

Name	Type	Description
`player`	`address`	Player receiving GoldenStones.
`amount`	`uint256`	Amount distributed.

DailyHammerRewardsActivated

Emitted when daily hammer rewards are activated.

event DailyHammerRewardsActivated(address indexed player, uint256 activatedAt);

Parameters

Name	Type	Description
`player`	`address`	Player who activated daily hammer rewards.
`activatedAt`	`uint256`	UTC-day timestamp marking activation.

RawStonesForged

Emitted when raw stones are forged.

event RawStonesForged(address indexed player, uint256 amount, uint256 nonce, uint256 gems);

Parameters

Name	Type	Description
`player`	`address`	Player performing forging.
`amount`	`uint256`	Raw stones forged.
`nonce`	`uint256`	Forge nonce.
`gems`	`uint256`	Total gems earned.

RewardedRawStonesConsumed

Emitted when system daily raw stones are consumed.

event RewardedRawStonesConsumed(address indexed player, uint256 amount);

StoredRawStonesConsumed

Emitted when stored raw stones are consumed.

event StoredRawStonesConsumed(address indexed player, uint256 amount);

RewardedHammersConsumed

Emitted when system daily hammers are consumed.

event RewardedHammersConsumed(address indexed player, uint256 amount);

StoredHammersConsumed

Emitted when stored hammers are consumed.

event StoredHammersConsumed(address indexed player, uint256 amount);

SetStakings

Emitted when staking contract permissions change.

event SetStakings(address indexed staking, bool flag);

Parameters

Name	Type	Description
`staking`	`address`	Address of staking contract.
`flag`	`bool`	True if enabled, false if disabled.

SetMasterSigner

Emitted when master forge signer is updated.

event SetMasterSigner(address indexed oldSigner, address indexed newSigner);

Parameters

Name	Type	Description
`oldSigner`	`address`	Previous signer.
`newSigner`	`address`	New signer.

SetGoldenStoneConfigs

Emitted when GoldenStone config updates occur.

event SetGoldenStoneConfigs(
    uint256 oldDuration,
    uint256 newDuration,
    uint256 oldMinParticipants,
    uint256 newMinParticipants,
    uint256 oldMaxParticipants,
    uint256 newMaxParticipants
);

SetGoldenStoneReward

Emitted when GoldenStone reward settings change.

event SetGoldenStoneReward(uint256 oldReward, uint256 newReward, uint256 oldBps, uint256 newBps);

SetHammersPerReferral

Emitted when per-referral hammer reward is updated.

event SetHammersPerReferral(uint256 oldVal, uint256 newVal);

Structs

PlayerInventory

Represents both stored and system resources of a player.

rawStones: stored raw stones (not including daily system raw stones).
goldenStones: number of GoldenStones owned (not yet activated).
hammers: stored hammers (not including rewarded system hammers).

struct PlayerInventory {
    uint256 rawStones;
    uint256 goldenStones;
    uint256 hammers;
}

GoldenStone

Represents the state of an activated GoldenStone.

deadline: expiration timestamp beyond which it can be auto-forged.
isForged: marks whether the GoldenStone has been forged.
participants: array of participant addresses (owner is always index 0).

struct GoldenStone {
    uint256 deadline;
    bool isForged;
    address[] participants;
}

Keyboard shortcuts