PopCoinWallet.sol

Overview

PopCoinWallet.sol implements the PopCoinWallet smart contract, a core component managing wallet functionality within the PopCoin ecosystem. This contract handles ownership, value tracking, and interactions with related contracts such as PopCoinRoot and PopitGame. It supports minting tokens, managing candidate "popits" (game-related token-like entities), activating these popits, and lifecycle management including contract destruction.

The wallet tracks balances and candidate popits, interacts with the root contract for minting and readiness confirmations, and communicates with the game contract to synchronize state changes. It enforces permissions tied to the owner and root public keys and ensures operational safety by maintaining a minimum contract balance.

Contract: PopCoinWallet

Properties

Constructor

constructor (
    TvmCell PopitGameCode,
    uint64 value,
    address popcoinroot,
    uint256 root_pubkey,
    uint64 mbiCur
)

• Purpose: Initializes the wallet contract with references to the PopitGame code, initial value, root contract, root public key, and mbi base.

• Parameters:

  • PopitGameCode: TVM cell containing compiled code of the PopitGame contract.

  • value: Initial token value to mint or assign.

  • popcoinroot: Address of the PopCoinRoot contract.

  • root_pubkey: Public key of the root owner for authentication.

  • mbiCur: Current mbi base value for validation.

• Implementation Details:

  • Extracts and verifies static salt data for consistency using abi.codeSalt.

  • Performs validation on the code hash to ensure authenticity.

  • Checks that the constructor caller matches the expected PopitGame address.

  • Initiates minting or readiness signaling depending on the initial value.

  • Notifies the PopitGame contract of deployment.

• Usage Example:

  • Deployed automatically by the PopitGame contract upon wallet creation.

Modifiers and Access Control

• senderIs(address): Ensures the message sender matches the given address.

• onlyOwnerPubkey(uint256): Restricts function execution to the owner holding the specified public key.

• accept: Marks functions as accepting external calls with required gas for execution.

Public & External Methods

deleteCandidate

function deleteCandidate(uint256 index) public senderIs(_owner) accept;

• Purpose: Deletes a candidate popit from internal mappings by its index.

• Parameters:

  • index: Identifier of the candidate popit to remove.

• Usage: Only callable by the wallet owner.

• Effect: Removes candidate popit and associated mbi data.

addValue

function addValue(uint256 id, uint64 value, uint64 mbiCur) public onlyOwnerPubkey(_root_pubkey) accept;

• Purpose: Adds a new candidate popit with specified value and mbi.

• Parameters:

  • id: Identifier for the candidate popit.

  • value: Value associated with the popit.

  • mbiCur: Current mbi value relevant to this popit.

• Usage: Restricted to the owner with the root public key.

• Effect: Stores candidate data and informs the PopitGame contract.

• Errors: Reverts if the candidate ID already exists.

addValuePopitGame

function addValuePopitGame(uint256 id, uint64 value, uint64 mbiCur) public senderIs(_popitGame) accept;

• Purpose: Called by the PopitGame contract to either mint or delete candidate popits.

• Parameters: Same as addValue.

• Behavior: If mbiCur is zero, deletes candidate popit; otherwise requests minting via PopCoinRoot.

addValueOld

function addValueOld(uint64 value) public onlyOwnerPubkey(_root_pubkey) accept;

• Purpose: Adds value to the wallet's total tokens through an older minting method.

• Parameters: value - amount to add.

• Effect: Calls mintValueOld on PopCoinRoot and updates internal _value.

activatePopit

function activatePopit(uint256 id, uint16 indexRoot) public view senderIs(_owner) accept;

• Purpose: Activates a candidate popit, triggering readiness verification.

• Parameters:

  • id: Candidate popit ID.

  • indexRoot: Root index used for verification.

• Preconditions: Contract must be ready (_isReady == true), candidate must exist.

• Effect: Calls isReadyPopit on PopCoinRoot to finalize activation.

setReadyPopit

function setReadyPopit(uint256 index) public senderIs(_popcoinroot) accept;

