DappRoot.sol

Overview

DappRoot.sol defines the DappRoot smart contract, which serves as the primary management contract for decentralized application (DApp) configurations. Its core functionality includes:

• Managing and storing code templates for DApp configurations.

• Deploying new DApp configurations with customizable parameters.

• Handling ownership and administrative controls related to deploying and closing configurations.

• Ensuring the contract maintains sufficient balance to operate.

This contract interacts closely with the DappConfig contract for individual DApp configuration instances and utilizes utilities from DappLib for composing and calculating code and addresses related to configurations.

Contract: DappRoot

State Variables

Constructor

constructor ()

• Initializes the contract.

• Sets the owner implicitly (via Modifiers inheritance).

• Mints the initial contract balance (implementation detail suggested by comments but not explicitly shown in constructor body).

Functions

setNewCode

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

• Purpose: Updates the code template for a given configuration ID.

• Parameters:

  • id: Unique identifier for the configuration code.

  • code: The TVM cell containing the compiled code to be stored.

• Access Control: Only callable by the contract itself (senderIs(address(this))), ensuring controlled internal updates.

• Behavior: Ensures sufficient contract balance and sets the new code in _codeStorage.

• Usage Example:

  // Example: Updating code template for config ID 1
  dappRoot.setNewCode(1, newCodeCell);
  

ensureBalance

function ensureBalance() private pure

• Purpose: Checks if the contract balance meets a minimum threshold (MIN_BALANCE).

• Behavior: If balance is below the threshold, mints additional funds.

• Implementation Detail: Uses gosh.mintshellq(MIN_BALANCE) to mint funds.

• Note: Marked private and pure, indicating balance check logic is embedded or external.

deployNewConfigCustom

function deployNewConfigCustom(optional(address) authorityAddress) public view internalMsg accept

• Purpose: Deploys a new DApp configuration with parameters derived from the message currency value.

• Parameters:

  • authorityAddress (optional): Address for authority assignment in the new config.

• Behavior:

  • Ensures contract balance.

  • Requires message currency amount to be at least MIN_BALANCE_DEPLOY.

  • Burns the required currency from the sender.

  • Creates a CreditConfig with unlimited flag set to false and balance equal to the currency provided.

  • Calls deployConfig to create the new configuration.

• Access Control: Public but expects proper currency transfer (internalMsg modifier).

• Usage Example:

  dappRoot.deployNewConfigCustom(authorityAddress);
  

deployNewConfig

function deployNewConfig(uint256 dapp_id, bool is_unlimit, int128 available_balance, optional(address) authorityAddress) public view onlyOwnerPubkey(tvm.pubkey()) accept

• Purpose: Deploys a new DApp configuration with explicit parameters.

• Parameters:

  • dapp_id: Unique identifier for the DApp.

  • is_unlimit: Boolean flag for unlimited balance access.

  • available_balance: Initial balance available for the configuration. Must be non-negative.

  • authorityAddress (optional): Address for authority assignment.

• Access Control: Only callable by contract owner (onlyOwnerPubkey).

• Preconditions:

  • _is_close_owner must be false (contract not closed).

  • available_balance must be >= 0.

• Behavior: Calls deployConfig with composed CreditConfig.

• Usage Example:

  dappRoot.deployNewConfig(123, true, 1000, someAuthority);
  

deployNewConfigNode

function deployNewConfigNode(uint256 dapp_id, bool is_unlimit, int128 available_balance, optional(address) authorityAddress) public view senderIs(address(this)) accept

• Purpose: Internal deployment of a new DApp configuration node, callable only by the contract itself.

• Parameters: Same as deployNewConfig.

• Access Control: Only callable by the contract (senderIs(address(this))).

• Behavior: Calls deployConfig with provided parameters.

• Usage: Utilized internally for controlled deployments.

deployConfig

function deployConfig(uint256 dapp_id, CreditConfig info, optional(address) authorityAddress) private view

• Purpose: Core deployment logic for new DApp configurations.

• Parameters:

  • dapp_id: Unique DApp identifier.

  • info: CreditConfig struct containing unlimited flag and balance.

  • authorityAddress (optional): Authority assignment.

• Preconditions: _codeStorage must contain valid code at key m_ConfigCode.

• Behavior:

  • Composes the new configuration contract’s state initialization data using DappLib.composeDappConfigStateInit.

  • Deploys a new DappConfig contract instance with prepared state.

