PopCoinRoot.sol

Overview

PopCoinRoot.sol defines the PopCoinRoot smart contract, which serves as the core contract managing the lifecycle, metadata, and reward distribution of a token system named PopCoin. It handles creation and activation of tokens ("popits"), manages media associated with popits, and coordinates interactions with other contracts, including wallets (PopCoinWallet), games (PopitGame), and verifier contracts (MobileVerifiersContractRoot). The contract ensures secure minting, reward calculations, and state transitions, while controlling access through owner public key checks and sender validations.

Contract: PopCoinRoot

State Variables

• version (string constant): Contract version identifier "1.0.0".

• _code (mapping(uint8 => TvmCell)): Stores code cells for different contract components, e.g., PopCoinWallet.

• _isReady (bool): Indicates whether the contract is activated and ready.

• _popitgamehash (uint256): Hash identifier related to the Popit game.

• _root (address): Address of the root contract or owner.

• _name (string static): Static name identifier for the popcoin root.

• _isPublic (bool): Flag to indicate if public interactions (e.g., adding popits) are allowed.

• _totalSupply (uint128): Total supply of PopCoin tokens.

• _maxPopitIndex (uint16): Tracks the highest index of popits created.

• _popits_value (mapping(uint16 => Popit)): Stores value-related data of popits.

• _popits_media (mapping(uint16 => PopitMedia)): Stores media metadata for popits.

• _popits_candidate (mapping(uint256 => PopitCandidateWithMedia)): Holds candidate popits pending activation.

• _root_pubkey (uint256): Public key of the root owner for authorization checks.

• _description (string): Description of the popcoin root.

• _rewards (uint128): Total rewards available for distribution.

• _basicRewards (uint128): Baseline reward value.

• _popitGameOwner (address): Address of the Popit game owner contract.

• _MBNLst, _TAPLst, _BCLst (uint64[]): Arrays tracking various metrics related to popits (e.g., mint counts, taps).

• _deployed (uint64): Block sequence number when this contract was deployed.

Constructor

constructor (
    TvmCell PopCoinWalletCode,
    uint256 popitgamehash,
    uint16 maxPopitIndex,
    mapping(uint16 => PopitMedia) popits_media,
    string description,
    uint256 root_pubkey,
    bool isPublic,
    uint128 index,
    address popitGameOwner
)

• Initializes the PopCoinRoot contract with wallet code, game hash, media metadata, and other parameters.

• Validates sender and library version.

• Sets up initial state including popits media, owner keys, and description.

• Initializes metric arrays (_MBNLst, _TAPLst, _BCLst) with a fixed size vectorSize.

• Calls popCoinRootDeployed function on the PopitGame contract to notify deployment.

• Parameters:

  • PopCoinWalletCode: Code cell for PopCoinWallet contract.

  • popitgamehash: Identifier hash for Popit game.

  • maxPopitIndex: Maximum index for popits media entries.

  • popits_media: Initial media data mapping.

  • description: Description for this contract instance.

  • root_pubkey: Owner public key for authorization.

  • isPublic: Flag for public access to add popits.

  • index: Used in address calculation for deployment validation.

  • popitGameOwner: Address of the Popit game owner contract.

Public Methods

setIsPublic

function setIsPublic(bool isPublic) public onlyOwnerPubkey(_root_pubkey) accept

• Toggles the _isPublic flag controlling whether public users can add popits.

• Only callable by owner public key.

• Calls ensureBalance() to maintain sufficient contract balance for operations.

setPopitMedia

function setPopitMedia(uint16 index, PopitMedia data) public onlyOwnerPubkey(_root_pubkey) accept

• Updates the media data for a specific popit index.

• Requires contract to be activated (_isReady == true).

• Only callable by owner public key.

addNewPopit

function addNewPopit(string media, optional(uint32) protopopit) public onlyOwnerPubkey(_root_pubkey) accept

• Adds a new popit candidate with associated media and optional prototype popit reference.

• Owner-only function.

• Requires contract readiness.

addNewPopitPublic

function addNewPopitPublic(string media, optional(uint32) protopopit) public accept

• Allows any user to add a new popit candidate if the contract is public (_isPublic == true).

• Requires contract readiness.

Private Methods

newPopit

function newPopit(string media, optional(uint32) protopopit) private

• Internal function to create and store a new popit candidate.

