FieldGetter

xrpl_wasm_stdlib::core::ledger_objects

Trait FieldGetter 

Source 
pub trait FieldGetter: Sized {
    // Required methods
    fn get_from_current_ledger_obj(field_code: i32) -> Result<Self>;
    fn get_from_current_ledger_obj_optional(
        field_code: i32,
    ) -> Result<Option<Self>>;
    fn get_from_ledger_obj(register_num: i32, field_code: i32) -> Result<Self>;
    fn get_from_ledger_obj_optional(
        register_num: i32,
        field_code: i32,
    ) -> Result<Option<Self>>;
}
Expand description

Trait for types that can be retrieved from ledger object fields.

This trait provides a unified interface for retrieving typed data from XRPL ledger objects, replacing the previous collection of type-specific functions with a generic, type-safe approach.

§Supported Types

The following types implement this trait:

  • u16 - 16-bit unsigned integers (2 bytes)
  • u32 - 32-bit unsigned integers (4 bytes)
  • u64 - 64-bit unsigned integers (8 bytes)
  • AccountID - 20-byte account identifiers
  • Amount - XRP amounts and token amounts (variable size, up to 48 bytes)
  • Hash128 - 128-bit cryptographic hashes (16 bytes)
  • Hash256 - 256-bit cryptographic hashes (32 bytes)
  • Blob<N> - Variable-length binary data (generic over buffer size N)

§Usage Patterns

use xrpl_wasm_stdlib::core::ledger_objects::{ledger_object, current_ledger_object};
use xrpl_wasm_stdlib::core::types::account_id::AccountID;
use xrpl_wasm_stdlib::sfield;

fn example() {
  let slot = 0;
  // Get a required field from a specific ledger object
  let balance: u64 = ledger_object::get_field(slot, sfield::Balance).unwrap();
  let account: AccountID = ledger_object::get_field(slot, sfield::Account).unwrap();

  // Get an optional field from the current ledger object
  let flags: Option<u32> = current_ledger_object::get_field_optional(sfield::Flags).unwrap();
}

§Error Handling

  • Required field methods return Result<T> and error if the field is missing
  • Optional field methods return Result<Option<T>> and return None if the field is missing
  • All methods return appropriate errors for buffer size mismatches or other retrieval failures

§Safety Considerations

  • All implementations use appropriately sized buffers for their data types
  • Buffer sizes are validated against expected field sizes where applicable
  • Unsafe operations are contained within the host function calls

Required Methods§

Source

fn get_from_current_ledger_obj(field_code: i32) -> Result<Self>

Get a required field from the current ledger object.

§Arguments
  • field_code - The field code identifying which field to retrieve
§Returns

Returns a Result<Self> where:

  • Ok(Self) - The field value for the specified field
  • Err(Error) - If the field cannot be retrieved or has unexpected size
Source

fn get_from_current_ledger_obj_optional(field_code: i32) -> Result<Option<Self>>

Get an optional field from the current ledger object.

§Arguments
  • field_code - The field code identifying which field to retrieve
§Returns

Returns a Result<Option<Self>> where:

  • Ok(Some(Self)) - The field value for the specified field
  • Ok(None) - If the field is not present
  • Err(Error) - If the field cannot be retrieved or has unexpected size
Source

fn get_from_ledger_obj(register_num: i32, field_code: i32) -> Result<Self>

Get a required field from a specific ledger object.

§Arguments
  • register_num - The register number holding the ledger object
  • field_code - The field code identifying which field to retrieve
§Returns

Returns a Result<Self> where:

  • Ok(Self) - The field value for the specified field
  • Err(Error) - If the field cannot be retrieved or has unexpected size
Source

fn get_from_ledger_obj_optional( register_num: i32, field_code: i32, ) -> Result<Option<Self>>

Get an optional field from a specific ledger object.

§Arguments
  • register_num - The register number holding the ledger object
  • field_code - The field code identifying which field to retrieve
§Returns

