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.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 stringXRPRangeException – 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. 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.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 stringXRPRangeException – if the given amount of XRP is invalid