• Generates a unique id by hashing media, prototype, and timestamp.

• Checks that the candidate does not already exist.

• Initializes empty metric arrays for the candidate.

ensureBalance

function ensureBalance() private pure

• Checks if the contract balance is above a threshold (CONTRACT_BALANCE).

• If below, mints tokens to replenish balance.

• Ensures smooth operation of payable functions.

Activation and State Management

activate

function activate(bool isOld) public onlyOwnerPubkey(_root_pubkey) accept

• Activates the contract, setting _isReady to true.

• If not old, triggers sending tap rewards via MobileVerifiersContractRoot.

• Only owner can activate.

activatePopit

function activatePopit(uint256 id, optional(string) media) public view onlyOwnerPubkey(_root_pubkey) accept

• Requests activation of a specific popit candidate by calling sendTapRewardsPopit on the verifier root.

• Requires the candidate to exist.

deleteCandidate

function deleteCandidate(uint256 id) public onlyOwnerPubkey(_root_pubkey) accept

• Deletes a popit candidate by id.

• Only callable by owner.

destroy

function destroy() public view onlyOwnerPubkey(_root_pubkey) accept

• Allows destruction of the contract if it is not activated (_isReady == false).

• Notifies MobileVerifiersContractRoot of the destruction event.

Minting Functions

These functions update the total supply, metrics, and signal readiness to the wallet contracts.

mintValue

function mintValue(address owner, uint64 value, uint64 mbiCur) public senderIs(expectedWalletAddress) accept

• Increases total supply and updates metric lists.

• Signals readiness to the PopCoinWallet contract.

• Validates the sender is the expected wallet address calculated via VerifiersLib.

mintValuePopit

function mintValuePopit(address owner, uint256 dataId, uint64 dataValue, uint64 mbiCur) public senderIs(expectedWalletAddress) accept

• Updates mint counts and values for a popit candidate.

• Requires candidate to exist.

mintValueOld

function mintValueOld(address owner, uint64 value) public senderIs(expectedWalletAddress) accept

• Adds to total supply for older minting logic.

Readiness and Rewards

isReady

function isReady(address owner, uint64 value, address popitGameAddress, uint128 mbi) public senderIs(expectedWalletAddress) accept

• Checks if contract is ready; if so, sets wallet ready state.

• Calculates rewards using gosh.calcmvreward.

• Transfers rewards to the Popit game address.

• Uses encoded metric arrays _TAPLst and _MBNLst.

isReadyPopit

function isReadyPopit(address owner, uint16 indexRoot, uint256 candidateId, uint128 candidateValue, address popitGameAddress, uint128 mbi) public senderIs(expectedWalletAddress) accept

• Similar to isReady but for individual popits.

• Validates candidate ID matches stored media ID.

• Calculates and transfers rewards.

• Cleans up popit value data if all taps are consumed.

Self-Destruction

destroyNode

function destroyNode() public senderIs(address(this)) accept

• Self-destructs the contract.

• Can only be invoked by itself.

Fallback / Receive

receive() external

• Accepts incoming funds.

• If sender is _root and no rewards exist, initializes _rewards and _basicRewards with the received amount.

Getters

getDetails

function getDetails() external view returns (
    address root,
    string name,
    uint128 totalSupply,
    uint16 maxPopitIndex,
    mapping(uint16 => Popit) popits_value,
    mapping(uint16 => PopitMedia) popits_media,
    uint128 rewards,
    mapping(uint256 => PopitCandidateWithMedia) popits_candidate,
    bool isReadyStatus,
    address popitGameOwner,
    string description,
    uint64 deployed
)

• Returns detailed state information of the contract for external querying.

getVersion

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

• Returns a tuple with the contract version and name "PopCoinRoot".

Important Implementation Details

• Access Control: Uses modifiers such as onlyOwnerPubkey and senderIs to enforce strict access control based on public keys and sender addresses, leveraging the VerifiersLib for address computations.

• Popit Candidate Management: Popits are first added as candidates with associated media and optionally a prototype popit. They must be activated before being incorporated into the main popit collection.

• Reward Calculation: Reward distribution uses encoded metric arrays and a reward calculation function (gosh.calcmvreward), ensuring reward limits are respected.

• Balance Management: The ensureBalance function guarantees the contract maintains sufficient balance to cover outgoing calls and operations.

