xrpl_common_stdlib/host/

host_bindings_trait.rs

/// Trait defining all host functions available to WASM smart contracts.
///
/// This trait serves as the source of truth for host function signatures and is implemented by:
/// - `WasmHostBindings`: The production implementation that calls actual host functions via FFI
/// - `EmptyHostBindings`: Stub implementations for non-WASM builds (panics if called)
/// - `MockHostBindings`: Generated by `mockall` for unit testing (via `#[automock]`)
///
/// # Example
///
/// ```rust,ignore
/// use xrpl_common_stdlib::host::{HostBindings, WasmHostBindings};
///
/// fn my_function<H: HostBindings>(host: &H) {
///     unsafe {
///         let mut buffer = [0u8; 8];
///         let result = host.ldgr_index(buffer.as_mut_ptr(), buffer.len());
///         // ... use result
///     }
/// }
///
/// // In production code:
/// let host = WasmHostBindings;
/// my_function(&host);
/// ```
#[allow(unused)] // To remove warn when compiled for non-WASM targets
#[cfg_attr(
    all(any(test, feature = "test-host-bindings"), not(target_arch = "wasm32")),
    mockall::automock
)]
pub trait HostBindings {
    // ###############################
    // Host Function Category: getters
    // ###############################

    /// Retrieves the current ledger sequence number.
    ///
    /// This function populates a provided buffer with the ledger sequence number.
    ///
    /// # Parameters
    ///
    /// - `out_buff_ptr`: A mutable pointer to a buffer where the ledger sequence number will be written.
    /// - `out_buff_len`: The maximum length of the buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes written to the output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn ldgr_index(&self, out_buff_ptr: *mut u8, out_buff_len: usize) -> i32;

    /// Retrieves the parent ledger time.
    ///
    /// This function is used to obtain the parent ledger's timestamp as a byte array.
    /// The timestamp is written into a provided output buffer.
    ///
    /// # Parameters
    ///
    /// - `out_buff_ptr`: A mutable pointer to a buffer where the parent ledger time will be written.
    /// - `out_buff_len`: The maximum length of the buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes written to the output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn parent_ldgr_time(&self, out_buff_ptr: *mut u8, out_buff_len: usize) -> i32;

    /// Retrieves the hash of the parent ledger.
    ///
    /// This function fetches the hash of the parent ledger and stores it in the buffer provided.
    /// The hash is expected to be written to the memory location pointed by `out_buff_ptr`,
    /// and its length should not exceed the `out_buff_len`.
    ///
    /// # Parameters
    /// - `out_buff_ptr`: A mutable pointer to a buffer where the parent ledger hash will be written.
    ///   The buffer must be allocated and managed by the caller.
    /// - `out_buff_len`: The maximum length of the buffer in bytes. This indicates the size of the
    ///   buffer and ensures that the function does not write beyond the allowed length.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn parent_ldgr_hash(&self, out_buff_ptr: *mut u8, out_buff_len: usize) -> i32;

    /// Retrieves the current transaction base fee.
    ///
    /// # Parameters
    ///
    /// - `out_buff_ptr`: A mutable pointer to a buffer where the base fee will be written.
    /// - `out_buff_len`: The maximum length of the buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes written to the output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn base_fee(&self, out_buff_ptr: *mut u8, out_buff_len: usize) -> i32;

    /// Retrieves the state of an amendment and whether it's enabled or not.
    ///
    /// # Parameters
    ///
    /// - `amendment_ptr`: A raw pointer to the amendment. This can be either the uint256 that
    ///   represents the hash of an amendment, or the string name of the
    ///   amendment.
    /// - `amendment_len`: The length of the amendment specified by `amendment_ptr`.
    ///
    /// # Returns
    ///
    /// - Returns a boolean 0 or 1 (whether the amendment is enabled or not) on success.
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn amendment_enabled(&self, amendment_ptr: *const u8, amendment_len: usize) -> i32;

