Utilities

Convenience utilities for the XRP Ledger

exception xrpl.utils.XRPLTimeRangeException

Bases: XRPLException

Exception for invalid XRP Ledger time data.

exception xrpl.utils.XRPRangeException

Bases: XRPLException

Exception for invalid XRP amounts.

xrpl.utils.datetime_to_ripple_time(dt: datetime) → int

Convert from a datetime object to an XRP Ledger ‘Ripple Epoch’ time.

Parameters:

dt – The datetime to convert

Returns:

The equivalent time in whole seconds since the Ripple Epoch of 2001-01-01T00:00Z

Raises:

XRPLTimeRangeException – if the time is outside the range that can be represented in Ripple Epoch time

xrpl.utils.decode_mptoken_metadata(input_hex: str) → MPTokenMetadata

Decodes hex-encoded MPTokenMetadata into a JSON object.

This process performs the reverse of encoding: 1. Converts the hex string to its JSON string representation. 2. Parses the JSON string into a dictionary object. 3. Converts compact field names within the object to their corresponding

long-form equivalents.

Parameters:

input_hex – The hex encoded MPTokenMetadata string.

Returns:

The decoded MPTokenMetadata dictionary object with long field names.

Raises:

Error – If the input string is not valid hex or cannot be parsed as a JSON object after decoding.

Notes

This utility is the counterpart to the encoding function and handles field name expansion.

xrpl.utils.drops_to_xrp(drops: str) → Decimal

Convert from drops to decimal XRP.

Parameters:

drops – String representing indivisible drops of XRP

Returns:

Decimal representation of the same amount of XRP

Raises:

• TypeError – if drops not given as a string

• XRPRangeException – if the given number of drops is invalid

xrpl.utils.encode_mptoken_metadata(mptoken_metadata: MPTokenMetadata) → str

Encodes MPTokenMetadata object to a hex string.

The encoding process involves: 1. Shortening long field names to their compact form equivalents. 2. Sorting the fields alphabetically for deterministic encoding. 3. Stringify the resulting object. 4. Converting the string to its hex representation.

Parameters:

mptoken_metadata – The MPTokenMetadata object to encode.

Returns:

The hex encoded MPTokenMetadata string.

Raises:

Error – If the input is not a valid JSON-like dictionary object.

Notes

This utility ensures deterministic encoding by sorting fields.

xrpl.utils.get_balance_changes(metadata: TransactionMetadata) → List[AccountBalances]

Parse all balance changes from a transaction’s metadata. Does not include MPT balance.

Parameters:

metadata – Transactions metadata.

Returns:

All balance changes caused by a transaction. The balance changes are grouped by the affected account addresses.

xrpl.utils.get_final_balances(metadata: TransactionMetadata) → List[AccountBalances]

Parse all final balances from a transaction’s metadata.

Parameters:

metadata – Transactions metadata.

Returns:

All final balances caused by a transaction. The final balances are grouped by the affected account addresses.

xrpl.utils.get_nftoken_id(meta: TransactionMetadata) → str | None

Gets the NFTokenID for an NFT recently minted with NFTokenMint.

Parameters:

meta – Metadata from the response to submitting an NFTokenMint transaction.

Returns:

The newly minted NFToken’s NFTokenID. None if there is no NFTokenID that was minted.

Raises:

TypeError – if given something other than metadata (e.g. the full transaction response).

xrpl.utils.get_order_book_changes(metadata: TransactionMetadata) → List[AccountOfferChanges]

Parse all order book changes from a transaction’s metadata.

Parameters:

metadata – Transactions metadata.

Returns:

All offer changes caused by the transaction. The offer changes are grouped by their owner accounts.

xrpl.utils.get_xchain_claim_id(meta: TransactionMetadata) → str

Gets the XChainClaimID from a recently-submitted XChainCreateClaimID transaction.

Parameters:

meta – Metadata from the response to submitting an XChainCreateClaimID transaction.

Returns:

The newly created XChainClaimID.

Raises:

TypeError – if given something other than metadata (e.g. the full transaction response).

xrpl.utils.hex_to_str(input: str) → str

Convert a hex string into a human-readable string. XRPL uses hex strings as inputs in fields like domain in the AccountSet transaction.

Parameters:

input – hex-encoded string to convert

Returns:

Input encoded as a human-readable string.

xrpl.utils.parse_nftoken_id(nft_id: str) → NFTokenID

Parse an NFTokenID into the information it is encoding.

Example decoding:

000B 0539 C35B55AA096BA6D87A6E6C965A6534150DC56E5E 12C5D09E 0000000C +— +— +————————————— +——- +——- | | | | | | | | | `—> Sequence: 12 | | | | | | | `—> Scrambled Taxon: 314,953,886 | | | Unscrambled Taxon: 1337 | | | | | `—> Issuer: rJoxBSzpXhPtAuqFmqxQtGKjA13jUJWthE | | | `—> TransferFee: 1337.0 bps or 13.37% | `—> Flags: 11 -> lsfBurnable, lsfOnlyXRP and lsfTransferable

Parameters:

nft_id – A hex string which identifies an NFToken on the ledger.

Raises:

XRPLException – when given an invalid Token ID as nft_id.

Returns:

A decoded nft TokenID with all information encoded within

# noqa:E501

xrpl.utils.posix_to_ripple_time(timestamp: int | float) → int

Convert from a POSIX-like timestamp such as one returned by time.time() to an XRP Ledger ‘Ripple Epoch’ time.

Parameters:

timestamp – An integer or floating-point timestamp such as one returned by time.time().

Returns:

The equivalent time in whole seconds since the Ripple Epoch of 2001-01-01T00:00Z

Raises:

XRPLTimeRangeException – if the time is outside the range that can be represented in Ripple Epoch time

xrpl.utils.ripple_time_to_datetime(ripple_time: int) → datetime

Convert from XRP Ledger ‘Ripple Epoch’ time to a UTC datetime object.

Parameters:

ripple_time – Whole seconds since the Ripple Epoch of 2001-01-01T00:00Z

Returns:

The equivalent time as a datetime instance.

Raises:

XRPLTimeRangeException – if the given ripple_time is not valid

xrpl.utils.ripple_time_to_posix(ripple_time: int) → int

Convert from XRP Ledger ‘Ripple Epoch’ time to a POSIX-like integer timestamp.

Parameters:

ripple_time – A timestamp as the number of whole seconds since the Ripple Epoch of 2001-01-01T00:00Z

Returns:

The equivalent time in whole seconds since the UNIX epoch of 1970-01-01T00:00Z

Raises:

XRPLTimeRangeException – if the given ripple_time is not valid

xrpl.utils.str_to_hex(input: str) → str

Convert a UTF-8-encoded string into hexadecimal encoding. XRPL uses hex strings as inputs in fields like domain in the AccountSet transaction.

Parameters:

input – UTF-8-encoded string to convert

Returns:

Input encoded as a hex string.

xrpl.utils.validate_mptoken_metadata(input_hex: str) → List[str]

Validates if MPTokenMetadata adheres to XLS-89d standard.

Parameters:

input_hex (str) – Hex encoded MPTokenMetadata.

Returns:

A list messages indicating deviations from the standard.

Return type:

List[str]

xrpl.utils.xrp_to_drops(xrp: int | float | Decimal) → str

Convert a numeric XRP amount to drops of XRP.

Parameters:

xrp – Numeric representation of whole XRP

Returns:

Equivalent amount in drops of XRP

Raises:

• TypeError – if xrp is given as a string

• XRPRangeException – if the given amount of XRP is invalid