Mirror.sol

Overview

Mirror.sol defines the Mirror smart contract, which acts as a critical component within a multifactor verification and game deployment ecosystem. The contract manages deployment and interaction with multiple specialized contracts including multifactor authentication modules, game contracts, token roots, and indexers. It maintains an internal state with references to root contracts, an index, public keys, and code cells for various contract types.

The contract provides administrative functions to update its internal state, ensure operational balance, deploy new contracts related to multifactor verification, games, and token roots, and manage whitelist updates for access control. It is designed with strict access control and validation logic to preserve the integrity and security of the system.

Contract: Mirror

State Variables

• string constant version = "1.0.0";
  Version identifier for the contract.

• address _root;
  Address of the root contract to which this mirror is connected.

• uint128 _index;
  Numeric index identifying this mirror instance, constrained to a maximum value (MAX_MIRROR_INDEX).

• uint256 _rootPubkey;
  Public key associated with the root contract owner, used for authorization.

• mapping(uint8 => TvmCell) _code;
  Stores contract code cells indexed by an identifier, enabling dynamic deployment of various contract types.

Constructor

constructor (
    address root,
    uint128 index,
    uint256 rootPubkey
)

• Parameters:

  • root: The address of the root contract.

  • index: Index number for this mirror (must be within valid range).

  • rootPubkey: Public key of the root owner.

• Functionality:
  Initializes the contract with the root address, index, and root public key. Validates that the index is within the allowed range.

Core Private and Modifier Functions

ensureBalance()

function ensureBalance() private pure

• Purpose:
  Ensures the contract maintains a minimum balance (CONTRACT_BALANCE) by minting tokens if the balance is below the threshold.

• Implementation Detail:
  Calls gosh.mintshellq(CONTRACT_BALANCE) if balance is insufficient. The function is marked pure but interacts with the blockchain state through a special gosh interface.

State Management Functions

setNewIndex

function setNewIndex(uint128 index) public senderIs(address(this)) accept

• Parameters:

  • index: New index value to set.

• Functionality:
  Sets a new _index value after ensuring sufficient contract balance. Restricted to calls originating from the contract itself via the senderIs modifier and requires message acceptance.

setNewCode

function setNewCode(uint8 id, TvmCell code) public senderIs(address(this)) accept

• Parameters:

  • id: Identifier for the contract code type.

  • code: The TvmCell containing the contract code.

• Functionality:
  Updates the _code mapping with new contract code cells. Only callable by the contract itself.

destroyNode

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

• Functionality:
  Self-destructs the contract, releasing all funds to its own address. Restricted to internal calls.

Deployment Functions

deployPopitGame

function deployPopitGame(uint256 pubkey) public view senderIs(VerifiersLib.calculateMultifactorAddress(_code[m_MvMultifactor], pubkey, _root)) accept

• Parameters:

  • pubkey: Public key of the multifactor address to authorize deployment.

• Functionality:
  Deploys a new PopitGame contract initialized with state composed from the provided code cells and root data. The function calculates a multifactor address for validation and uses various code cells to deploy the game contract with an initial balance (FEE_DEPLOY_POPIT_GAME_WALLET).

• Usage Example:

  mirror.deployPopitGame(userPubkey);
  

deployMultifactor

function deployMultifactor(
    string name,
    string zkid,
    bytes proof,
    uint256 epk,
    bytes epk_sig,
    uint64 epk_expire_at,
    bytes jwk_modulus,
    bytes kid,
    uint64 jwk_modulus_expire_at,
    uint8 index_mod_4,
    string iss_base_64,
    string provider,
    string header_base_64,
    uint256 pub_recovery_key,
    bytes pub_recovery_key_sig,
    uint256 jwk_update_key,
    bytes jwk_update_key_sig,
    mapping(uint256 => bytes) root_provider_certificates
) public view accept

• Parameters:
  Various cryptographic and identification parameters for multifactor authentication setup, including keys, signatures, proofs, expiration timestamps, and provider information.

• Functionality:
  Deploys a new multifactor authentication contract after verifying:

  • The caller's public key matches the mirror's index.

  • Validity of names and cryptographic signatures.

  • Proof correctness via gosh.vergrth16.

  • Timing constraints for keys and proofs.

  • No repeated keys among owner, recovery, and update keys.

  After validation, it deploys a NameIndex contract and invokes its isOwner method to finalize multifactor registration.

• Important Algorithm:
  Uses Poseidon hash function and Groth16 verification for zero-knowledge proof validation.

isDeployMultifactor

function isDeployMultifactor(
    string name,
    bool ready,
    string zkid,
    bytes proof,
    uint256 epk,
    bytes epk_sig,
    uint64 epk_expire_at,
    bytes jwk_modulus,
    bytes kid,
    uint64 jwk_modulus_expire_at,
    uint8 index_mod_4,
    string iss_base_64,
    string provider,
    string header_base_64,
    uint256 pub_recovery_key,
    bytes pub_recovery_key_sig,
    uint256 jwk_update_key,
    bytes jwk_update_key_sig,
    mapping(uint256 => bytes) root_provider_certificates,
    uint256 owner_pubkey
) public view senderIs(VerifiersLib.calculateIndexerAddress(_code[m_Indexer], name)) accept