• Implementation Detail: Uses TVM's stateInit parameter and deployment value (FEE_DEPLOY_CONFIG).

• Inter-contract Interaction: Instantiates DappConfig contracts representing individual configurations.

closeRoot

function closeRoot() public onlyOwnerPubkey(tvm.pubkey()) accept

• Purpose: Marks the root contract as closed, preventing further owner deployments.

• Behavior:

  • Sets _is_close_owner flag to true.

  • Ensures contract maintains minimum balance.

• Access Control: Owner-only function.

getConfigAddr

function getConfigAddr(uint256 dapp_id) external view returns(address config)

• Purpose: Retrieves the on-chain address of a configuration contract for a given DApp ID.

• Parameters:

  • dapp_id: The unique identifier of the DApp.

• Returns: Address of the deployed DappConfig contract.

• Implementation: Calculates address using DappLib.calculateDappConfigAddress.

• Usage Example:

  address configAddr = dappRoot.getConfigAddr(123);
  

getDappConfigCode

function getDappConfigCode(uint256 dapp_id) external view returns(TvmCell code)

• Purpose: Returns the TVM code cell for a specific DApp configuration.

• Parameters:

  • dapp_id: Unique identifier for the DApp.

• Returns: TVM cell representing the code for the DApp configuration.

• Implementation: Builds the code using DappLib.buildDappConfigCode.

Important Types and Constants

• CreditConfig: Struct representing credit configuration, includes:

  • is_unlimit (bool): Flag for unlimited credit.

  • available_balance (int128): Available balance amount.

• m_ConfigCode: Presumed constant key/index for config code storage in _codeStorage.

• MIN_BALANCE, MIN_BALANCE_DEPLOY: Minimum balance constants for operations and deployments.

• ERR_LOW_BALANCE, ERR_NOT_READY, ERR_WRONG_DATA, ERR_NO_DATA: Error codes for require statements.

• FEE_DEPLOY_CONFIG: Fee cost for deploying a configuration contract.

• CURRENCIES_ID_SHELL: Currency identifier used in the contract.

Interactions with Other Components

• DappConfig Contract: Represents individual DApp configurations deployed by DappRoot. Each configuration is a separate contract instance initialized with specific parameters.

• DappLib Library: Provides utility functions for composing contract state initialization and calculating addresses for configurations.

• Modifiers Contract: Provides access control modifiers such as onlyOwnerPubkey and senderIs.

• gosh System Interface: Used for token minting (mintshellq) and burning (burnecc).

• DappConfig.sol: Imported contract defining the configuration contract deployed by DappRoot.

Implementation Details and Algorithms

• Code Storage: Uses a mapping _codeStorage to maintain different versions or types of configuration contract codes, enabling flexible deployments.

• Balance Management: The contract ensures it holds enough balance for operations by minting tokens if below thresholds.

• Deployments: Deploys new configurations by composing state initialization data and calling the constructor of DappConfig with required parameters.

• Access Control: Multiple functions restrict access via onlyOwnerPubkey or internal-only calls, securing sensitive operations.

• Closing Mechanism: Once closed via closeRoot, owner deployments are disabled, preventing further configuration changes by the owner.

Diagram: Class Structure of DappRoot

classDiagram
class DappRoot {
-string version
-mapping(uint8 => TvmCell) _codeStorage
-bool _is_close_owner
+constructor()
+setNewCode()
+deployNewConfigCustom()
+deployNewConfig()
+deployNewConfigNode()
-deployConfig()
+closeRoot()
+getConfigAddr()
+getDappConfigCode()
-ensureBalance()
}
DappRoot ..|> Modifiers
DappRoot --> DappConfig : deploys >
DappRoot ..> DappLib : uses >

Usage Examples

• Deploying a new config by owner:

  dappRoot.deployNewConfig(1001, true, 5000, optionalAuthorityAddress);
  

• Retrieving a config address:

  address configAddress = dappRoot.getConfigAddr(1001);
  

• Setting new code template internally:

  // Only callable by contract itself
  dappRoot.setNewCode(1, newCodeCell);
  

For detailed information on the CreditConfig struct, DappConfig contract, and related utility functions, see DappConfig Contract and DappLib Library. For access control mechanisms, see Modifiers.