    /// Fetch a ledger entry pointed by the given ledger entry ID.
    ///
    /// This function uses the ledger entry ID to locate a ledger entry. If found, add it to the
    /// cache. The cache can have up to 255 ledger entries. If `cache_num` is 0, the
    /// new ledger entry will put in the next available cache space. If `cache_num` is not 0,
    /// the new ledger entry will replace an existing ledger entry in the catch.
    ///
    /// # Parameters
    ///
    /// - `id_ptr`: A raw pointer to the ledger entry ID, which is a unique identifier used to
    ///   locate or store data in the ledger.
    /// - `id_len`: The length of the ledger entry ID specified by `id_ptr`.
    /// - `cache_num`: The cache number to which the ledger entry ID will be placed in.
    ///   If 0, the host will assign a new cache space.
    ///
    /// # Returns
    ///
    /// - Returns a positive cache number
    /// - Returns a negative error code on failure
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn cache_le(&self, id_ptr: *const u8, id_len: usize, cache_num: i32) -> i32;

    /// Retrieves a specific transaction field and writes it into the provided output buffer.
    ///
    /// # Parameters
    ///
    /// * `field` - An integer value representing the specific transaction field to retrieve.
    /// * `out_buff_ptr` - A mutable pointer to a buffer where the output data will be written.
    /// * `out_buff_len` - The size (in bytes) of the buffer pointed to by `out_buff_ptr`.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn tx_field(&self, field: i32, out_buff_ptr: *mut u8, out_buff_len: usize) -> i32;

    /// Retrieves a specific field from the current ledger object and writes it into the provided buffer.
    ///
    /// # Parameters
    /// - `field` (`i32`): The integer identifier for the desired field in the ledger object.
    /// - `out_buff_ptr` (`*mut u8`): A mutable pointer to the memory location where the field data
    ///   will be written. This should point to a pre-allocated buffer.
    /// - `out_buff_len` (`usize`): The size (in bytes) of the buffer provided by `out_buff_ptr`.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn home_le_field(&self, field: i32, out_buff_ptr: *mut u8, out_buff_len: usize) -> i32;

    /// Retrieves a specific field from a ledger object based on the given parameters.
    ///
    /// # Parameters
    ///
    /// - `cache_num`: An integer representing the cache index of the ledger object.
    /// - `field`: An integer representing the specific field to retrieve from the ledger object.
    /// - `out_buff_ptr`: A mutable pointer to a buffer where the retrieved field data will be written.
    /// - `out_buff_len`: The size of the output buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn le_field(
        &self,
        cache_num: i32,
        field: i32,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Retrieves an inner field from the current ledger object and writes it into the provided buffer.
    ///
    /// # Parameters
    /// - `locator_ptr`: A pointer to a byte array containing the locator for the inner field.
    /// - `locator_len`: The length of the locator data in bytes.
    /// - `out_buff_ptr`: A pointer to a mutable byte array where the resulting field data will be written.
    /// - `out_buff_len`: The size of the output buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn tx_inner(
        &self,
        locator_ptr: *const u8,
        locator_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Retrieves a specific inner field from the current ledger object.
    ///
    /// This function is designed to access an inner field within the ledger object
    /// specified by the `locator`. The `locator` acts as a path or identifier to
    /// the desired field. The resulting data is written to the `out_buff` buffer.
    /// The function returns a status code indicating success or failure of the operation.
    ///
    /// # Parameters
    /// - `locator_ptr`: A pointer to a byte array containing the locator for the inner field.
    /// - `locator_len`: The length of the locator data in bytes.
    /// - `out_buff_ptr`: A pointer to a mutable byte array where the resulting field data will be written.
    /// - `out_buff_len`: The size of the output buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn home_le_inner(
        &self,
        locator_ptr: *const u8,
        locator_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Retrieves an inner field from a ledger object in a specific cache_num and writes the result into an output buffer.
    ///
    /// # Parameters
    /// - `cache_num`: The cache index of the ledger object to access.
    /// - `locator_ptr`: A pointer to the memory location containing the locator string data
    ///   (used to identify the inner field in the ledger object).
    /// - `locator_len`: The length of the locator string.
    /// - `out_buff_ptr`: A pointer to the buffer where the retrieved inner field value will be written.
    /// - `out_buff_len`: The size of the output buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn le_inner(
        &self,
        cache_num: i32,
        locator_ptr: *const u8,
        locator_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Retrieves the length of an array based on the provided field value.
    ///
    /// # Parameters
    /// - `field` (i32): The integer identifier for the desired field.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of array length on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// This function is safe to call from WASM context
    unsafe fn tx_arr_len(&self, field: i32) -> i32;

