Add basic high-level methods

[LimpidCrypto]

Need to be done:
#17

• AsyncWebsocketClient
• Response

We should have high-level methods that predefine often used functions in combination with the public XRP Ledger Server API methods.

Structure

• Topic

  • function, structure, addition, removal, ...

    1. Short explanation of the change.

    2. Short explanation how the change works.

    3. Some particularities.

    fields	type	explanation

    Sources:

    • ...

Every function has a client argument. Its type is always only one of WebsocketClient and AsyncWebsocketClient. When writing sync high-level methods use WebsocketClient, when writing async use AsyncWebsocketClient as type.

---

• account:

  • does_account_exist -> bool

    1. Queries a ledger and checks if an account exists.

    2. The function simply calls the get_account_info function. If the Result is no error the account exists.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    ledger_index	Option<&str>	A ledger index. Must be one of "validated", "current", "closed", or an integer as str.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/main.py#L12

  • get_next_valid_account_seq_number -> u32

    1. Queries the ledger for an account to its next valid sequence number.

    2. The function simply calls the get_account_root function and returns the AccountRoot object's Sequence field.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    ledger_index	Option<&str>	A ledger index. Must be one of: "validated", "current", "closed", integer as str

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/main.py#L42

  • get_account_xrp_balance -> Currency

    1. Queries the Ledger for an account's XRP balance.

    2. The function simply calls the get_account_root function and returns the AccountRoot object's Balance field.

    3. Use drops_to_xrp to convert the drops amount into a XRP amount.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    ledger_index	Optional<&str>	A ledger index. Must be one of: "validated", "current", "closed", integer as str

    Sources:

    • https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/src/sugar/balances.ts#L43
    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/main.py#L64

  • get_account_balances -> Vec<Currency>

    1. Queries the Ledger for all balances (XRP and Token) a given account holds.

    2. The function calls the get_account_xrp_balance and the AccountLines request method and brings the balances in an easy-to-use format.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    ledger_index	Optional<&str>	A ledger index. Must be one of: "validated", "current", "closed", integer as str

    Sources:

    • https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/src/sugar/balances.ts#L77

  • get_account_root -> AccountRoot

    1. Queries the ledger for an AccountRoot object of a given address.

    2. The function simply calls the get_account_info function and returns the result's account_data field.

    3. The return type AccountRoot may not be defined yet.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    ledger_index	Option<&str>	A ledger index. Must be one of: "validated", "current", "closed", integer as str

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/main.py#L84

  • get_account_info -> Response

    1. Queries the ledger for account info of an account's address.

    2. The function calls the AccountInfo request method using the WebsocketClient/AsyncWebsocketClient.

    3. The returning Response struct may not have been added yet. Keep a look at Add clients #17, if the tick is already set.
       The user can choose which ledger he wants to query using the ledger_index argument. If no ledger_index is defined (: None) the default is "validated". If a Ledger Index is defined edit the AccountInfo request as wished.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    ledger_index	Option<&str>	A ledger index. Must be one of: "validated", "current", "closed", integer as str

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/main.py#L105
    • https://xrpl.org/account_info.html

  • get_latest_transaction -> Response

    1. Queries the Ledger for the last transaction a given account has sent.

    2. The function calls the AccountTx request method using the WebsocketClient/AsyncWebsocketClient.

    3. The returning Response struct may not have been added yet. Keep a look at Add clients #17, if the tick is already set.
       To receive an account's latest transaction define request:

       AccountTx {
         command: RequestMethod::AccountTx, // maybe obsolete; check if `<https://github.com/sephynox/xrpl-rust/issues/19)>` is closed.
         account: account,
         id: None,
         ledger_hash: None,
         ledger_index: None,
         binary: None,
         forward: None,
         ledger_index_min: None,
         ledger_index_max: -1,
         limit: 1,
         marker: None
       }

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/transaction_history.py#L10

  • get_account_transactions

    1. Queries the Ledger for transactions sent by a given address.

    2. The function calls the AccountTx request method using the WebsocketClient/AsyncWebsocketClient.

    3. If an account has send too many transactions for the node to send, the node sends as many transactions as it can and includes a marker field to tell you to how many Ledgers it looked back. You can define the marker field in AccountTx to receive the next batch of transactions.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    marker	u32	The Marker to request the next batch of transactions.

    Sources:

    • https://xrpl.org/markers-and-pagination.html#markers-and-pagination
    • https://xrpl.org/account_tx.html#account_tx
    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/transaction_history.py#L35

  • get_account_payment_transactions

    1. Queries the Ledger for transactions sent by a given address with the TransactionType Payment.

    2. The function simply calls the get_account_transactions function and filters the list of transactions for transactions with TransactionType Payment.

    fields	type	explanation
    account	&str	An accounts classic address.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    marker	u32	The Marker to request the next batch of transactions.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/account/transaction_history.py#L60

