dapp_identifier.rs

Overview

This file defines the DAppIdentifier struct, a wrapper around an AccountAddress type used to uniquely identify decentralized applications (DApps). It provides serialization, deserialization, and utility implementations to facilitate easy conversion, debugging, bitwise operations, and blockchain-related serialization of DApp identifiers. This file plays a crucial role in representing DApp identities within the system, enabling them to be handled consistently across various modules interacting with blockchain addresses.

Struct: DAppIdentifier

Description

The DAppIdentifier struct encapsulates an AccountAddress and serves as a unique identifier for decentralized applications. It derives several traits to support common operations such as cloning, hashing, equality checks, serialization, and deserialization.

Definition

pub struct DAppIdentifier(pub AccountAddress);

Derived Traits

• Clone: Allows duplication of DAppIdentifier instances.

• Eq and PartialEq: Enables equality comparisons.

• Hash: Supports usage as keys in hash maps.

• Serialize and Deserialize: Enables JSON (or other format) serialization and deserialization via Serde.

• Default: Provides a default instance (with a default AccountAddress).

Fields

• 0 (tuple field): The contained AccountAddress representing the DApp's address.

Usage Example

let raw_id: UInt256 = /* some UInt256 value representing the address */;
let dapp_id = DAppIdentifier::from(raw_id);
println!("{:?}", dapp_id);

Implementations

From for DAppIdentifier

Converts a UInt256 type (a 256-bit unsigned integer, commonly used for blockchain addresses) into a DAppIdentifier by wrapping it into an AccountAddress.

fn from(dapp: UInt256) -> Self {
    Self(AccountAddress(dapp))
}

Parameters:

• dapp: A UInt256 representing the raw blockchain address.

Returns:

• A new DAppIdentifier instance containing the wrapped AccountAddress.

Usage:
Allows implicit conversion from low-level address representation to the DAppIdentifier abstraction.

Debug Trait Implementation

Provides a custom format for debug printing the DAppIdentifier. It delegates formatting to the inner AccountAddress.

fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
    write!(f, "{:?}", self.0)
}

Parameters:

• f: A mutable reference to a Formatter used to build the output string.

Returns:

• fmt::Result indicating success or failure of formatting.

Usage:
Enables usage of {:?} to output the contained AccountAddress in debug logs or console output.

Bitwise AND Operator (BitAnd) for References

Implements the bitwise AND (&) operation for references to DAppIdentifier. This operator returns a new DAppIdentifier whose internal AccountAddress is the bitwise AND of the two operand addresses.

fn bitand(self, rhs: Self) -> Self::Output {
    DAppIdentifier(&self.0 & &rhs.0)
}

Parameters:

• self: Left operand as a reference to DAppIdentifier.

• rhs: Right operand as a reference to DAppIdentifier.

Returns:

• A new DAppIdentifier whose address is the bitwise AND of the two input addresses.

Usage:
Useful for bitwise manipulations on DApp addresses, such as masking or intersection operations, potentially in cryptographic or blockchain logic.

Serializable Trait Implementation

Implements the Serializable trait from the tvm_block crate, enabling the serialization of DAppIdentifier instances into blockchain data cells.

fn write_to(&self, cell: &mut BuilderData) -> tvm_types::Result<()> {
    self.0 .0.write_to(cell)
}

Parameters:

• cell: Mutable reference to a BuilderData instance used for serializing data into a blockchain cell.

Returns:

• A Result indicating success or failure of the serialization.

Usage:
This method facilitates writing the underlying 256-bit address into the blockchain's data structure, enabling storage or transmission of DApp identifiers on-chain.

Important Implementation Details

• The internal representation relies on AccountAddress, which itself wraps a UInt256 type. This ensures compatibility with blockchain address formats.

• Bitwise operations are implemented on references to avoid unnecessary cloning and copying, improving performance.

• Serialization is delegated to the inner UInt256 type's write_to method, ensuring consistent binary representation aligned with blockchain requirements.

• The Debug implementation ensures that the DAppIdentifier can be easily logged or inspected during debugging without exposing unnecessary internal details.

Interactions with Other System Components

• AccountAddress: This file depends on the AccountAddress type, which represents blockchain addresses. The DAppIdentifier is essentially a newtype around it.

• UInt256: Conversion and serialization depend on this 256-bit unsigned integer type, which is the underlying format for addresses.

• tvm_block::Serializable and tvm_types::BuilderData: These crates provide serialization capabilities tailored to the blockchain's cell data structures, enabling the DAppIdentifier to be embedded in on-chain data.

• Serde (Serialize, Deserialize): Enables external data interchange formats to parse and produce DAppIdentifier instances for off-chain communication or storage.

This file is likely used wherever DApp identifiers are stored, transmitted, or manipulated, such as transaction processing, smart contract calls, or indexing systems.

Mermaid Diagram

classDiagram
class DAppIdentifier {
+AccountAddress 0
+from(UInt256) DAppIdentifier
+fmt(&Formatter) fmt::Result
+bitand(&DAppIdentifier) DAppIdentifier
+write_to(&mut BuilderData) Result
}
DAppIdentifier --> AccountAddress
AccountAddress --> UInt256

This diagram illustrates the DAppIdentifier struct with its key methods and its composition relationship with AccountAddress and indirectly with UInt256.