    /// Retrieves the length of an array based on the provided field value.
    ///
    /// # Parameters
    /// - `field` (i32): The integer identifier for the desired field.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of array length on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// This function is safe to call from WASM context
    unsafe fn home_le_arr_len(&self, field: i32) -> i32;

    /// Retrieves the length of an array based on the provided cache number and field value.
    ///
    /// # Parameters
    /// - `cache_num`: The cache index of the ledger object to access.
    /// - `field` (i32): The integer identifier for the desired field.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of array length on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// This function is safe to call from WASM context
    unsafe fn le_arr_len(&self, cache_num: i32, field: i32) -> i32;

    /// Retrieves the length of an array based on the provided locator.
    ///
    /// # Parameters
    /// - `locator_ptr`: A pointer to a byte array containing the locator for the inner field.
    /// - `locator_len`: The length of the locator data in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of array length on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn tx_inner_arr_len(&self, locator_ptr: *const u8, locator_len: usize) -> i32;

    /// Retrieves the length of an array based on the provided locator.
    ///
    /// # Parameters
    /// - `locator_ptr`: A pointer to a byte array containing the locator for the inner field.
    /// - `locator_len`: The length of the locator data in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of array length on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn home_le_inner_arr_len(&self, locator_ptr: *const u8, locator_len: usize) -> i32;

