Utilities

The utilities module offers a comprehensive set of tools and functions to simplify development process. This package encompasses various utility functions designed to enhance the overall development experience when working with MOI.

The utilities package offers a range of features, including address validation, data format conversion and cryptographic operations. These features are designed to ensure accuracy, security, and convenience throughout the development process.

Types

Interaction

The Interaction interface represents an interaction object. It has the following properties:

  • type - number: The type of the interaction.

  • nonce - string: The nonce value.

  • sender - string: The sender of the interaction.

  • receiver - string: The receiver of the interaction.

  • payer - string: The payer of the interaction.

  • transfer_values - Map<string, string>: Transfer values associated with the interaction.

  • perceived_values - Map<string, string>: Perceived values associated with the interaction.

  • perceived_proofs - string: The perceived proofs for the interaction.

  • fuel_price - string: The fuel price for the interaction.

  • fuel_limit - string: The fuel limit for the interaction.

  • payload - unknown: The payload of the interaction.

  • mode - string: The mode of the interaction.

  • compute_hash - string: The hash of the compute.

  • compute_nodes - string[]: The compute nodes involved in the interaction.

  • mtq - string: The MTQ value for the interaction.

  • trust_nodes - string[]: The trust nodes associated with the interaction.

  • hash - string: The hash of the interaction.

  • signature - string: The signature of the interaction.

  • parts - TesseractPart[]: An array of tesseract parts associated with the interaction.

  • ix_index - string: The index of the interaction.

Interactions

The Interactions type represents an array of interactions.

AssetCreationReceipt

The AssetCreationReceipt interface represents a receipt for asset creation. It has the following properties:

  • asset_id - string: The ID of the created asset.

  • address - string: The address associated with the asset.

AssetMintOrBurnReceipt

The AssetMintOrBurnReceipt interface represents a receipt for asset minting or burning. It has the following properties:

  • total_supply - string: The total supply of the asset.

LogicDeployReceipt

The LogicDeployReceipt interface represents a receipt for logic deployment. It has the following properties:

  • logic_id - string (optional): The ID of the deployed logic.

  • error - string: The error message associated with the deployment.

LogicInvokeReceipt

The LogicInvokeReceipt interface represents a receipt for logic execution. It has the following properties:

  • outputs - string: The outputs of the logic execution.

  • error - string: The error message associated with the execution.

Receipt

The Receipt interface represents an interaction receipt. It has the following properties:

  • ix_type - number: The type of the interaction.

  • ix_hash - string: The hash of the interaction.

  • fuel_used - bigint: The fuel used for the interaction.

  • state_hashes - Map<string, string>: State hashes associated with the interaction.

  • context_hashes - Map<string, string>: Context hashes associated with the interaction.

  • extra_data - AssetCreationReceipt, AssetMintOrBurnReceipt, LogicDeployReceipt, LogicInvokeReceipt, or null: Additional data associated with the interaction receipt.

ContextLockInfo

The ContextLockInfo interface represents information about a context lock. It has the following properties:

  • address - string: The address associated with the context lock.

  • context_hash - string: The hash of the context.

  • height - string: The height of the context.

  • tesseract_hash - string: The hash of the tesseract.

DeltaGroup

The DeltaGroup interface represents a group of delta nodes. It has the following properties:

  • address - string: The address associated with the delta group.

  • role - number: The role of the delta group.

  • behavioural_nodes - string[]: An array of behavioural nodes.

  • random_nodes - string[]: An array of random nodes.

  • replaced_nodes - string[]: An array of replaced nodes.

PoXCData

The PoXCData interface represents PoXC data. It has the following properties:

  • binary_hash - string: The hash of the binary.

  • identity_hash - string: The hash of the identity.

  • ics_hash - string: The hash of the ICS.

TesseractGridID

The TesseractGridID interface represents the identifier for a tesseract grid. It has the following properties:

  • hash - string: The hash of the grid.

  • total - string: The total value.

  • parts - TesseractPart[]: An array of tesseract parts.

CommitData

The CommitData interface represents commit data. It has the following properties:

  • round - string: The round value.

  • commit_signature - string: The commit signature.

  • vote_set - string: The vote set.

  • evidence_hash - string: The hash of the evidence.

  • grid_id - TesseractGridID: The grid identifier.

TesseractHeader

The TesseractHeader interface represents the header of a tesseract. It has the following properties:

  • address - string: The address associated with the tesseract.

  • prev_hash - string: The hash of the previous tesseract.

  • height - string: The height of the tesseract.

  • fuel_used - string: The fuel used in the tesseract.

  • fuel_limit - string: The fuel limit of the tesseract.

  • body_hash - string: The hash of the tesseract body.

  • grid_hash - string: The hash of the tesseract grid.

  • operator - string: The operator of the tesseract.

  • cluster_id - string: The ID of the cluster.

  • timestamp - string: The timestamp of the tesseract.

  • context_lock - ContextLockInfo[]: An array of context lock information.

  • extra - CommitData: Additional commit data.

