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.create_cross_chain_payment(payment: Payment, dest_account: str) → Payment

Creates a cross-chain payment transaction.

Parameters:

  • payment – The initial payment transaction. If the transaction is signed, then it will need to be re-signed. There must be no more than 2 memos, since the first memo is used for the sidechain destination account. The destination must be the sidechain’s door account.

  • dest_account – The destination account on the sidechain.

Returns:

A cross-chain payment transaction, where the mainchain door account is the

Destination and the destination account on the sidechain is encoded in the memos.

Raises:

XRPLException – If there are more than 2 memos.

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.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.get_balance_changes(metadata: TransactionMetadata) → List[AccountBalances]

Parse all balance changes from a transaction’s metadata.

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_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.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.posix_to_ripple_time(timestamp: Union[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.xrp_to_drops(xrp: Union[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