    /// Retrieves the length of an array based on the provided locator.
    ///
    /// # Parameters
    /// - `cache_num`: The cache index of the ledger object to access.
    /// - `locator_ptr`: A pointer to a byte array containing the locator for the inner field.
    /// - `locator_len`: The length of the locator data in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of array length on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn le_inner_arr_len(
        &self,
        cache_num: i32,
        locator_ptr: *const u8,
        locator_len: usize,
    ) -> i32;

    // ###################################################
    // Host Function Category: update current ledger entry
    // ###################################################

    /// Updates a data field of the current ledger entry
    ///
    /// # Parameters
    ///
    /// - `data_ptr`: A pointer to the data to be written.
    /// - `data_len`: The size of the data.
    ///
    /// # Returns
    ///
    /// - 0 on success
    /// - negative for an error
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn set_data(&self, data_ptr: *const u8, data_len: usize) -> i32;

    // ###################################################
    // Host Function Category: hash and ledger entry ID computation
    // ###################################################

    /// Computes the first 32 bytes (half) of the SHA-512 hash for the given input data.
    ///
    /// # Parameters
    ///
    /// - `data_ptr`: A pointer to the input data to be hashed.
    /// - `data_len`: The length, in bytes, of the input data.
    /// - `out_buff_ptr`: A pointer to the buffer where the resulting 32-byte hash will be written.
    /// - `out_buff_len`: The length, in bytes, of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn sha512_half(
        &self,
        data_ptr: *const u8,
        data_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Checks a key signature when provided the message and public key.
    ///
    /// # Parameters
    /// - `message_ptr`: A pointer to the message data to be verified.
    /// - `message_len`: The length, in bytes, of the message data.
    /// - `signature_ptr`: A pointer to the signature data.
    /// - `signature_len`: The length, in bytes, of the signature data.
    /// - `pubkey_ptr`: A pointer to the public key data.
    /// - `pubkey_len`: The length, in bytes, of the public key data.
    ///
    /// # Returns
    ///
    /// - Returns 1 if the signature is valid.
    /// - Returns 0 if the signature is invalid.
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn check_sig(
        &self,
        message_ptr: *const u8,
        message_len: usize,
        signature_ptr: *const u8,
        signature_len: usize,
        pubkey_ptr: *const u8,
        pubkey_len: usize,
    ) -> i32;

    /// Generates the ledger entry ID (key identifier) for a specific account.
    ///
    /// This function is used to calculate the account ledger entry ID in a cryptographic or
    /// blockchain-based system. A ledger entry ID is typically used to identify an account or entity
    /// in a secure and deterministic way.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory of the account identifier.
    /// - `account_len`: The size (in bytes) of the data pointed to by `account_ptr`.
    /// - `out_buff_ptr`: A pointer to the memory where the generated ledger entry ID will be stored.
    /// - `out_buff_len`: The length (in bytes) of the buffer pointed to by `out_buff_ptr`.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn accountroot_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Generates the ledger entry ID (key identifier) for a specific AMM.
    ///
    /// This function is used to calculate the AMM ledger entry ID in a cryptographic or
    /// blockchain-based system. A ledger entry ID is typically used to identify an AMM or entity
    /// in a secure and deterministic way.
    ///
    /// # Parameters
    ///
    /// - `issue1_ptr`: A pointer to the memory of the issue1 identifier.
    /// - `issue1_len`: The size (in bytes) of the data pointed to by `issue1_ptr`.
    /// - `issue2_ptr`: A pointer to the memory of the issue2 identifier.
    /// - `issue2_len`: The size (in bytes) of the data pointed to by `issue2_ptr`.
    /// - `out_buff_ptr`: A pointer to the memory where the generated ledger entry ID will be stored.
    /// - `out_buff_len`: The length (in bytes) of the buffer pointed to by `out_buff_ptr`.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn amm_id(
        &self,
        issue1_ptr: *const u8,
        issue1_len: usize,
        issue2_ptr: *const u8,
        issue2_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a check entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn check_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Generates a ledger entry ID for a credential.
    ///
    /// # Parameters
    ///
    /// * `subject_ptr`: A pointer to the memory location where the subject data begins.
    /// * `subject_len`: The length of the subject data in bytes.
    /// * `issuer_ptr`: A pointer to the memory location where the issuer data begins.
    /// * `issuer_len`: The length of the issuer data in bytes.
    /// * `cred_type_ptr`: A pointer to the memory location where the credential type data begins.
    /// * `cred_type_len`: The length of the credential type data in bytes.
    /// * `out_buff_ptr`: A pointer to the buffer where the generated ledger entry ID will be written.
    /// * `out_buff_len`: The size of the output buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    #[allow(clippy::too_many_arguments)]
    unsafe fn credential_id(
        &self,
        subject_ptr: *const u8,
        subject_len: usize,
        issuer_ptr: *const u8,
        issuer_len: usize,
        cred_type_ptr: *const u8,
        cred_type_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a delegate entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `authorize_ptr`: A pointer to the memory location of the authorized account.
    /// - `authorize_len`: The length of the authorized account.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn delegate_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        authorize_ptr: *const u8,
        authorize_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a deposit preauth entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `authorize_ptr`: A pointer to the memory location of the authorized account.
    /// - `authorize_len`: The length of the authorized account.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn deposit_preauth_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        authorize_ptr: *const u8,
        authorize_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a DID entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn did_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for an escrow entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn escrow_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a trustline entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account1_ptr`: A pointer to the memory location of the first accountID.
    /// - `account1_len`: The length of the first accountID.
    /// - `account2_ptr`: A pointer to the memory location of the second accountID.
    /// - `account2_len`: The length of the second accountID.
    /// - `currency_ptr`: A pointer to the memory location of the currency.
    /// - `currency_len`: The length of the currency.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    #[allow(clippy::too_many_arguments)]
    unsafe fn trustline_id(
        &self,
        account1_ptr: *const u8,
        account1_len: usize,
        account2_ptr: *const u8,
        account2_len: usize,
        currency_ptr: *const u8,
        currency_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for an MPT issuance entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `issuer_ptr`: A pointer to the memory location of the accountID.
    /// - `issuer_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn mpt_issuance_id(
        &self,
        issuer_ptr: *const u8,
        issuer_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for an MPToken entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `mptid_ptr`: A pointer to the memory location of the MPTID.
    /// - `mptid_len`: The length of the MPTID.
    /// - `holder_ptr`: A pointer to the memory location of the holder account.
    /// - `holder_len`: The length of the holder account.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn mptoken_id(
        &self,
        mptid_ptr: *const u8,
        mptid_len: usize,
        holder_ptr: *const u8,
        holder_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for an NFT offer entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn nft_offer_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for an offer entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn offer_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Generates a ledger entry ID associated with an oracle's account and document ID.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `document_id_ptr`: A pointer to the memory location of the document ID.
    /// - `document_id_len`: The length of the document ID data.
    /// - `out_buff_ptr`: A pointer to a pre-allocated buffer where the resulting ledger entry ID will be
    ///   written.
    /// - `out_buff_len`: The size of the output buffer in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn oracle_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        document_id_ptr: *const u8,
        document_id_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a payment channel entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `destination_ptr`: A pointer to the memory location of the destination.
    /// - `destination_len`: The length of the destination.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    #[allow(clippy::too_many_arguments)]
    unsafe fn paychan_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        destination_ptr: *const u8,
        destination_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a permissioned domain entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn permissioned_domain_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a signer entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn signers_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a ticket entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn ticket_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Computes the Ledger entry ID for a vault entry in a ledger.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `sequence_ptr`: A pointer to the memory location of the account sequence number.
    /// - `sequence_len`: The length of the sequence data.
    /// - `out_buff_ptr`: A pointer to the output buffer where the derived ledger entry ID will be stored.
    /// - `out_buff_len`: The length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn vault_id(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        sequence_ptr: *const u8,
        sequence_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    // #############################
    // Host Function Category: NFT
    // #############################

    /// Retrieves the URI details of a specific NFT (Non-Fungible Token) associated with a given account.
    ///
    /// # Parameters
    ///
    /// - `account_ptr`: A pointer to the memory location of the accountID.
    /// - `account_len`: The length of the accountID.
    /// - `nft_id_ptr`: A pointer to the memory location containing the NFT identifier.
    /// - `nft_id_len`: The length of the NFT identifier in bytes.
    /// - `out_buff_ptr`: A mutable pointer to the memory location where the retrieved NFT URI
    ///   will be written.
    /// - `out_buff_len`: The maximum length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   `../core/error_codes.rs`
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn nft_uri(
        &self,
        account_ptr: *const u8,
        account_len: usize,
        nft_id_ptr: *const u8,
        nft_id_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Retrieves the issuer of a specific NFT (Non-Fungible Token).
    ///
    /// # Parameters
    ///
    /// - `nft_id_ptr`: A pointer to the memory location containing the NFT identifier.
    /// - `nft_id_len`: The length of the NFT identifier in bytes.
    /// - `out_buff_ptr`: A mutable pointer to the memory location where the retrieved issuer
    ///   account will be written.
    /// - `out_buff_len`: The maximum length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn nft_issuer(
        &self,
        nft_id_ptr: *const u8,
        nft_id_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Retrieves the taxon of a specific NFT (Non-Fungible Token).
    ///
    /// # Parameters
    ///
    /// - `nft_id_ptr`: A pointer to the memory location containing the NFT identifier.
    /// - `nft_id_len`: The length of the NFT identifier in bytes.
    /// - `out_buff_ptr`: A mutable pointer to the memory location where the retrieved taxon
    ///   will be written.
    /// - `out_buff_len`: The maximum length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn nft_taxon(
        &self,
        nft_id_ptr: *const u8,
        nft_id_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    /// Retrieves the flags of a specific NFT (Non-Fungible Token).
    ///
    /// # Parameters
    ///
    /// - `nft_id_ptr`: A pointer to the memory location containing the NFT identifier.
    /// - `nft_id_len`: The length of the NFT identifier in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive flags value on success, which is a bitmask representing the NFT's flags
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn nft_flags(&self, nft_id_ptr: *const u8, nft_id_len: usize) -> i32;

    /// Retrieves the transfer fee of a specific NFT (Non-Fungible Token).
    ///
    /// # Parameters
    ///
    /// - `nft_id_ptr`: A pointer to the memory location containing the NFT identifier.
    /// - `nft_id_len`: The length of the NFT identifier in bytes.
    ///
    /// # Returns
    ///
    /// - Returns a positive transfer fee value on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn nft_xfer_fee(&self, nft_id_ptr: *const u8, nft_id_len: usize) -> i32;

    /// Retrieves the serial number of a specific NFT (Non-Fungible Token).
    ///
    /// # Parameters
    ///
    /// - `nft_id_ptr`: A pointer to the memory location containing the NFT identifier.
    /// - `nft_id_len`: The length of the NFT identifier in bytes.
    /// - `out_buff_ptr`: A mutable pointer to the memory location where the retrieved serial
    ///   number will be written.
    /// - `out_buff_len`: The maximum length of the output buffer.
    ///
    /// # Returns
    ///
    /// - Returns a positive number of bytes wrote to an output buffer on success
    /// - Returns a negative error code on failure. The list of error codes is defined in
    ///   ../core/error_codes.rs
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn nft_serial(
        &self,
        nft_id_ptr: *const u8,
        nft_id_len: usize,
        out_buff_ptr: *mut u8,
        out_buff_len: usize,
    ) -> i32;

    // #############################
    // Host Function Category: FLOAT
    // #############################

    /// Converts a signed 64-bit integer to an opaque float representation
    /// # Parameters
    /// * `in_int` - The input integer to convert
    /// * `out_buff` - Pointer to output buffer where the float will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the conversion
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_from_int(
        &self,
        in_int: i64,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Converts an unsigned integer to an opaque float representation
    /// # Parameters
    /// * `in_uint_ptr` - Pointer to the input unsigned integer
    /// * `in_uint_len` - The length of the input unsigned integer in bytes
    /// * `out_buff` - Pointer to output buffer where the float will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the conversion
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_from_uint(
        &self,
        in_uint_ptr: *const u8,
        in_uint_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Creates a float from explicit mantissa and exponent values
    /// # Parameters
    /// * `mantissa` - The mantissa value
    /// * `exponent` - The exponent value
    /// * `out_buff` - Pointer to output buffer where the float will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the operation
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_from_mant_exp(
        &self,
        mantissa: i64,
        exponent: i32,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Creates a float from an STAmount serialized value
    /// # Parameters
    /// * `in_buff` - Pointer to input STAmount buffer
    /// * `in_buff_len` - The length of the input buffer in bytes
    /// * `out_buff` - Pointer to output buffer where the float will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the operation
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_from_stamount(
        &self,
        in_buff: *const u8,
        in_buff_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Creates a float from an STNumber serialized value
    /// # Parameters
    /// * `in_buff` - Pointer to input STNumber buffer
    /// * `in_buff_len` - The length of the input buffer in bytes
    /// * `out_buff` - Pointer to output buffer where the float will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the operation
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_from_stnumber(
        &self,
        in_buff: *const u8,
        in_buff_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Converts a float to a signed integer
    /// # Parameters
    /// * `in_buff` - Pointer to input float value
    /// * `in_buff_len` - The length of the input float value in bytes
    /// * `out_buff` - Pointer to output buffer where the integer will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the operation
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_to_int(
        &self,
        in_buff: *const u8,
        in_buff_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Decomposes a float into its mantissa and exponent components
    /// # Parameters
    /// * `in_buff` - Pointer to input float value
    /// * `in_buff_len` - The length of the input float value in bytes
    /// * `mant_buff` - Pointer to output buffer where the mantissa will be written
    /// * `mant_buff_len` - The length of the mantissa output buffer in bytes
    /// * `exp_buff` - Pointer to output buffer where the exponent will be written
    /// * `exp_buff_len` - The length of the exponent output buffer in bytes
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_to_mant_exp(
        &self,
        in_buff: *const u8,
        in_buff_len: usize,
        mant_buff: *mut u8,
        mant_buff_len: usize,
        exp_buff: *mut u8,
        exp_buff_len: usize,
    ) -> i32;

    /// Compares two opaque float values
    /// # Parameters
    /// * `in_buff1` - Pointer to first float value
    /// * `in_buff1_len` - The length of the first float value in bytes
    /// * `in_buff2` - Pointer to second float value
    /// * `in_buff2_len` - The length of the second float value in bytes
    /// # Returns
    /// 0 if equal, 1 if first > second, 2 if first < second,
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_cmp(
        &self,
        in_buff1: *const u8,
        in_buff1_len: usize,
        in_buff2: *const u8,
        in_buff2_len: usize,
    ) -> i32;

    /// Adds two opaque float values
    /// # Parameters
    /// * `in_buff1` - Pointer to first float value
    /// * `in_buff1_len` - The length of the first float value in bytes
    /// * `in_buff2` - Pointer to second float value
    /// * `in_buff2_len` - The length of the second float value in bytes
    /// * `out_buff` - Pointer to output buffer where result will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the addition
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    #[allow(clippy::too_many_arguments)]
    unsafe fn float_add(
        &self,
        in_buff1: *const u8,
        in_buff1_len: usize,
        in_buff2: *const u8,
        in_buff2_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Subtracts two opaque float values
    /// # Parameters
    /// * `in_buff1` - Pointer to first float value
    /// * `in_buff1_len` - The length of the first float value in bytes
    /// * `in_buff2` - Pointer to second float value
    /// * `in_buff2_len` - The length of the second float value in bytes
    /// * `out_buff` - Pointer to output buffer where result will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the subtraction
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    #[allow(clippy::too_many_arguments)]
    unsafe fn float_sub(
        &self,
        in_buff1: *const u8,
        in_buff1_len: usize,
        in_buff2: *const u8,
        in_buff2_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Multiplies two opaque float values
    /// # Parameters
    /// * `in_buff1` - Pointer to first float value
    /// * `in_buff1_len` - The length of the first float value in bytes
    /// * `in_buff2` - Pointer to second float value
    /// * `in_buff2_len` - The length of the second float value in bytes
    /// * `out_buff` - Pointer to output buffer where result will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the multiplication
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    #[allow(clippy::too_many_arguments)]
    unsafe fn float_mult(
        &self,
        in_buff1: *const u8,
        in_buff1_len: usize,
        in_buff2: *const u8,
        in_buff2_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Divides two opaque float values
    /// # Parameters
    /// * `in_buff1` - Pointer to dividend float value
    /// * `in_buff1_len` - The length of the dividend float value in bytes
    /// * `in_buff2` - Pointer to divisor float value
    /// * `in_buff2_len` - The length of the divisor float value in bytes
    /// * `out_buff` - Pointer to output buffer where result will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the division
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    #[allow(clippy::too_many_arguments)]
    unsafe fn float_div(
        &self,
        in_buff1: *const u8,
        in_buff1_len: usize,
        in_buff2: *const u8,
        in_buff2_len: usize,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    /// Calculates the nth power of an opaque float value
    /// # Parameters
    /// * `in_buff` - Pointer to input float value
    /// * `in_buff_len` - The length of the input float value in bytes
    /// * `pow` - The power to calculate (e.g., 2 for square)
    /// * `out_buff` - Pointer to output buffer where result will be written
    /// * `out_buff_len` - The length of the output buffer in bytes
    /// * `rounding_mode` - Rounding mode to use for the operation
    /// # Returns
    /// 8 on success, error code otherwise
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn float_pow(
        &self,
        in_buff: *const u8,
        in_buff_len: usize,
        pow: i32,
        out_buff: *mut u8,
        out_buff_len: usize,
        rounding_mode: i32,
    ) -> i32;

    // #############################
    // Host Function Category: TRACE
    // #############################

    /// Print to the trace log on XRPLd. Any XRPLd instance set to \"trace\" log level will see this.
    ///
    /// # Parameters
    /// - `msg_read_ptr`: A pointer to an array containing text characters (in utf8).
    /// - `msg_read_len`: The byte length of the text to send to the trace log.
    /// - `data_type`: A [`crate::host::trace::TraceDataType`] discriminant selecting how the host
    ///   reads the data buffer. Note that it sits between the message pair and the data pair.
    /// - `data_read_ptr`: A pointer to an array of bytes containing the data to print.
    /// - `data_read_len`: The byte length of that data. Numeric types require an exact width,
    ///   little-endian.
    ///
    /// Fire-and-forget: returns nothing and cannot fail from the guest's perspective.
    ///
    /// # Safety
    /// Caller must ensure all pointer parameters point to valid memory
    unsafe fn trace(
        &self,
        msg_read_ptr: *const u8,
        msg_read_len: usize,
        data_type: i32,
        data_read_ptr: *const u8,
        data_read_len: usize,
    );
}