xrpl_std/host/
trace.rs

1use crate::core::error_codes::match_result_code;
2
3use crate::core::types::amount::token_amount::TokenAmount;
4use crate::host;
5use crate::host::Result;
6use core::ptr;
7
8/// Data representation
9#[derive(Clone, Copy)]
10pub enum DataRepr {
11    /// As UTF-8
12    AsUTF8 = 0,
13    /// As hexadecimal
14    AsHex = 1,
15}
16
17/// Write the contents of a message to the xrpld trace log.
18///
19/// # Parameters
20/// * `msg`: A str ref pointing to an array of bytes containing UTF-8 characters.
21///
22/// # Returns
23///
24/// Returns an integer representing the result of the operation. A value of `0` or higher signifies
25/// the number of message bytes that were written to the trace function. Non-zero values indicate
26/// an error (e.g., incorrect buffer sizes).
27#[inline(always)] // <-- Inline because this function is very small
28pub fn trace(msg: &str) -> Result<i32> {
29    let null_ptr: *const u8 = ptr::null::<u8>();
30
31    let result_code = unsafe {
32        host::trace(
33            msg.as_ptr(),
34            msg.len(),
35            null_ptr,
36            0usize,
37            DataRepr::AsUTF8 as _,
38        )
39    };
40
41    match_result_code(result_code, || result_code)
42}
43
44/// Write the contents of a message to the xrpld trace log.
45///
46/// # Parameters
47/// * `msg`: A str ref pointing to an array of bytes containing UTF-8 characters.
48///
49/// # Returns
50///
51/// Returns an integer representing the result of the operation. A value of `0` or higher signifies
52/// the number of message bytes that were written to the trace function. Non-zero values indicate
53/// an error (e.g., incorrect buffer sizes).
54#[inline(always)] // <-- Inline because this function is very small
55pub fn trace_data(msg: &str, data: &[u8], data_repr: DataRepr) -> Result<i32> {
56    let result_code = unsafe {
57        let data_ptr = data.as_ptr();
58        let data_len = data.len();
59        host::trace(msg.as_ptr(), msg.len(), data_ptr, data_len, data_repr as _)
60    };
61
62    match_result_code(result_code, || result_code)
63}
64
65/// Write the contents of a message, and a number, to the xrpld trace log.
66///
67/// # Parameters
68/// * `msg`: A str ref pointing to an array of bytes containing UTF-8 characters.
69/// * `number`: A number to emit into the trace logs.
70///
71/// # Returns
72///
73/// Returns an integer representing the result of the operation. A value of `0` or higher signifies
74/// the number of message bytes that were written to the trace function. Non-zero values indicate
75/// an error (e.g., incorrect buffer sizes).
76#[inline(always)]
77pub fn trace_num(msg: &str, number: i64) -> Result<i32> {
78    let result_code = unsafe { host::trace_num(msg.as_ptr(), msg.len(), number) };
79    match_result_code(result_code, || result_code)
80}
81
82#[inline(always)]
83pub fn trace_amount(msg: &str, token_amount: &TokenAmount) -> Result<i32> {
84    // TODO: instead of manually calling `trace_num`, create a new host function called
85    // `trace_amount` and call that instead.
86
87    let result_code: i32 = match token_amount {
88        TokenAmount::XRP { num_drops, .. } => unsafe {
89            host::trace_num(msg.as_ptr(), msg.len(), *num_drops)
90        },
91        TokenAmount::IOU { amount, .. } => unsafe {
92            host::trace_opaque_float(msg.as_ptr(), msg.len(), amount.0.as_ptr(), 8)
93        },
94        TokenAmount::MPT { num_units, .. } => unsafe {
95            // TODO: Consider trace_amount?
96            host::trace_num(msg.as_ptr(), msg.len(), *num_units as i64)
97        },
98    };
99
100    match_result_code(result_code, || result_code)
101}
102
103/// Write a float to the XRPLD trace log
104#[inline(always)]
105pub fn trace_float(msg: &str, f: &[u8; 8]) -> Result<i32> {
106    let result_code = unsafe { host::trace_opaque_float(msg.as_ptr(), msg.len(), f.as_ptr(), 8) };
107    match_result_code(result_code, || result_code)
108}
xrpl_std/host/trace.rs

xrpl_std/host/
trace.rs
