dappconfig.rs

Overview

The dappconfig.rs file provides utilities and functions for managing and interacting with decentralized application (DApp) configuration data within the context of a blockchain environment. It focuses on encoding, decoding, and handling the state and messages related to DApp configurations, including address calculation, message creation for configuration updates, and extraction of configuration parameters from blockchain account data.

Key functionalities include:

• Calculating the unique blockchain address of a DApp configuration smart contract.

• Decoding DApp configuration data from blockchain messages and accounts.

• Creating internal blockchain messages to update DApp configurations.

• Utility functions for handling numeric conversions and configuration value retrieval.

Detailed Explanations

Constants

• DAPP_DATA, CONFIG_DATA, IS_UNLIMIT_DATA, AVAILABLE_BALANCE_DATA:
  These string constants represent keys used in the ABI-encoded data to identify fields within DApp configuration structures.

Functions

get_dapp_config_abi() -> tvm_client::abi::Abi

Returns the ABI (Application Binary Interface) representation of the DApp configuration contract by parsing the JSON ABI string DAPP_CONFIG_ABI.

• Usage: Internal utility function to retrieve the ABI for encoding and decoding contract data.

calculate_dapp_config_address(dapp_id: DAppIdentifier, mut data: StateInit) -> anyhow::Result<UInt256>

Calculates the unique blockchain address of a DApp configuration contract based on the DApp identifier and the contract's initial state.

• Parameters:

  • dapp_id: Identifier of the DApp (DAppIdentifier type).

  • data: The initial smart contract state (StateInit), which includes code and data cells.

• Returns:

  • UInt256: The 256-bit hash representing the contract address on the blockchain.

• Details:

  • Serializes the dapp_id into a builder cell and uses it as a salt to modify the contract code.

  • Updates the StateInit with the salted code.

  • Calculates the hash of the resulting StateInit to get the contract address.

• Errors: Returns an error if serialization or hashing fails.

• Usage Example:

  let dapp_address = calculate_dapp_config_address(my_dapp_id, my_state_init)?;
  

get_i128_value(value: Int) -> i128

Converts a tvm_abi::Int (which internally uses big integers) into a native Rust i128.

• Parameters:

  • value: An Int type representing a signed big integer.

• Returns:

  • A signed 128-bit integer (i128) representing the same numeric value.

• Implementation Details:

  • Extracts the sign and u64 digit array from the big integer.

  • Combines up to two u64 digits into a single i128 value.

  • Applies the sign accordingly.

• Usage: Internal utility for safely converting ABI integer values.

decode_message_config(body: SliceData) -> anyhow::Result<Option<UInt256>>

Decodes a message body slice to extract the DApp identifier from a DApp configuration message.

• Parameters:

  • body: A SliceData containing the encoded message body.

• Returns:

  • An Option<UInt256> containing the DApp ID if found; otherwise None.

• Details:

  • Uses the DApp configuration ABI to decode the input.

  • Iterates over tokens to find the token named "dapp_id".

  • Converts the token value to a UInt256 representing the DApp ID.

• Error Handling: Returns detailed errors if ABI decoding fails.

• Usage Example:

  if let Some(dapp_id) = decode_message_config(message_body)? {
      // use dapp_id
  }
  

decode_dapp_config_data(account: &Account) -> anyhow::Result<Option<DappConfig>>

Decodes the storage data from a blockchain account to reconstruct the DappConfig object.

• Parameters:

  • account: Reference to an Account object representing a blockchain account.

• Returns:

  • An Option<DappConfig> containing the decoded configuration if present.

• Details:

  • Retrieves the raw data cell from the account.

  • Uses the DApp configuration ABI to decode the storage fields.

  • Iterates through tokens to extract configuration fields:

    • is_unlimit (boolean flag).

    • available_balance (signed integer).

  • Populates a DappConfig instance accordingly.

• Error Handling: Returns detailed errors for ABI decoding or data conversion failures.