Returns a Result<Option<Self>> where:

  • Ok(Some(Self)) - The field value for the specified field
  • Ok(None) - If the field is not present in the ledger object
  • Err(Error) - If the field retrieval operation failed

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§

Source§

impl FieldGetter for Amount

Implementation of FieldGetter for XRPL amount values.

This implementation handles amount fields in XRPL ledger objects, which can represent either XRP amounts (8 bytes) or token amounts (up to 48 bytes including currency code and issuer information).

§Buffer Management

Uses a 48-byte buffer to accommodate the largest possible amount representation. The Amount type handles the parsing of different amount formats internally. No strict byte count validation is performed since amounts can vary in size.

Source§

impl FieldGetter for Issue

Implementation of FieldGetter for XRPL issues.

This implementation handles issue fields in XRPL ledger objects. Supports all three Issue variants: XRP, IOU, and MPT.

§Buffer Management

Uses a 40-byte buffer to accommodate all Issue types:

  • XRP: 20 bytes (all zeros)
  • IOU: 40 bytes (20 bytes currency + 20 bytes issuer)
  • MPT: 24 bytes (4 bytes sequence + 20 bytes issuer)

The implementation detects the Issue type based on the number of bytes returned from the host function.

Source§

impl FieldGetter for AccountID

Implementation of FieldGetter for XRPL account identifiers.

This implementation handles 20-byte account ID fields in XRPL ledger objects. Account IDs uniquely identify accounts on the XRPL network and are derived from public keys using cryptographic hashing.

§Buffer Management

Uses a 20-byte buffer (ACCOUNT_ID_SIZE) and validates that exactly 20 bytes are returned from the host function. The buffer is converted to an AccountID using the From<[u8; 20]> implementation.

Source§

impl FieldGetter for Currency

Implementation of FieldGetter for XRPL currency codes.

This implementation handles 20-byte currency code fields in XRPL ledger objects. Currency codes uniquely identify different currencies and assets on the XRPL.

§Buffer Management

Uses a 20-byte buffer and validates that exactly 20 bytes are returned from the host function to ensure data integrity.

Source§

impl FieldGetter for Hash128

Implementation of FieldGetter for 128-bit cryptographic hashes.

This implementation handles 16-byte hash fields in XRPL ledger objects. Hash128 values are commonly used for shorter identifiers and checksums in XRPL, such as email hashes.

§Buffer Management

Uses a 16-byte buffer (HASH128_SIZE) and validates that exactly 16 bytes are returned from the host function to ensure data integrity.

Source§

impl FieldGetter for Hash256

Implementation of FieldGetter for 256-bit cryptographic hashes.

This implementation handles 32-byte hash fields in XRPL ledger objects. Hash256 values are widely used throughout XRPL for transaction IDs, ledger indexes, object IDs, and various cryptographic operations.

§Buffer Management

Uses a 32-byte buffer (HASH256_SIZE) and validates that exactly 32 bytes are returned from the host function to ensure data integrity.

Source§

impl<T: FixedSizeFieldType> FieldGetter for T

Generic implementation of FieldGetter for all fixed-size unsigned integer types.

This single implementation handles u8, u16, u32, and u64 by leveraging the FixedSizeFieldType trait. The implementation:

  • Allocates a buffer of the appropriate size
  • Calls the host function to retrieve the field
  • Validates that the returned byte count matches the expected size
  • Converts the buffer to the target type

§Buffer Management

Uses MaybeUninit for efficient stack allocation without initialization overhead. The buffer size is determined at compile-time via the SIZE constant.

Source§

impl<const N: usize> FieldGetter for Blob<N>

Implementation of FieldGetter for variable-length binary data.

This implementation handles blob fields in XRPL ledger objects, which can contain arbitrary binary data such as memos, signatures, public keys, and other variable-length content.

§Buffer Management

Uses a buffer of size N to accommodate blob field data. The actual length of the data is determined by the return value from the host function and stored in the Blob’s len field. No strict byte count validation is performed since blobs can vary significantly in size.

§Type Parameters

  • N - The maximum capacity of the blob buffer in bytes