PopitGame.sol

Overview

PopitGame.sol defines the PopitGame smart contract, which orchestrates the deployment and management of the PopCoin wallets and roots within a blockchain-based game ecosystem. This contract handles the initialization of core components, interactions with wallet contracts, and coordination with auxiliary contracts like Boost. Its primary responsibilities include deploying wallet contracts, managing state variables such as rewards and current mbi (an internal metric), and ensuring sufficient contract balance to operate securely. The smart contract enforces access control primarily through public key verification and sender address validation.

Contract: PopitGame

Properties

• string constant version: The version of the contract, set to "1.0.0".

• mapping(uint8 => TvmCell) _code: Stores the compiled code cells for dependent contracts, indexed by an 8-bit key.

• address static _owner: Immutable owner address set at contract deployment.

• uint64 _mbiCur: Current mbi (metric-based index) used in wallet interactions.

• address _root: Address of the PopCoin root contract.

• uint32 _startTime: Timestamp marking the contract start time.

• uint256 _root_pubkey: Public key of the root, used for owner verification.

• address _boost: Address of the deployed Boost contract.

• uint128 _rewards: Accumulated rewards stored in the contract.

Events

• PopCoinRootReceived(string name): Emitted when a PopCoin root contract is deployed and registered.

• PopCoinWalletReceived(string name): Emitted when a PopCoin wallet contract is deployed and registered.

Constructor

constructor (
    mapping(uint8 => TvmCell) code,
    uint256 root_pubkey,
    uint128 index
)

Description

Initializes the PopitGame contract instance. It verifies the sender, sets essential state variables, and deploys the Boost contract with necessary initialization data.

Parameters

• code: A mapping containing the compiled code cells for the dependent contracts (Boost, PopCoinWallet, PopCoinRoot etc.).

• root_pubkey: The public key of the root owner for authorization checks.

• index: Numeric index used to calculate the expected sender address for deployment security.

Implementation Details

• Extracts salt data from the contract code to verify the library version using VerifiersLib.versionLib.

• Validates the sender address matches an expected pattern derived from a base constant and the given index.

• Deploys the Boost contract by composing its state initialization data through VerifiersLib.composeBoostStateInit.

• Sets the contract's start timestamp and stores passed-in parameters.

Usage Example

mapping(uint8 => TvmCell) codeCells = ...; // Provided compiled code
uint256 rootPubKey = ...; // Owner's root public key
uint128 index = 1;

PopitGame game = new PopitGame(codeCells, rootPubKey, index);

Functions

addValuePopit

function addValuePopit(string name, uint256 id, uint64 value) public view senderIs(...) accept

Adds a specified value to a PopCoin wallet associated with the given name and id.

• Parameters:

  • name: The identifier for the PopCoin wallet.

  • id: Unique identifier of the PopCoin item.

  • value: The amount to add.

• Modifiers: Sender must be the PopCoin wallet address calculated from VerifiersLib.

• Behavior: Calls addValuePopitGame on the PopCoinWallet contract with the current mbi value.

• Example:

popitGame.addValuePopit("player1", 12345, 100);

popCoinRootDeployed

function popCoinRootDeployed(string name) public view senderIs(...) accept

Handles the event when a PopCoin root contract is deployed and signals this via an event emission.

• Parameters:

  • name: The name of the PopCoin root contract.

• Modifiers: Sender must be the PopCoin root address calculated from VerifiersLib.

• Behavior: Emits PopCoinRootReceived event to an external address.

• Example:

popitGame.popCoinRootDeployed("mainRoot");

popCoinWalletDeployed

function popCoinWalletDeployed(string name) public view senderIs(...) accept

Handles the event when a PopCoin wallet contract is deployed and signals this via an event emission.

• Parameters:

  • name: The name of the PopCoin wallet.

• Modifiers: Sender must be the PopCoin wallet address calculated from VerifiersLib.

• Behavior: Emits PopCoinWalletReceived event to an external address.

• Example:

popitGame.popCoinWalletDeployed("player1");

ensureBalance (Private)

function ensureBalance() private pure

Ensures the contract maintains a minimum balance defined by CONTRACT_BALANCE. If the balance falls below the threshold, it triggers a mint operation.

• Behavior: Checks balance and calls gosh.mintshellq if necessary.

• Usage: Called internally before operations requiring sufficient funds.

setMbiCur

function setMbiCur(uint64 mbiCur) public senderIs(_boost) accept

Sets the current mbi value, which impacts wallet value updates.

• Parameters:

  • mbiCur: New mbi value to set.

• Modifiers: Caller must be the deployed Boost contract.

• Behavior: Updates the internal _mbiCur variable.

• Example:

boostContract.setMbiCur(42);

deployPopCoinWallet

function deployPopCoinWallet(string name, uint64 value) public view onlyOwnerPubkey(_root_pubkey) accept

Deploys a new PopCoinWallet contract with an initial value, using the provided name as an identifier.

• Parameters:

  • name: The wallet name.

  • value: Initial value to assign to the wallet.

• Modifiers: Caller must be the owner with _root_pubkey.

