DOCSEARCHbyAlgolia
Submit Docs

xrpl-py Python Library

repository·main·Indexed 42 days ago

https://github.com/xrplf/xrpl-py

A complete pure Python library for interacting with the XRP Ledger. It provides native Python models for transaction serialization, signing, and network communication via JsonRpcClient and WebsocketClient. Features include key and wallet management, account inspection, asynchronous API support via asyncio, and optional Beta support for Confidential Multi-Purpose Tokens (MPT) via the xrpl-py-confidential add-on for ElGamal encryption and zero-knowledge proofs.

Tokens
18K
Snippets
64
Records
86
Agent score
53%

What's inside xrpl-py

  1. Overview of xrpl-py features

    main

    The xrpl-py library provides a pure Python implementation for interacting with the XRP Ledger. Key capabilities include:

    • Key and wallet management: Tools for handling accounts and keys.
    • Serialization and Signing: Simplifies the complex process of encoding transactions and signing them with private keys.
    • Network Clients: Access to the XRP Ledger via xrpl.clients.
    • Account Inspection: Native methods for querying account states via xrpl.account.
    • Core Codecs: Encoding and decoding of addresses and other XRPL objects via xrpl.core.
    • Transaction Models: Native Python models for all standard XRP Ledger transactions.

  2. Overview of xrpl-py

    main

    The xrpl-py library is a pure Python implementation for interacting with the XRP Ledger. It simplifies complex interactions such as serialization and transaction signing by providing native Python methods and models for:

    • XRP Ledger transactions: Models for various transaction types.
    • Core server API objects: Interfaces for interacting with rippled server objects.

  3. Use XRPL Core Codecs for signing, serialization, and key generation

    main

    The xrpl.core package provides essential low-level functionality for interacting with the XRP Ledger. It is composed of three primary codecs:

    • xrpl.core.addresscodec: Handles XRPL address encoding and decoding.
    • xrpl.core.binarycodec: Manages the serialization and deserialization of XRPL data into binary formats.
    • xrpl.core.keypairs: Provides tools for key generation, managing keypairs, and signing transactions.

  4. Use XRPL Models for data validation

    main

    The xrpl.models package provides a suite of classes used to validate the formats of all data sent to or received from the XRP Ledger. These models ensure that your requests, transactions, and responses adhere to the expected XRPL schemas.

    Key model categories include:

    • Amounts: Models for representing different value types.
    • Currencies: Models for handling currency-specific data.
    • Requests: Models for XRPL request objects.
    • Transactions: Models for various transaction types, including pseudo-transactions.
    • Responses: Models for data returned by the ledger.

  5. Use the Base Transaction Model to prepare XRPL transactions

    main
    The xrpl.models.transactions.transaction.Transaction class serves as the base model for all XRP Ledger transactions. You can use this class to define the common structure required for any transaction before specializing it into a specific transaction type. It provides the foundation for fields that are shared across different transaction models in the XRPL ecosystem.

  6. Confidential MPT (XLS-0096) support

    main

    For Confidential Multi-Purpose Token (MPT) support, use the optional xrpl-py-confidential add-on.

    While the transaction models for confidential transfers are included in the core xrpl-py package, the xrpl-py-confidential package is required for ElGamal encryption and zero-knowledge proof generation.

    Note: This feature is currently in Beta.

  7. Use asynchronous xrpl-py with asyncio

    main

    The library provides an asynchronous version of its API in the xrpl.asyncio module. If you are using asyncio, you must use the asynchronous versions of methods (e.g., AsyncJsonRpcClient, xrpl.asyncio.transaction.submit_and_wait) instead of the synchronous ones to avoid event loop conflicts.

    Every synchronous method has a corresponding asynchronous counterpart.

    import asyncio
from xrpl.models.transactions import Payment
from xrpl.asyncio.transaction import sign, submit_and_wait
from xrpl.asyncio.ledger import get_latest_validated_ledger_sequence
from xrpl.asyncio.account import get_next_valid_seq_number
from xrpl.asyncio.clients import AsyncJsonRpcClient

async_client = AsyncJsonRpcClient(JSON_RPC_URL)

async def submit_sample_transaction():
    current_validated_ledger = await get_latest_validated_ledger_sequence(async_client)

    my_tx_payment = Payment(
        account=test_wallet.address,
        amount="2200000",
        destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
        last_ledger_sequence=current_validated_ledger + 20,
        sequence=await get_next_valid_seq_number(test_wallet.address, async_client),
        fee="10",
    )
    
    # In async mode, submit_and_wait can take the transaction directly
    tx_response = await submit_and_wait(my_tx_payment, async_client, test_wallet)

asyncio.run(submit_sample_transaction())

  9. Sign and submit transactions

    main

    The xrpl.transaction module provides three primary ways to handle transaction authorization and submission:

    1. sign_and_submit: Signs a transaction locally and submits it. Warning: This does not implement reliable submission best practices; use only for development/testing.
    2. sign: Signs a transaction locally but does not submit it to the network.
    3. submit_and_wait: The recommended method for production. It implements reliable transaction submission guidelines by submitting a signed transaction and verifying its inclusion in a validated ledger.

    To use submit_and_wait, you must first sign the transaction using sign.

    from xrpl.models.transactions import Payment
from xrpl.transaction import sign, submit_and_wait
from xrpl.ledger import get_latest_validated_ledger_sequence
from xrpl.account import get_next_valid_seq_number

# 1. Prepare
my_tx_payment = Payment(
    account=test_wallet.address,
    amount="2200000",
    destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
    last_ledger_sequence=current_validated_ledger + 20,
    sequence=get_next_valid_seq_number(test_wallet.address, client),
    fee="10",
)

# 2. Sign
my_tx_payment_signed = sign(my_tx_payment, test_wallet)

# 3. Submit
tx_response = submit_and_wait(my_tx_payment_signed, client)

  10. Use asyncio for asynchronous XRPL operations

    main

    The xrpl-py library provides full support for Python's asyncio implementation. For every synchronous method available in the library, there is an equivalent asynchronous method located in the xrpl.asyncio module.

    Important Constraint: Due to how asyncio event loops are managed, you cannot call synchronous methods from within asynchronous code. If you are writing an async function or working within an event loop, you must use the corresponding methods from the xrpl.asyncio submodules (such as xrpl.asyncio.clients, xrpl.asyncio.account, etc.) to avoid blocking the loop or causing errors.