TesseractBody

The TesseractBody interface represents the body of a tesseract. It has the following properties:

  • state_hash - string: The hash of the state.

  • context_hash - string: The hash of the context.

  • interaction_hash - string: The hash of the interactions.

  • receipt_hash - string: The hash of the receipts.

  • context_delta - DeltaGroup[]: An array of delta groups for the context.

  • consensus_proof - PoXCData: The PoXC data for the consensus.

Tesseract

The Tesseract interface represents a tesseract object. It has the following properties:

  • header - TesseractHeader: The header of the tesseract.

  • body - TesseractBody: The body of the tesseract.

  • ixns - Interactions: The interactions associated with the tesseract.

  • seal - string: The seal of the tesseract.

  • hash - string: The hash of the tesseract.

Address

isValidAddress(address)

Checks if the given address is a valid address.

Arguments:

  • address (string) – The address to validate.

Returns:

boolean – Returns true if the address is valid, otherwise false.

// Example
const isValid = isValidAddress("0xd210e094cd2432ef7d488d4310759b6bd81a0cda35a5fcce3dab87c0a841bdba")
console.log(isValid)

>> true

Base64

encodeBase64(uint8Array)

encodeBase64

Encodes a Uint8Array into a base64 string.

Arguments:

  • uint8Array (Uint8Array) – The Uint8Array to encode.

Returns:

string – The base64 encoded string.

// Example
const uint8Array = new Uint8Array([72, 101, 108, 108, 111]);
const encoded = encodeBase64(uint8Array);
console.log(encoded)

>> SGVsbG8=
decodeBase64(base64String)

Decodes a base64 string into a Uint8Array.

Arguments:

  • base64String (string) – The base64 string to decode.

Returns:

Uint8Array – The decoded Uint8Array.

// Example
const uint8Array = new Uint8Array([72, 101, 108, 108, 111]);
const encoded = encodeBase64(uint8Array);
console.log(encoded)

>> [ 72, 101, 108, 108, 111 ]

Hex

numToHex(value)

Converts a number, bigint, or BN instance to a hexadecimal string representation. If the input value is not already a BN instance, it is converted to one. Throws an error if the input value is a negative number.

Arguments:

  • value (number|bigint|BN) – The value to convert to a hexadecimal string.

Throws:

Error – If the input value is a negative number.

Returns:

string – - The hexadecimal string representation of the value.

// Example
console.log(numToHex(123))

>> 7B
toQuantity(value)

Converts a number, bigint, or BN instance to a quantity string representation. The quantity string is prefixed with “0x” and is obtained by calling numToHex function.

Arguments:

  • value (number|bigint|BN) – The value to convert to a quantity string.

Throws:

Error – If an error occurs during the conversion.

Returns:

string – - The quantity string representation of the value.

// Example
console.log(toQuantity(123))

>> 0x7B
encodeToString(data)

Converts a Uint8Array to a hexadecimal string representation.

Arguments:

  • data (Uint8Array) – The Uint8Array to encode as a hexadecimal string.

Returns:

string – The hexadecimal string representation of the Uint8Array.

// Example
const data = new Uint8Array([1, 2, 3, 4])
console.log(encodeToString(data))

>> 0x01020304
hexToBytes(str)

Converts a hexadecimal string to a Uint8Array.

Arguments:

  • str (string) – The hexadecimal string to convert to a Uint8Array.

Throws:

Error – If the input string is not a valid hexadecimal string.

Returns:

Uint8Array – - The Uint8Array representation of the hexadecimal string.

// Example
console.log(hexToBytes("0x01020304"))

>> [1, 2, 3, 4]
hexToBN(hex)

Converts a hexadecimal string to a bigint or number. If the resulting value is too large to fit in a number, it is returned as a BigInt. Otherwise, it is returned as a number.

Arguments:

  • hex (string) – The hexadecimal string to convert.

Returns:

bigint|number – The resulting value as a bigint or number.

// Example
console.log(hexToBN("0x123"))

>> 291
bytesToHex(data)

Converts a Uint8Array to a hexadecimal string representation.

Arguments:

  • data (Uint8Array) – The Uint8Array to convert to a hexadecimal string.

Returns:

string – The hexadecimal string representation of the Uint8Array.

// Example
const data = new Uint8Array([1, 2, 3, 4]);
console.log(bytesToHex(data))

>> 01020304
isHex(data)

