xrpl_common_stdlib/host/

mod.rs

//! Host bindings and utilities exposed to WASM smart contracts.
//!
//! This module exposes the low-level host ABI plus typed primitives (Result, Error, helpers).
//! Most users should prefer the safe, high-level APIs in [`crate::fields`] and [`crate::objects`],
//! which wrap these bindings.
//!
//! ## Float Operations for Fungible Tokens (IOUs)
//!
//! The host provides float arithmetic functions for XRPL's fungible token amounts.
//! These operations use rippled's Number class via FFI to ensure exact consensus compatibility:
//!
//! - `float_from_int` / `float_from_uint` / `float_from_mant_exp` - Convert values to float format
//! - `float_from_stamount` / `float_from_stnumber` - Convert XRP ledger types to float format
//! - `float_to_int` / `float_to_mant_exp` - Convert float to integer or decomposed form
//! - `float_add` / `float_sub` / `float_mult` / `float_div` - Arithmetic
//! - `float_pow` - Mathematical functions
//! - `float_cmp` - Comparison operations
//!
//! All operations support explicit rounding modes; see [`RoundingMode`].
//!
//! See the host_bindings documentation for detailed function signatures.

pub mod chain;
pub mod error_codes;
pub mod trace;

/// Rounding mode for float operations, matching rippled's `Number::RoundingMode`.
///
/// The host functions take the mode as an `i32`; convert with `.into()` at the call site.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum RoundingMode {
    /// Round to the nearest representable value.
    ToNearest = 0,
    /// Round toward zero (truncate).
    TowardsZero = 1,
    /// Round toward negative infinity.
    Downward = 2,
    /// Round toward positive infinity.
    Upward = 3,
}

impl From<RoundingMode> for i32 {
    #[inline(always)]
    fn from(mode: RoundingMode) -> Self {
        mode as i32
    }
}

// This setup allows us to keep all host functions in the `host::` namespace, but vary the implementation based on
// target and build profiles.
// 1) `host_bindings_trait.rs` defines the trait that specifies the host functions available to WASM smart contracts.
// 2a) When cargo is executed with `test` or with the `test-host-bindings` feature, `host_bindings_test.rs` is included,
//     which provides stub implementations for coverage testing.
// 2b) When `cargo build` is executed, then `host_bindings_empty.rs` is included, which provides a no-op implementation
//     that simply allows the build to pass when the target is not Wasm32.
// 2c) When `cargo build --target wasm32v1-none` (or any Wasm target) is executed, then `host_bindings_wasm.rs` is
//     included, which provides the actual host function implementations.
pub mod host_bindings_trait;

#[cfg(all(
    not(any(test, feature = "test-host-bindings")),
    not(target_arch = "wasm32")
))] // <-- e.g., `cargo build` or `... --features xrpl-common-stdlib/test-host-bindings`
include!("host_bindings_empty.rs");

#[cfg(all(any(test, feature = "test-host-bindings"), not(target_arch = "wasm32")))] // <-- e.g., `cargo test` or cov
include!("host_bindings_test.rs");

// host functions defined by the host.
#[cfg(target_arch = "wasm32")] // <-- e.g., `cargo build --target wasm32v1-none`
include!("host_bindings_wasm.rs");

/// `Result` is a type that represents either a success ([`Ok`]) or failure ([`Err`]) result from the host.
#[must_use]
pub enum Result<T> {
    /// Contains the success value
    Ok(T),
    /// Contains the error value
    Err(Error), // TODO: Test if the WASM size is expanded if we use an enum here instead of i32
}

impl<T> Result<T> {
    /// Returns `true` if the result is [`Ok`].
    #[inline]
    pub fn is_ok(&self) -> bool {
        matches!(*self, Result::Ok(_))
    }

    /// Returns `true` if the result is [`Err`].
    #[inline]
    pub fn is_err(&self) -> bool {
        !self.is_ok()
    }

    /// Converts from `Result<T>` to `Option<T>`.
    ///
    /// Converts `self` into an `Option<T>`, consuming `self`,
    /// and discarding the error, if any.
    #[inline]
    pub fn ok(self) -> Option<T> {
        match self {
            Result::Ok(x) => Some(x),
            Result::Err(_) => None,
        }
    }