• Purpose: Marks a candidate popit as ready and updates wallet value.

• Parameters: index of the candidate popit.

• Effect: Adds candidate value to total _value and deletes candidate entries.

activate

function activate() public view senderIs(_owner) accept;

• Purpose: Activates the wallet if not already ready.

• Effect: Calls isReady on PopCoinRoot to signal readiness.

setReady

function setReady() public senderIs(_popcoinroot) accept;

• Purpose: Sets the _isReady flag to true, signaling wallet readiness.

• Caller: Only callable by PopCoinRoot.

destroy

function destroy() public senderIs(_owner) accept;

• Purpose: Self-destructs the wallet contract, sending remaining funds to _popitGame.

• Caller: Only owner.

destroyRoot

function destroyRoot() public onlyOwnerPubkey(_root_pubkey) accept;

• Purpose: Self-destructs the wallet contract, initiated by the root public key owner.

• Effect: Funds sent to _popitGame.

destroyNode

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

• Purpose: Self-destructs the contract by itself with no funds forwarded.

Internal Methods

ensureBalance

function ensureBalance() private pure;

• Purpose: Ensures the contract maintains a minimum balance (CONTRACT_BALANCE).

• Implementation: Calls gosh.mintshellq to mint gas tokens if balance is below threshold.

• Note: This method is used before external calls or state changes to guarantee smooth execution.

Fallback

• receive() external { }

  • Allows the contract to accept plain transfers of value without data.

Getters

getDetails

function getDetails() external view returns(
    address popcoinroot,
    string name,
    address owner,
    uint64 value,
    bool isReady,
    mapping(uint256 => uint64) popits_candidate,
    mapping(uint256 => uint64) popits_mbi,
    uint64 deployed
);

• Purpose: Returns comprehensive wallet state details.

• Returns: All major state variables including mappings of candidate popits.

getVersion

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

• Purpose: Returns the contract version string and contract name ("PopCoinWallet").

Important Implementation Details and Algorithms

• Verification and Security:
  In the constructor, the contract verifies the correctness of the deployed code by decoding abi.codeSalt and matching the PopitGameCode hash. It ensures only the authorized PopitGame contract can deploy it.

• Popit Candidate Management:
  Candidate popits are stored in two mappings: _popits_candidate for values and _popits_mbi for metadata/state. These are added, deleted, and finalized through various functions interacting with the PopitGame and PopCoinRoot contracts.

• Minting Workflow:
  Token minting is handled via calls to PopCoinRoot methods, with different functions for standard minting (mintValue), popit-related minting (mintValuePopit), and legacy minting (mintValueOld).

• Lifecycle Management:
  The contract can be destroyed by the owner or root, forwarding balance to the game contract or self-destructing without forwarding.

• Gas Management:
  The ensureBalance function maintains a minimum balance to prevent execution failures due to insufficient gas.

Interaction with Other Contracts

• PopCoinRoot:
  Central contract managing token minting, readiness state, and verification of popits. The wallet uses it extensively to mint tokens and confirm activation.

• PopitGame:
  The game contract that deploys wallet instances and coordinates popit related events. The wallet notifies it upon deployment and candidate changes.

• Modifiers and VerifiersLib:
  The contract inherits from Modifiers to enforce access control and uses VerifiersLib for versioning and address verification.

Visual Diagram: Class Diagram of PopCoinWallet

classDiagram
class PopCoinWallet {
+string version
+address _popcoinroot
+string _name
+address _owner
+address _root
+uint64 _value
+mapping(uint256 => uint64) _popits_candidate
+mapping(uint256 => uint64) _popits_mbi
+address _popitGame
+bool _isReady
+uint256 _root_pubkey
+uint64 _mbiCurBase
+uint64 _deployed
+constructor()
+deleteCandidate()
+addValue()
+addValuePopitGame()
+addValueOld()
+activatePopit()
+setReadyPopit()
+ensureBalance()
+activate()
+setReady()
+destroy()
+destroyRoot()
+destroyNode()
+receive()
+getDetails()
+getVersion()
}