• Usage Example:

  let config = decode_dapp_config_data(&account)?;
  if let Some(dapp_config) = config {
      // process config
  }
  

create_config_touch_message(minted: i128, addr: UInt256, block_time: u32) -> anyhow::Result<Message>

Creates an internal blockchain message to update the DApp configuration with a new minted value.

• Parameters:

  • minted: The new minted value to set in the config (signed 128-bit integer).

  • addr: The UInt256 address of the DApp configuration contract.

  • block_time: The current block timestamp (unsigned 32-bit integer).

• Returns:

  • A Message object representing the internal message to be sent.

• Details:

  • Calculates an expiration timestamp (block_time + 5).

  • Constructs parameters JSON with the minted value.

  • Encodes the function call to setNewConfig using the ABI.

  • Builds the internal message header with source and destination addresses set to addr.

  • Sets a fixed grams (currency) value for message fees.

  • Serializes the message body into a cell and wraps it as slice data.

• Error Handling: Returns errors on failures during ABI encoding, address creation, or serialization.

• Usage Example:

  let msg = create_config_touch_message(1000, config_addr, current_block_time)?;
  

get_available_balance_from_config(config: DappConfig) -> i128

Retrieves the available balance from a given DappConfig, applying special rules for unlimited flags.

• Parameters:

  • config: A DappConfig instance.

• Returns:

  • An i128 value representing available balance.

  • Returns -1 if the is_unlimit flag is set on the config.

  • Returns 0 if the available balance is negative.

• Usage:
  Used to safely extract a usable balance value considering configuration constraints.

Implementation Details and Algorithms

• Address Calculation with Code Salting:
  The address calculation function uses a technique called "code salting," where the code cell of a smart contract is modified by appending a salt derived from the DApp identifier. This ensures unique contract addresses for different DApps even if the base code is the same.

• ABI-Based Encoding and Decoding:
  The file relies heavily on ABI definitions to serialize and deserialize smart contract messages and storage data. This abstraction allows safe interaction with smart contract data structures without manual binary parsing.

• Signed Big Integer Conversion:
  Because blockchain contract integers can be arbitrarily large, the file includes a utility to convert tvm_abi::Int into native Rust i128 by extracting the least significant 128 bits and applying the sign.

• Message Construction:
  Internal messages are constructed carefully with proper headers, fee collections, and serialized bodies to ensure they are compatible with the blockchain messaging system.

Interaction with Other Parts of the System

• The file imports ABI JSON and the DappConfig struct from the creditconfig module, indicating it is tightly coupled with the credit configuration logic of the system.

• It uses types and utilities from several blockchain-related crates such as tvm_abi, tvm_block, tvm_client, and tvm_types for encoding, message handling, and state management.

• The functions here enable the creation and decoding of messages that interact with on-chain smart contracts managing DApp configurations, facilitating state updates and queries.

• It is designed to be used by higher-level components that manage DApp lifecycle, configuration updates, or blockchain state inspection.

Mermaid Diagram: Structure and Key Functions Flow

flowchart TD
A[Start] --> B[get_dapp_config_abi]
B --> C[calculate_dapp_config_address]
C --> D[get_i128_value]
B --> E[decode_message_config]
E --> F[decode_dapp_config_data]
F --> G[get_available_balance_from_config]
B --> H[create_config_touch_message]
style A fill:#f9f,stroke:#333,stroke-width:2px
style B fill:#bbf,stroke:#333,stroke-width:1px
style C fill:#bbf,stroke:#333,stroke-width:1px
style D fill:#bbf,stroke:#333,stroke-width:1px
style E fill:#bbf,stroke:#333,stroke-width:1px
style F fill:#bbf,stroke:#333,stroke-width:1px
style G fill:#bbf,stroke:#333,stroke-width:1px
style H fill:#bbf,stroke:#333,stroke-width:1px

The diagram illustrates the flow from ABI retrieval through address calculation, message decoding, configuration data extraction, balance retrieval, and message creation functions, showing their interrelations.