    /// Converts from `Result<T>` to `Option<Error>`.
    ///
    /// Converts `self` into an `Option<Error>`, consuming `self`,
    /// and discarding the success value, if any.
    #[inline]
    pub fn err(self) -> Option<Error> {
        match self {
            Result::Ok(_) => None,
            Result::Err(x) => Some(x),
        }
    }

    /// Returns the contained [`Ok`] value, consuming the `self` value.
    ///
    /// # Panics
    ///
    /// Panics if the value is an [`Err`], with a panic message provided by the
    /// [`Err`]'s value.
    #[inline]
    #[track_caller]
    pub fn unwrap(self) -> T {
        match self {
            Result::Ok(t) => t,
            Result::Err(error) => {
                #[cfg(target_arch = "wasm32")]
                {
                    trace::trace_num("error_code=", error.code() as i64);
                }
                #[cfg(not(target_arch = "wasm32"))]
                {
                    let location = core::panic::Location::caller();
                    eprintln!(
                        "Result::unwrap() failed at {}:{}:{} with error_code={}",
                        location.file(),
                        location.line(),
                        location.column(),
                        error.code()
                    );
                }
                panic!(
                    "called `Result::unwrap()` on an `Err` with code: {}",
                    error.code()
                )
            }
        }
    }

    /// Returns the contained [`Ok`] value or a provided default.
    #[inline]
    pub fn unwrap_or(self, default: T) -> T {
        match self {
            Result::Ok(t) => t,
            Result::Err(_) => default,
        }
    }

    /// Returns the contained [`Ok`] value or computes it from a closure.
    #[inline]
    pub fn unwrap_or_else<F: FnOnce(Error) -> T>(self, op: F) -> T {
        match self {
            Result::Ok(t) => t,
            Result::Err(e) => op(e),
        }
    }

    #[inline]
    #[track_caller]
    pub fn unwrap_or_panic(self) -> T {
        self.unwrap_or_else(|error| {
            let location = core::panic::Location::caller();
            #[cfg(target_arch = "wasm32")]
            {
                trace::trace_num("error_code=", error.code() as i64);
            }
            #[cfg(not(target_arch = "wasm32"))]
            {
                eprintln!(
                    "unwrap_or_panic() failed at {}:{}:{} with error_code={}",
                    location.file(),
                    location.line(),
                    location.column(),
                    error.code()
                );
            }
            core::panic!("Failed in {}: error_code={}", location, error.code());
        })
    }

    #[inline]
    pub fn map<U, F: FnOnce(T) -> U>(self, op: F) -> Result<U> {
        match self {
            Result::Ok(t) => Result::Ok(op(t)),
            Result::Err(e) => Result::Err(e),
        }
    }

    /// Calls `op` if the result is [`Ok`], otherwise returns the [`Err`] value of `self`.
    #[inline]
    pub fn and_then<U, F: FnOnce(T) -> Result<U>>(self, op: F) -> Result<U> {
        match self {
            Result::Ok(t) => op(t),
            Result::Err(e) => Result::Err(e),
        }
    }
}

impl From<i64> for Result<u64> {
    #[inline(always)] // <-- Inline because this function is very small
    fn from(value: i64) -> Self {
        match value {
            res if res >= 0 => Result::Ok(value as _),
            _ => Result::Err(Error::from_code(value as _)),
        }
    }
}

/// Possible errors returned by XRPL Programmability APIs.
///
/// Errors are global across all Programmability APIs.
#[derive(Clone, Copy, Debug)]
#[repr(i32)]
pub enum Error {
    /// The host function has an empty/stub implementation (not yet implemented by the host).
    Unimplemented = error_codes::UNIMPLEMENTED,

    /// The requested serialized field could not be found in the specified object.
    /// This error is returned when attempting to access a field that doesn't exist
    /// in the current transaction or ledger object.
    FieldNotFound = error_codes::FIELD_NOT_FOUND,