• Parameters:
  Similar to deployMultifactor but includes a ready flag and explicit owner_pubkey.

• Functionality:
  Triggered by the NameIndex contract, it deploys the actual Multifactor contract if the ready flag is true. This function validates the sender to be the indexer address for the given name.

updateWhiteList

function updateWhiteList(uint256 pubkey, uint8 index, string name) public view senderIs(VerifiersLib.calculateMultifactorAddress(_code[m_MvMultifactor], pubkey, _root)) accept

• Parameters:

  • pubkey: Public key of the multifactor address requesting the whitelist update.

  • index: Identifier of the contract type to whitelist.

  • name: User or contract identifier.

• Functionality:
  Updates the whitelist in the multifactor contract by calculating new addresses for different contract types (boost, wallet, game) based on the index. Calls setWhiteList on the multifactor contract with the new address and mirror index.

Token and Game Root Deployment

deployPopCoinRoot

function deployPopCoinRoot(
    string name,
    uint16 maxPopitIndex,
    mapping(uint16 => PopitMedia) popits_media,
    string description,
    bool isPublic,
    address popitGameOwner
) public view onlyOwnerPubkey(_rootPubkey) accept

• Parameters:

  • name: Name for the PopCoin token root.

  • maxPopitIndex: Maximum index allowed for Popit entities.

  • popits_media: Mapping of media associated with Popits.

  • description: Description for the token root.

  • isPublic: Visibility flag.

  • popitGameOwner: Address of the game owner.

• Functionality:
  Deploys a PopCoinRoot contract initialized with the corresponding code, root address, and parameters. Validates that the new root address's modulus matches the mirror index before deployment.

• Access Control:
  Restricted to calls from the owner public key (onlyOwnerPubkey).

Fallback and Getters

receive()

• Fallback function allowing the contract to accept plain transfers.

getVersion

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

• Returns:

  • The contract version string.

  • The contract name "MobileVerifiersContractRootMirror".

Implementation Details and Algorithms

• Access Control:
  Multiple functions use the senderIs modifier to restrict calls to specific addresses calculated via VerifiersLib. The onlyOwnerPubkey modifier restricts critical operations to the root owner's public key.

• Balance Management:
  The contract maintains a minimum balance (CONTRACT_BALANCE) using the ensureBalance function, which mints tokens if needed.

• Contract Deployment:
  Uses inline state initialization (stateInit) and deployment with precomputed addresses for determinism and security.

• Cryptography and Proofs:
  Employs Poseidon hash and Groth16 zero-knowledge proof verification via the gosh interface to ensure proofs and signatures' integrity.

• Dynamic Code Management:
  Stores various contract code cells in a mapping _code, enabling dynamic updates and deployments of related contracts.

• Indexing and Naming:
  Integrates with NameIndex contracts to manage names and ownership proofs during multifactor deployment.

Interactions with Other Contracts and Modules

• VerifiersLib:
  Provides utility functions for address calculation, state initialization composition, and validation logic used throughout the contract.

• Modifiers:
  Custom modifiers (imported from modifiers.sol) enforce access restrictions and message acceptance.

• PopitGame, Multifactor, PopCoinRoot, NameIndex:
  The contract deploys and interacts with these specialized contracts to manage games, multifactor authentication, token roots, and indexing.

• gosh Interface:
  Used for cryptographic operations including signature verification, hash calculation, zero-knowledge proof verification, and token minting.

Visual Diagram

classDiagram
class Mirror {
-string version
-address _root
-uint128 _index
-uint256 _rootPubkey
-mapping(uint8 => TvmCell) _code
+constructor(root, index, rootPubkey)
-ensureBalance()
+setNewIndex(index)
+setNewCode(id, code)
+destroyNode()
+deployPopitGame(pubkey)
+deployMultifactor(...)
+isDeployMultifactor(...)
+updateWhiteList(pubkey, index, name)
+deployPopCoinRoot(name, maxPopitIndex, popits_media, description, isPublic, popitGameOwner)
+receive()
+getVersion()
}
Mirror ..> VerifiersLib : uses
Mirror ..> PopitGame : deploys
Mirror ..> Multifactor : deploys
Mirror ..> PopCoinRoot : deploys
Mirror ..> NameIndex : deploys
Mirror ..> gosh : cryptographic ops

The diagram illustrates the Mirror contract with its main properties and methods, highlighting its usage of external libraries (VerifiersLib), deployment of specialized contracts (PopitGame, Multifactor, PopCoinRoot, NameIndex), and reliance on the gosh interface for cryptographic operations.