VerifiersLib.sol

Overview

VerifiersLib.sol is a Solidity library designed to provide utility functions for calculating deterministic addresses and composing state initialization data for various smart contracts within the system. The library supports contracts such as PopitGame, PopCoinWallet, PopCoinRoot, Multifactor, NameIndex (Indexer), and Boost. It leverages the TON Virtual Machine (TVM) specifics for creating TvmCell objects for contract code and state initialization, and for generating addresses by hashing these state initializations.

Additionally, the library includes utility functions for validating string names and computing efficient mathematical operations such as integer logarithm base 2 (log2).

This library plays a critical role in the contract deployment process by ensuring addresses are computed off-chain in a deterministic manner, allowing for pre-calculation of contract addresses before deployment.

Detailed API Documentation

Constants

• string constant versionLib = "1.0.0";
  Library version identifier used as part of the code salt in contract code generation.

Address Calculation and State Initialization Functions

For each supported contract type, the library provides a trio of functions:

1. calculate<Contract>Address: Computes the deterministic contract address based on the encoded state initialization.

2. composeStateInit: Prepares the state initialization cell, encoding contract code and variable initializers.

3. buildCode: Generates the contract code cell with embedded version and relevant parameters used as a salt.

1. PopitGame Contract

• calculatePopitGameAddress(TvmCell code, address root, address owner) returns (address)
  Computes the address for a PopitGame contract.

• composePopitGameStateInit(TvmCell code, address root, address owner) returns (TvmCell)
  Encodes the state initialization cell for PopitGame, including owner as a variable initializer.

• buildPopitGameCode(TvmCell originalCode, address root) returns (TvmCell)
  Builds the contract code cell for PopitGame, embedding the library version and root address as salt.

Usage example:

address popitGameAddr = VerifiersLib.calculatePopitGameAddress(codeCell, rootAddr, ownerAddr);

2. PopCoinWallet Contract

• calculatePopCoinWalletAddress(TvmCell code, uint256 PopitGamehash, address root, string name, address owner) returns (address)
  Computes the address for a PopCoinWallet contract.

• composePopCoinWalletStateInit(TvmCell code, uint256 PopitGamehash, address root, string name, address owner) returns (TvmCell)
  Prepares the state initialization cell with name and owner variables.

• buildPopCoinWalletCode(TvmCell originalCode, address root, uint256 PopitGamehash) returns (TvmCell)
  Generates the code cell salted with version, root address, and PopitGamehash.

3. PopCoinRoot Contract

• calculatePopCoinRootAddress(TvmCell code, address root, string name) returns (address)
  Determines the address for a PopCoinRoot contract.

• composePopCoinRootStateInit(TvmCell code, address root, string name) returns (TvmCell)
  Encodes state initialization with name variable.

• buildPopCoinRootCode(TvmCell originalCode, address root) returns (TvmCell)
  Builds code cell salted with version and root.

4. Multifactor Contract

• calculateMultifactorAddress(TvmCell code, uint256 pubkey, address root) returns (address)
  Computes the address for a Multifactor contract.

• composeMultifactorStateInit(TvmCell code, uint256 pubkey, address root) returns (TvmCell)
  Prepares state initialization with _owner_pubkey.

• buildMultifactorCode(TvmCell originalCode, address root) returns (TvmCell)
  Constructs code cell salted only with root (no version).

5. Indexer Contract (NameIndex)

• calculateIndexerAddress(TvmCell code, string name) returns (address)
  Computes the address for a NameIndex contract.

• composeIndexerStateInit(TvmCell code, string name) returns (TvmCell)
  Encodes state initialization with _name.

• buildIndexerCode(TvmCell originalCode) returns (TvmCell)
  Builds code cell salted with version only.

6. Boost Contract

• calculateBoostAddress(TvmCell code, address popitgame, address root) returns (address)
  Computes the address for a Boost contract.

• composeBoostStateInit(TvmCell code, address popitgame, address root) returns (TvmCell)
  Encodes state initialization with _popitGame.

• buildBoostCode(TvmCell originalCode, address root) returns (TvmCell)
  Builds code cell salted with version and root.

Utility Functions

log2(uint256 x) returns (uint64 n)

Computes the integer base-2 logarithm of x using bit-shifting.
Parameters:

• x: The input unsigned integer.
  Returns:

• n: The highest power of 2 less than or equal to x.