    /// The provided buffer is too small to hold the requested data.
    /// Increase the buffer size and retry the operation.
    BufferTooSmall = error_codes::BUFFER_TOO_SMALL,

    /// The API was asked to assume the object under analysis is an STArray but it was not.
    /// This error occurs when trying to perform array operations on non-array objects.
    NoArray = error_codes::NO_ARRAY,

    /// The specified field is not a leaf field and cannot be accessed directly.
    /// Leaf fields are primitive types that contain actual data values.
    NotLeafField = error_codes::NOT_LEAF_FIELD,

    /// The provided locator string is malformed or invalid.
    /// Locators must follow the proper format for field identification.
    LocatorMalformed = error_codes::LOCATOR_MALFORMED,

    /// The specified slot number is outside the valid range.
    /// Slot numbers must be within the allowed bounds for the current context.
    SlotOutRange = error_codes::SLOT_OUT_RANGE,

    /// No free slots are available for allocation.
    /// All available slots are currently in use. Consider reusing existing slots.
    SlotsFull = error_codes::SLOTS_FULL,

    /// The specified slot did not contain any slotted data (i.e., is empty).
    /// This error occurs when trying to access a slot that hasn't been allocated
    /// or has been freed.
    EmptySlot = error_codes::EMPTY_SLOT,

    /// The requested ledger object could not be found.
    /// This may occur if the object doesn't exist or the ledger entry ID is invalid.
    LedgerObjNotFound = error_codes::LEDGER_OBJ_NOT_FOUND,

    /// The operation would exceed the allowed transfer limit.
    OutOfTransferLimit = error_codes::OUT_OF_TRANSFER_LIMIT,

    /// The data field is too large to be processed.
    /// Consider reducing the size of the data or splitting it into smaller chunks.
    DataFieldTooLarge = error_codes::DATA_FIELD_TOO_LARGE,

    /// A pointer or buffer length provided as a parameter described memory outside the allowed memory region.
    /// This error indicates a memory access violation.
    PointerOutOfBounds = error_codes::POINTER_OUT_OF_BOUNDS,

    /// No memory has been exported by the WebAssembly module.
    /// The module must export its memory for host functions to access it.
    NoMemoryExported = error_codes::NO_MEM_EXPORTED,

    /// One or more of the parameters provided to the API are invalid.
    /// Check the API documentation for valid parameter ranges and formats.
    InvalidParams = error_codes::INVALID_PARAMS,

    /// The provided account identifier is invalid.
    /// Account IDs must be valid 20-byte addresses in the proper format.
    InvalidAccount = error_codes::INVALID_ACCOUNT,

    /// The specified field identifier is invalid or not recognized.
    /// Field IDs must correspond to valid XRPL serialization fields.
    InvalidField = error_codes::INVALID_FIELD,

    /// The specified index is outside the valid bounds of the array or collection.
    /// Ensure the index is within the valid range for the target object.
    IndexOutOfBounds = error_codes::INDEX_OUT_OF_BOUNDS,

    /// The input provided for floating-point parsing is malformed.
    /// Floating-point values must be in the correct format for XFL operations.
    InvalidFloatInput = error_codes::INVALID_FLOAT_INPUT,

    /// An error occurred during floating-point computation.
    /// This may indicate overflow, underflow, or other arithmetic errors.
    InvalidFloatComputation = error_codes::INVALID_FLOAT_COMPUTATION,

    /// A byte slice the host returned could not be decoded into the requested type.
    /// This is NOT a host ABI code: the host reported success, and the stdlib's own decoder
    /// rejected the bytes.
    InvalidDecoding = error_codes::INVALID_DECODING,
}

impl Error {
    // TODO: Use Trait instead?
    #[inline(always)] // <-- Inline because this function is very small
    pub fn from_code(code: i32) -> Self {
        unsafe { core::mem::transmute(code) }
    }

    /// Error code
    #[inline(always)] // <-- Inline because this function is very small
    pub fn code(self) -> i32 {
        self as _
    }
}

impl From<Error> for i64 {
    fn from(val: Error) -> Self {
        val as i64
    }
}