Checks if a given string is a valid hexadecimal value.

Arguments:

  • data (string) – The input string.

Returns:

boolean – True if the input is a valid hexadecimal string, false otherwise.

// Example
console.log(isHex("0x1234ABCD"))

>> true
trimHexPrefix(data)

Removes the ‘0x’ prefix from a hexadecimal string if present.

Arguments:

  • data (string) – The input string.

Returns:

string – The trimmed hexadecimal string.

// Example
console.log(trimHexPrefix("0xABCDEF"))

>> ABCDEF

Bytes

isInteger(value)

Checks if the given value is an integer.

Arguments:

  • value (number) – The value to check.

Returns:

boolean – - Returns true if the value is an integer, otherwise false.

// Example
console.log(isInteger(42))

>> true
isBytes(value)

Checks if the given value is a valid byte array.

Arguments:

  • value (any) – The value to check.

Returns:

boolean – - Returns true if the value is a valid byte array, otherwise false.

// Example
console.log(isBytes([0, 255, 128]))

>> true
hexDataLength(data)

Calculates the length of the data represented by a hexadecimal string.

Arguments:

  • data (string) – The hexadecimal string.

Returns:

number|null – - The length of the data, or null if the input is not a valid hexadecimal string.

// Example
console.log(hexDataLength('0xabcdef'))

>> true
isHexString(value, length)

Checks if the given value is a valid hexadecimal string.

Arguments:

  • value (any) – The value to check.

  • length (number) – Optional. The expected length of the hexadecimal string.

Returns:

boolean – Returns true if the value is a valid hexadecimal string, otherwise false.

// Example
console.log(isHexString('0x1234', 3))

>> false
bufferToUint8(target)

Converts a Buffer to a Uint8Array.

Arguments:

  • target (Buffer) – The Buffer to convert.

Returns:

Uint8Array – The Uint8Array representation of the Buffer.

// Example
const buffer = Buffer.from([1, 2, 3]);
const uint8Array = bufferToUint8(buffer);
console.log(uint8Array)

>> [1, 2, 3]

Json

marshal(data)

Marshals the given json object into a Uint8Array by converting it to JSON string and encoding as UTF-8.

Arguments:

  • data (object) – The data object to marshal.

Returns:

Uint8Array – The marshaled data as a Uint8Array.

// Example
const data = { name: "John", age: 30 }
console.log(marshal(data))

// Output

/*
    [
        123, 34, 110,  97, 109, 101, 34,
        58, 34,  74, 111, 104, 110, 34,
        44, 34,  97, 103, 101,  34, 58,
        51, 48, 125
    ]
*/
unmarshal(bytes)

Unmarshals the given Uint8Array into its original json object by decoding it as UTF-8 and parsing the JSON string.

Arguments:

  • bytes (Uint8Array) – The bytes to unmarshal.

Throws:

Error – If there is an error while deserializing the data.

Returns:

any – The unmarshaled data object.

// Example
const bytes = Buffer.from([
  123, 34, 110,  97, 109, 101, 34,
   58, 34,  74, 111, 104, 110, 34,
   44, 34,  97, 103, 101,  34, 58,
   51, 48, 125
]);
console.log(unmarshal(bytes))

>> { name: "John", age: 30 }

Properties

defineReadOnly(object, name, value)

Defines a read-only property on an object with the specified name and value.

Arguments:

  • object (object) – The object on which to define the property.

  • name (string|symbol) – The name of the property.

  • value (any) – The value of the property.

// Example
const data = {}
defineReadOnly(data, "foo", true)

Errors

CustomError

The CustomError class extends the Error class and provides additional utility methods.

// Example
const error = new CustomError("Invalid argument provided")
toString()

Overrides the toString() method to provide a string representation of the error.

Returns:

string – - The string representation of the error.

// Example
const error = error.toString();

ErrorUtils

The ErrorUtils class contains static helper methods for handling errors.

static throwError(message, code, params)

Throws a CustomError with the specified message, error code, and parameters.

Arguments:

  • message (string) – The error message.

  • code (ErrorCode) – The error code.

  • params (ErrorParams) – The parameters of the error.

Throws:

CustomError –

  • Throws a CustomError.

// Example
ErrorUtils.throwError("Invalid argument provided", ErrorCode.INVALID_ARGUMENT)
static throwArgumentError(message, name, value)

Throws a CustomError with the specified argument-related error message, argument name, and value.

Arguments:

  • message (string) – The error message.

  • name (string) – The name of the argument.

  • value (any) – The value of the argument.

Throws:

CustomError –

  • Throws a CustomError.

// Example
ErrorUtils.throwArgumentError("Invalid argument provided", "nonce", "2")