Implementation details:
This function uses a sequence of right bit-shifts to efficiently find the position of the highest set bit.

checkName(string name) returns (bool)

Validates a string name to ensure it meets specific character and length constraints suitable for contract or user naming.

Parameters:

• name: The string to validate.

Returns:

• true if the name is valid according to rules, false otherwise.

Validation rules:

• Length must be between 1 and 39 characters.

• Allowed characters: lowercase a-z, digits 0-9.

• Underscore _ and hyphen - allowed only if not repeated consecutively and not as the first character.

Implementation Details and Algorithms

• Salted Code Cells:
  The library uses abi.encode to create salt data containing the library version, root addresses, and other parameters. This salt is applied to the original contract code using abi.setCodeSalt. This approach ensures that each contract's code is uniquely identifiable and immutable per its deployment parameters.

• Deterministic Address Calculation:
  Addresses are calculated using the hash of the state initialization cell (tvm.hash(s1)) combined with a workchain prefix (0), using address.makeAddrStd. This allows off-chain address pre-computation and ensures no collisions for contracts with different initialization parameters.

• Name Validation:
  The checkName function performs a byte-wise inspection of the string to enforce naming rules, which are critical for contracts like NameIndex that rely on unique and valid names.

• Logarithm Calculation:
  The log2 function uses a binary search style approach with bit-shifts to calculate the integer logarithm base 2 in O(log n) time.

Interaction with Other Contracts and Files

• Imports:
  The library imports contracts PopitGame.sol, PopCoinRoot.sol, Mvmultifactor.sol, Indexer.sol, and Boost.sol. These imports define the contracts for which the library generates addresses and state initializations.

• Usage Context:
  This library is intended to be used by deployment scripts or other contracts that require the ability to pre-calculate addresses and prepare state initialization for the listed contracts before actual deployment or interaction.

• Dependency on TVM Types and Functions:
  Utilizes TVM-specific types like TvmCell and functions like tvm.hash and address.makeAddrStd which are essential for low-level contract code manipulation and address computation.

Visual Diagram: Structure of VerifiersLib.sol

flowchart TB
A[VerifiersLib]
subgraph AddressCalculationFunctions
direction TB
PGAddress[calculatePopitGameAddress]
PCWAddress[calculatePopCoinWalletAddress]
PCRAddress[calculatePopCoinRootAddress]
MFAddress[calculateMultifactorAddress]
IDXAddress[calculateIndexerAddress]
BSTAddress[calculateBoostAddress]
end
subgraph StateInitComposers
direction TB
PGState[composePopitGameStateInit]
PCWState[composePopCoinWalletStateInit]
PCRState[composePopCoinRootStateInit]
MFState[composeMultifactorStateInit]
IDXState[composeIndexerStateInit]
BSTState[composeBoostStateInit]
end
subgraph CodeBuilders
direction TB
PGCode[buildPopitGameCode]
PCWCode[buildPopCoinWalletCode]
PCRCode[buildPopCoinRootCode]
MFCode[buildMultifactorCode]
IDXCode[buildIndexerCode]
BSTCode[buildBoostCode]
end
subgraph UtilityFunctions
log2Func[log2]
checkNameFunc[checkName]
end
A --> AddressCalculationFunctions
A --> StateInitComposers
A --> CodeBuilders
A --> UtilityFunctions
AddressCalculationFunctions --> StateInitComposers
StateInitComposers --> CodeBuilders

Notes on Specific Contracts Referenced

• PopitGame: A core game contract likely managing game state and ownership.

• PopCoinWallet: Token wallet contract linked to a PopitGame instance.

• PopCoinRoot: Root contract of the token system representing a token type.

• Multifactor: Possibly a multi-factor authentication or multi-signature contract.

• NameIndex (Indexer): Contract for indexing or managing string-based names.

• Boost: Contract related to boosting or enhancing game functionality, linked to PopitGame.

For further details on these contracts' internal mechanics and their relationships, refer to their respective contract documentation.

Usage Example (PopitGame Address Calculation)

TvmCell popitGameCode = ... ; // precompiled code cell for PopitGame
address rootAddress = 0x123...;
address ownerAddress = 0xabc...;

address calculatedAddress = VerifiersLib.calculatePopitGameAddress(popitGameCode, rootAddress, ownerAddress);

This calculates the on-chain address where a PopitGame contract would be deployed with the specified parameters.

This library is fundamental for deterministic contract deployment and safe initialization practices within the system.