• ledger:

  • get_fee

    1. Queries the Ledger for the current transaction fee.

    2. The function calls the Fee request method using the WebsocketClient/AsyncWebsocketClient.

    3. The user can decide what type of fee to get. "open" would return the open_ledger_fee field; "minimum" would return the minimum_fee field; "dynamic" would return a calculated fee based on the node's transaction queue size.

    fields	type	explanation
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    max_fee	Option<u32>	The max fee the user want to spend as drops.
    fee_type	Option<&str>	The type of fee to return. Must be one of: "open", "minimum", "dynamic"

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/ledger/main.py#L52

  • get_latest_validated_ledger_sequence

    1. Queries the Ledger for the sequence number of the last validated Ledger.

    2. The function simply calls the Ledger request method and returns the results ledger_index field

    3. The ledger_index field must be set to "validated".

    fields	type	explanation
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/ledger/main.py#L12

  • get_latest_open_ledger_sequence

    1. Queries the Ledger for the sequence number of the last open Ledger.

    2. The function simply calls the Ledger request method and returns the results ledger_index field

    3. The ledger_index field must be set to "open".

    fields	type	explanation
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/ledger/main.py#L32

• transaction:

  • get_transaction_from_hash

    1. Queries the Ledger for a transaction using the given transaction hash.

    2. The function simply calls the Tx request method using the WebsocketClient/AsyncWebsocketClient.

    fields	type	explanation
    txn_hash	&str	The transaction hash.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    binary	Option<bool>	A boolean to determine wether to return the transaction as binary serialized to hexadecimal strings or as JSON.
    min_ledger	Option<u32>	A Ledger Index to begin search.
    max_ledger	Option<u32>	A Ledger Index to search up to.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/transaction/ledger.py#L10
    • https://xrpl.org/tx.html

  • sign_transaction

    1. Signs a transaction locally.

    3. If check_fee is None, check_fee is True.

    fields	type	explanation
    transaction	Transaction	The transaction that needs to get signed
    wallet	Wallet	The wallet used to sign the transaction.
    check_fee	Option<bool>	Bool if the provided fee defined in the transaction could be lower.

  • sign_and_submit_transaction

    1. Signs a transaction locally and submits it to the network.

    2. Simply calls the sign_transaction function and uses the submit request method to submit the transaction to the network using the WebsocketClient/AsyncWebsocketClient.

    fields	type	explanation
    transaction	Transaction	The transaction that needs to get signed
    wallet	Wallet	The wallet used to sign the transaction.
    check_fee	Option<bool>	Bool if the provided fee defined in the transaction could be lower.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.

  • autofill_and_sign_transaction

    1. Autofills and locally signs a transaction.

    2. Autofills fields like fee and signs the given transaction locally by calling sign_transaction.

    3. The method should have a parameter to choose the get_fee calculation type. This Parameter should be optional. If None the default value should be FeeType::Open.

    fields	type	explanation
    transaction	Transaction	The transaction that needs to get signed
    wallet	Wallet	The wallet used to sign the transaction.
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    fee_type	Option<FeeType>	A enum to determine the fee calculation type.

  • submit_transaction -> Response

    1. Submits a signed transaction to the XRP Ledger.

    2. Turns a transaction into a transaction blob and uses the SubmitOnly request method to submit it using the client.

    fields	type	explanation
    transaction	Transaction	The transaction that needs to get signed
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/transaction/main.py#L120

  • send_reliable_submission -> Response

    1. Submits a transaction to the XRP Ledger and waits until it got a result from the Ledger back.

    2. Calls the submit_transaction and waits until get_transaction_from_hash returns a validated transaction.

    fields	type	explanation
    transaction	Transaction	The transaction that needs to get signed
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.

    Sources:

    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/transaction/reliable_submission.py#L60

• wallet:

  • generate_faucet_wallet

    1. Generates a random wallet and funds it with some amount of XRP (usually 1000 XRP).

    2. The function uses the destination field to tell what account to fund.

    fields	type	explanation
    client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
    wallet	Option<Wallet>	A wallet object to fund.
    custom_faucet_host	Option<&str>	A custom faucet network to use.

    Sources:

    • https://xrpl.org/xrp-testnet-faucet.html
    • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/wallet/wallet_generation.py
    • https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/src/Wallet/fundWallet.ts

All these functions should be async. But we should have sync functions which simply call the async ones.

[LimpidCrypto]

For clarity reasons, every topic (account, ledger, …) gets its own issue.