PopCoinWallet.abi.json

Overview

This file defines the Application Binary Interface (ABI) for the PopCoinWallet smart contract. It specifies the contract's version, header details, fields (state variables), and the set of callable functions along with their inputs and outputs. The ABI facilitates the interaction between the smart contract and clients or other contracts by providing a standardized interface for invocation and data exchange.

The contract appears to manage a wallet system related to a "PopitGame" and a "popcoinroot" token root address. It handles operations such as adding values, activating entities, setting readiness flags, deleting candidates, and retrieving contract details. The fields include ownership information, readiness status, mappings for candidates and associated values, and deployment tracking.

ABI Structure and Components

ABI Meta Information

ABI version: 2 — Specifies the ABI format version.
Contract version: "2.4" — Indicates the implementation version of the contract.
Header: ["pubkey", "time", "expire"] — These headers define system-level parameters required in messages calling the contract: public key, timestamp, and expiration time.

Fields (State Variables)

Field Name	Type	Initialization	Description
`_pubkey`	`uint256`	true	Public key associated with the contract for authentication.
`_timestamp`	`uint64`	false	Timestamp for contract-related timing purposes.
`_constructorFlag`	`bool`	false	Flag indicating if the constructor has been executed.
`_popcoinroot`	`address`	false	Address of the popcoin root token associated with this wallet.
`_name`	`string`	true	Name identifier of the wallet.
`_owner`	`address`	true	Owner address of the wallet.
`_root`	`address`	false	Address of the root contract or entity.
`_value`	`uint64`	false	Numeric value associated with the wallet (likely token balance or stake).
`_popits_candidate`	`map(uint256,uint64)`	false	Mapping of candidate IDs to associated values, representing potential candidates.
`_popits_mbi`	`map(uint256,uint64)`	false	Mapping of candidate IDs to MBI (possibly "metric-based index" or similar) values.
`_popitGame`	`address`	false	Address of the PopitGame contract associated with this wallet.
`_isReady`	`bool`	false	Readiness flag indicating if the wallet is ready for certain operations.
`_root_pubkey`	`uint256`	false	Public key associated with the root contract or entity.
`_mbiCurBase`	`uint64`	false	Base MBI current value used for calculations or state tracking.
`_deployed`	`uint64`	false	Deployment timestamp or version number indicating when the wallet was deployed.

Functions

Each function represents an externally callable method of the contract. The functions predominantly have no return values, except for getDetails and getVersion which return multiple outputs.

constructor

Purpose: Initializes the PopCoinWallet contract with essential parameters.

Inputs:

Parameter	Type	Description
`PopitGameCode`	cell	Code cell representing the PopitGame contract logic or state.
`value`	`uint64`	Initial value or balance to assign to the wallet.
`popcoinroot`	`address`	Address of the popcoin root token contract.
`root_pubkey`	`uint256`	Public key of the root entity or contract.
`mbiCur`	`uint64`	Initial MBI current base value for the wallet.

Outputs: None.

Usage Example:

constructor(PopitGameCode, 1000, popcoinrootAddress, rootPubkeyValue, 500);

deleteCandidate

Purpose: Removes a candidate entry from the _popits_candidate mapping by its index.

Inputs:

Parameter	Type	Description
`index`	`uint256`	Index/key of the candidate to delete.

Outputs: None.

addValue

Purpose: Adds a specified value to a candidate identified by id, updating their associated MBI.

Inputs:

Parameter	Type	Description
`id`	`uint256`	Candidate ID to update.
`value`	`uint64`	Value to add to the candidate.
`mbiCur`	`uint64`	Current MBI value for the operation.

Outputs: None.

addValuePopitGame

Purpose: Similar to addValue, but specifically for candidates related to the PopitGame context.

Inputs:

Parameter	Type	Description
`id`	`uint256`	Candidate ID to update.
`value`	`uint64`	Value to add.
`mbiCur`	`uint64`	Current MBI value for the operation.

Outputs: None.

addValueOld

Purpose: Adds a value to the wallet without specifying a candidate ID (possibly for legacy or general increments).

Inputs:

Parameter	Type	Description
`value`	`uint64`	Value to add.

Outputs: None.

activatePopit