• Interaction with External Contracts: The contract interacts with:

  • PopCoinWallet: to signal readiness and minting.

  • PopitGame: to notify deployment and reward distribution.

  • MobileVerifiersContractRoot: to coordinate tap rewards and popit activation.

• Static Name Storage: The _name field is declared static, likely meaning it is set at deployment time and immutable afterward.

Interactions with Other Contracts

• PopCoinWallet: Wallet contracts for individual owners where tokens are minted and readiness state is set.

• PopitGame: Manages the game logic; receives notifications on deployment and reward transfers.

• MobileVerifiersContractRoot: Handles verification and reward distributions, invoked for tap rewards and popit activations.

• VerifiersLib: Library used for address calculation and version verification to ensure secure and correct contract interactions.

Data Structures Referenced

• Popit: Represents token value and related metrics for a popit.

• PopitMedia: Metadata associated with a popit, including media URL or identifier.

• PopitCandidateWithMedia: Represents an unactivated popit candidate with media and metrics.

• varuint32: Used in currency mappings for reward transfers.

Visual Diagram: Contract Structure and Method Overview

classDiagram
class PopCoinRoot {
-string version
-mapping _code
-bool _isReady
-uint256 _popitgamehash
-address _root
-string static _name
-bool _isPublic
-uint128 _totalSupply
-uint16 _maxPopitIndex
-mapping _popits_value
-mapping _popits_media
-mapping _popits_candidate
-uint256 _root_pubkey
-string _description
-uint128 _rewards
-uint128 _basicRewards
-address _popitGameOwner
-uint64[] _MBNLst
-uint64[] _TAPLst
-uint64[] _BCLst
-uint64 _deployed
+constructor()
+setIsPublic()
+setPopitMedia()
+addNewPopit()
+addNewPopitPublic()
-newPopit()
-ensureBalance()
+activate()
+activatePopit()
+deleteCandidate()
+getTapReward()
+destroy()
+mintValue()
+mintValuePopit()
+mintValueOld()
+isReady()
+isReadyPopit()
+destroyNode()
+getDetails()
+getVersion()
+receive()
}
PopCoinRoot ..> PopCoinWallet : uses
PopCoinRoot ..> PopitGame : notifies
PopCoinRoot ..> MobileVerifiersContractRoot : coordinates
PopCoinRoot ..> VerifiersLib : address verification

Usage Examples

Adding a New Popit by Owner

popCoinRoot.addNewPopit("https://example.com/media1.png", optional.empty());

• Adds a new popit candidate with specified media.

• Requires owner authorization and readiness.

Public Adding a New Popit (if allowed)

popCoinRoot.addNewPopitPublic("https://example.com/media2.png", 123);

• Adds a popit candidate with an optional prototype popit ID.

• Requires readiness and public flag enabled.

Activating the Contract

popCoinRoot.activate(false);

• Activates the contract if not already ready.

• Sends tap rewards via verifier root if new deployment.

Minting Value from Wallet

popCoinRoot.mintValue(ownerAddress, 100, 5);

• Mints 100 tokens for a popit wallet with metric index 5.

• Called only by the calculated wallet address.

Querying Contract Details

(
    address root,
    string memory name,
    uint128 totalSupply,
    uint16 maxPopitIndex,
    mapping(uint16 => Popit) memory popits_value,
    mapping(uint16 => PopitMedia) memory popits_media,
    uint128 rewards,
    mapping(uint256 => PopitCandidateWithMedia) memory popits_candidate,
    bool isReadyStatus,
    address popitGameOwner,
    string memory description,
    uint64 deployed
) = popCoinRoot.getDetails();

• Retrieves all major contract state data for external inspection.

References to Related Topics

• Modifiers used for access control and sender verification.

• VerifiersLib for cryptographic verification and address calculation.

• Popit-related data structures Popit, PopitMedia, and PopitCandidateWithMedia.

• Interactions with PopCoinWallet and PopitGame contracts, which are part of the token wallet and game logic respectively.

• Reward calculation logic using gosh.calcmvreward (external reward calculation function).

These topics provide foundational knowledge on contract security, verification, and token management mechanisms. For detailed explanations on Modifiers and VerifiersLib, refer to Modifiers and VerifiersLib. The token wallet and game logic contracts are documented in PopCoinWallet and PopitGame.