• Behavior:

  • Composes wallet state init using VerifiersLib.

  • Instantiates a new PopCoinWallet contract.

• Example:

popitGame.deployPopCoinWallet("player1", 1000);

deployPopCoinWalletOldTransfer

function deployPopCoinWalletOldTransfer(string name, uint64 value) public view onlyOwnerPubkey(_root_pubkey) accept

Alternate deployment method for a PopCoinWallet, similar to deployPopCoinWallet but without mbi validation.

• Parameters:

  • Same as deployPopCoinWallet.

• Modifiers: Same as deployPopCoinWallet.

• Behavior: Deploys the wallet without requiring _mbiCur to be non-zero.

• Example:

popitGame.deployPopCoinWalletOldTransfer("player1", 1000);

withdraw

function withdraw(uint128 value, address to) public senderIs(_owner)

Withdraws a specified amount of currency from the contract to a specified address.

• Parameters:

  • value: Amount to withdraw.

  • to: Recipient address.

• Modifiers: Caller must be the contract owner.

• Behavior:

  • Checks if the contract balance is sufficient.

  • Transfers funds.

  • Resets mbi value.

  • Calls deleteMbiCur on the Boost contract.

• Example:

popitGame.withdraw(500, recipientAddress);

Fallback / Receive Function

receive() external

Handles incoming transfers to the contract.

• Behavior:

  • Accepts incoming funds.

  • If sender is not the owner, increments _rewards by the received currency amount.

• Usage: Automatically invoked on plain transfers to the contract.

Getters

getPopCoinWalletAddress

function getPopCoinWalletAddress(string name) external view returns(address)

Calculates and returns the address of a PopCoinWallet contract for a given name.

• Parameters:

  • name: Wallet identifier.

• Returns: The calculated address of the PopCoinWallet.

• Example:

address walletAddr = popitGame.getPopCoinWalletAddress("player1");

getDetails

function getDetails() external view returns(
    address owner,
    address root,
    uint32 startTime,
    uint64 mbiCur,
    address boost,
    uint128 rewards,
    uint128 minstake
)

Returns comprehensive details about the current state of the PopitGame contract.

• Returns:

  • owner: Contract owner address.

  • root: PopCoin root address.

  • startTime: Contract start timestamp.

  • mbiCur: Current mbi value.

  • boost: Boost contract address.

  • rewards: Accumulated rewards.

  • minstake: Calculated minimum stake based on rewards and elapsed time using gosh.calcminstakebm.

• Example:

(address owner, , , , , , uint128 minstake) = popitGame.getDetails();

getVersion

function getVersion() external pure returns(string, string)

Returns the contract version and its name.

• Returns: Tuple (version, "PopitGame").

• Example:

(string memory version, string memory name) = popitGame.getVersion();

Implementation Details and Algorithms

• Verification & Security: Uses VerifiersLib to compute and verify addresses for PopCoinWallet and PopCoinRoot contracts, ensuring only authorized contracts interact with this contract.

• Deployment: Contracts are deployed using state initialization computed from the stored code cells, ensuring deterministic addresses and secure initialization.

• Balance Management: Maintains a minimum contract balance (CONTRACT_BALANCE) and automatically mints tokens when below threshold using gosh.mintshellq.

• Boost Integration: Interacts with the Boost contract to manage the mbi value and can instruct the Boost contract to reset mbi through deleteMbiCur.

• Currency Transfer: Uses low-level currency transfer mechanisms with explicit currency ID management (CURRENCIES_ID).

Interaction with Other Contracts

• Boost: Deployed during construction; manages metrics related to mbi and can perform mbi deletion.

• PopCoinWallet: Wallet contracts representing individual player holdings; deployed and managed by PopitGame.

• PopCoinRoot: Root contract of the PopCoin ecosystem; PopitGame listens for its deployment and emits corresponding events.

• VerifiersLib: Provides utility functions for address calculation, version verification, and state initialization composition.

• Modifiers: Provides access control modifiers such as senderIs and onlyOwnerPubkey.

• gosh: Provides currency minting (mintshellq) and minimum stake calculation (calcminstakebm) utilities.

Class Diagram

classDiagram
class PopitGame {
-string version
-mapping(uint8 => TvmCell) _code
-address static _owner
-uint64 _mbiCur
-address _root
-uint32 _startTime
-uint256 _root_pubkey
-address _boost
-uint128 _rewards
+constructor(code, root_pubkey, index)
+addValuePopit(name, id, value)
+popCoinRootDeployed(name)
+popCoinWalletDeployed(name)
-ensureBalance()
+setMbiCur(mbiCur)
+deployPopCoinWallet(name, value)
+deployPopCoinWalletOldTransfer(name, value)
+withdraw(value, to)
+receive()
+getPopCoinWalletAddress(name)
+getDetails()
+getVersion()
}
PopitGame ..> Modifiers : inherits
PopitGame ..> VerifiersLib : uses
PopitGame ..> PopCoinWallet : deploys/calls
PopitGame ..> Boost : deploys/calls