Purpose: Activates a Popit entity with a given ID and root index.

Inputs:

Parameter	Type	Description
`id`	`uint256`	Identifier of the Popit entity.
`indexRoot`	`uint16`	Root index for activation.

Outputs: None.

setReadyPopit

Purpose: Sets the readiness flag for a Popit candidate by index.

Inputs:

Parameter	Type	Description
`index`	`uint256`	Index of the Popit candidate.

Outputs: None.

activate

Purpose: Activates the wallet or contract state, presumably enabling it for operations.

Inputs: None.

Outputs: None.

setReady

Purpose: Sets the _isReady flag to indicate the wallet is ready for use.

Inputs: None.

Outputs: None.

destroy

Purpose: Destroys or deletes the current wallet contract instance.

Inputs: None.

Outputs: None.

destroyRoot

Purpose: Destroys the root contract or entity linked to this wallet.

Inputs: None.

Outputs: None.

destroyNode

Purpose: Destroys a node or sub-entity related to the wallet.

Inputs: None.

Outputs: None.

getDetails

Purpose: Retrieves detailed information about the wallet's state.

Inputs: None.

Outputs:

Output Name	Type	Description
`popcoinroot`	`address`	Address of the popcoin root token.
`name`	`string`	Name of the wallet.
`owner`	`address`	Owner's address.
`value`	`uint64`	Current value associated with the wallet.
`isReady`	`bool`	Readiness status of the wallet.
`popits_candidate`	`map(uint256,uint64)`	Candidate ID to value mappings.
`popits_mbi`	`map(uint256,uint64)`	Candidate ID to MBI mappings.
`deployed`	`uint64`	Deployment timestamp/version.

getVersion

Purpose: Returns the contract version information.

Inputs: None.

Outputs:

Output Name	Type	Description
`value0`	`string`	Primary version string.
`value1`	`string`	Secondary version or sub-version string.

Implementation Details and Algorithms

The contract maintains multiple mappings (_popits_candidate and _popits_mbi) that associate candidate identifiers (uint256) with numeric values (uint64). These mappings likely track candidate stakes or metrics.
The addValue and addValuePopitGame methods allow selective addition of values to candidates, integrating MBI metrics to update or validate the operation.
Activation functions (activate, activatePopit) and readiness setters (setReady, setReadyPopit) manage state transitions of the wallet and its sub-entities.
Destruction functions provide cleanup capabilities at different granularity levels: wallet instance (destroy), root entity (destroyRoot), and node (destroyNode).
The constructor initializes the contract with external references (like PopitGameCode, popcoinroot) and cryptographic keys (root_pubkey), enabling secure interaction and linkage.
The contract's architecture suggests a layered or modular approach where the wallet interacts with game logic (PopitGame) and token root entities (popcoinroot).

Interaction with Other System Components

The _popcoinroot field and related functions indicate interaction with a token root contract, managing token balances or representation.
The _popitGame address and PopitGameCode parameter in the constructor imply integration with a game contract or system, likely managing game-specific logic or candidate entities.
Public keys (_pubkey, _root_pubkey) suggest secure message validation and authorization, ensuring only legitimate callers can modify wallet state.
The readiness and activation workflow integrates with external systems that monitor or trigger state changes based on these flags.
The destroy functions facilitate controlled teardown or migration processes within the broader system.

Visual Diagram: Structure of PopCoinWallet ABI

classDiagram
class PopCoinWallet {
+constructor()
+deleteCandidate()
+addValue()
+addValuePopitGame()
+addValueOld()
+activatePopit()
+setReadyPopit()
+activate()
+setReady()
+destroy()
+destroyRoot()
+destroyNode()
+getDetails()
+getVersion()
-_pubkey: uint256
-_timestamp: uint64
-_constructorFlag: bool
-_popcoinroot: address
-_name: string
-_owner: address
-_root: address
-_value: uint64
-_popits_candidate: map(uint256,uint64)
-_popits_mbi: map(uint256,uint64)
-_popitGame: address
-_isReady: bool
-_root_pubkey: uint256
-_mbiCurBase: uint64
-_deployed: uint64
}

This diagram displays the contract's main functions and fields, reflecting its responsibilities for wallet management, candidate tracking, activation, and lifecycle control.